Efecte Service Management 2015 Web API

Transcription

1 Efecte Service Management 2015 Web API Updated May 5, 2015 Efecte Corp.

2 2 (17) TABLE OF CONTENTS 1 Overview Efecte Web API DataCardImport service Delete service Search service FileMetadata service FileDownload Service FileUpload Service Fetching Data Card Schema, i.e., Template Business Day service Security Web API errors Copyright 2014 Efecte Corporation. All rights reserved. Copyright of this document is vested in Efecte Corporation. This document or any part of it may not be translated, reproduced or transmitted by any means for any purpose without permission of Efecte Corporation. This document may not be communicated to any third party without permission of Efecte Corporation. All information presented in this document is subject to change without notice and does not represent commitment on Efecte Corporation.

3 3 (17)

4 4 (17) 1 Overview The purpose of this document is to describe the Efecte Web API that is used for integrating Efecte with other systems. 2 Efecte Web API In this section we will describe the Efecte Web API that external applications use to integrate themselves with Efecte. The API is built on top of standard HTTP protocol. Efecte Web API methods are invoked from Efecte URL + /servicename, where servicename is the name of the operation. NOTE! The schema files referred to in this document can be found internally in M-Files (under Documents by Product > Efecte Integration Suite > Efecte Web API Schemas). They will also be available via Efecte Extranet in the near future. 2.1 DataCardImport service URL: datacardimport.ws Example: Put XML as the HTTP BODY and set the Content-Type as text/xml. In order to create a new data card into Efecte, user needs to invoke the datacardimport service. The service takes Data card XML as a HTTP BODY, so the caller needs to know the XML syntax and the Efecte schema for the created data card. This document does not specify the XML schema, so refer to Efecte XML Schema to get information about that. The createdatacards parameter has to be set to true when new data cards are created. In order to modify an existing data card, you need to have at least one data card field in the sent XML that is defined as unique in Efecte. Efecte then tries to match the incoming data to a data card and update the matched card. The updatedatacards parameter has to be set to true when existing data cards are modified. Note that in the update case the XML attribute values replace the existing values and those fields that do not exist in XML are kept as they are in Efecte. If you want to remove attribute values from Efecte, leave value element in the XML empty and use the removeemptyvalues parameter. Here is a list of the possible HTTP parameters that are used: Parameter Name Required Possible Values Default Desciption updatedatacards {true, false} true createdatacards {true, false} true Are matched data cards updated Are non-matched data cards created createstaticattributes {true, false} false Are new static values created createemptyreferences {true, false} false ignoreuniquechecks {true, false} false restrictupdatetofolderid Valid ID of a data card folder in Efecte Are not-matched references created as empty data cards Are the uniqueness checks for data cards fields ignored Sets the folder where data card updating is restricted to. This parameter can be added

5 5 (17) restrictupdatetofoldercode folderid X* foldercode X* Valid code of a data card folder in Efecte Valid ID of a data card folder in Efecte Valid code of a data card folder in Efecte removeemptyvalues {true, false} false version Which version of DataCardImport service should be used in response multiple times. Using the restrictupdatetofoldercode parameter is not allowed when restrictupdatetofolderid is used. Sets the folder where data card updating is restricted to. This parameter can be added multiple times. Using the restrictupdatetofolderid is not allowed when restrictupdatetofoldercode is used. Sets the folder where new imported data cards will be created Sets the folder where new imported data cards will be created If set to true, Efecte removes data card values that are denoted in the XML with empty value element. If value is 1.1, root element in returned XML will always be <response>, i.e. web-apiimport-response-1_1.xsd is used. Otherwise, web-apiimport-response.xsd is used (root element is <entity-importreport> or <error>). Table 1. Possible HTTP parameters for the DataCardImport service (* Either folderid or foldercode has to be included in the parameters) Returned XML By default, the DataCardImport service will return an XML document conforming to the schema web-api-import-response.xsd. The XML is either <entity-import-report> or a Web API error (<error>). For example, here import is successful and one data card has been created: <?xml version="1.0" encoding="utf-8"?> <entity-import-report> <start-time> :39:36</start-time> <total-time>0,414</total-time> <entities-handled-per-second>2,415</entities-handled-per-second> <average-entity-handling-time>0,414</average-entity-handling-time> <user>webapiuser</user> <entities-handled>1</entities-handled> <entities-saved>1</entities-saved> <entities-updated>0</entities-updated> <entities-created>1</entities-created>

6 6 (17) </entity-import-report> Here is an example of a case where the import fails and an error is returned because neither folderid nor foldercode parameter was included in the request: <?xml version="1.0" encoding="utf-8"?> <error> <code>efe-2012</code> <description>invalid parameters: no folderid or code found</description> </error> When parameter version has value 1.1, the DataCardImport service will return an XML document conforming to the schema web-api-import-response-1_1.xsd, in which the root element will always be <response>. For example, with version 1.1, the error message used above would be: <?xml version="1.0" encoding="utf-8"?> <response> <error> <code>efe-2012</code> <description>invalid parameters: no folderid or code found</description> </error> </response> NOTE! In general, if any of the required parameters (listed in Table 1) are missing or contain invalid values, a Web API error is returned. This is also the case with Web API authentication and authorization errors. (See chapter 3 Web API errors for more information on Web API errors.) However, if something else goes wrong during the import of some data cards (e.g., the template of imported cards is misconfigured), the DataCardImport service returns <entityimport-report> containing information about handled data cards and about any errors that occurred during the import Example: appending values to a multivalue field & the format for messages sent to Worklog handler via API If you wish to append (add) values to a multivalue field without overriding the existing values, you need to use a special parameter in the data card XML. Below you see an example of such case and the parameter is highlighted. <?xml version="1.0" encoding="utf-8"?> <entityset> <entity> <template code="template_code"/> <attribute code="unique_attribute"> <value>id </value> </attribute> <attribute code="worklog_attribute_code" append="true"> <value> </value> </attribute> </entity> </entityset> {"message": "I like cookies", "author" :"John Doe", "date" : " T09:32:170000"}

7 7 (17) 2.2 Delete service This example also shows the format of a message sent via Web API to an attribute, which has a Worklog handler. The message consists of the message, author and date and time. URL: delete.ws Example: In order to remove an existing data card from Efecte, user needs to invoke the delete service. The service can delete data cards based on two different criteria: internal data card ID (entity ID) a search query; data cards that match the query will be removed

8 8 (17) Parameter Name Required Ids x* Query x* Possible Values Default usetrashcan {true, false} false Comma-separated list of internal data card (entity) IDs, identifying data cards to be removed An EQL query specifying the data cards to be removed. The query must be such that when given to the Search web service, it would return data in the Efecte data card XML (entity XML) format, i.e. the query must be of form "select entity from entity [...]". By default, data cards are removed permanently; in other words, they are not just moved to trashcan. Setting this parameter to "true", has the effect that trashcan will be used, similarly as when normally deleting data cards through Efecte's web interface. In this mode, data cards will be only removed permanently if they already were in trashcan. Table 2. Possible HTTP parameters for the Delete service (* Either one of the two parameters (ids, query) is required. The parameters are handled in this order, and only one will be taken into account on one invocation of the service. If both ids and query parameters are specified, the service will disregard the query parameter and will only attempt to remove data cards based on the ids parameter.) 2.3 Search service URL: search.ws Example: Parameter Name Required Possible Values query x Any valid EQL query Specifies the search query Table 3. Possible HTTP parameters for the Search service Searching for Data Cards In order to search data cards Efecte offers a datacardsearch web service that takes an EQL (Efecte Query Language) query and returns the results as XML. See Efecte Query Language for more information on how to construct EQL queries. The XML returned by the search service is in one of the following three formats: Entity XML Template XML Generic XML Entity XML and Template XML are described in the Efecte XML Schema document. The generic XML format is described with examples below. Note that the the generic format may include complete instances of Entity XML and Template XML, depending on the EQL query.

9 9 (17) Date values are always returned in a format yyyy-mm-dd HH:mm:ss z, following the ISO 8601 standard. Note that time zone name is included in the end. The time zone used is always the JVM s or database s default timezone. Note that if multiple timezone support is enabled, this may differ from Entity XML, where datetime values are adjusted to the Web service user's timezone setting. In decimal numbers, a dot (.) is used as a decimal separator. The character encoding used in the response XML depends on the webservice.response.encoding framework property. Default encoding is UTF Generic result XML Possible datatype elements for single values are given in the following table. Element Notes <date> The pattern used is always yyyy-mm-dd HH:mm:ss z. <decimal> Decimal numbers; decimal separator is always "." <integer> Integer numbers <string> Many Efecte datatypes (not only text and string, but also external references, etc,) are output as strings <null> Null values are a special case. For instance, a string attribute that has a null value will not appear as <string></string> or <string>null</string>, but simply as <null/> Table 4. Possible datatype elements for generic search results Simple example A document consisting of <string> values, directly below the <result> element, is returned in response to the simple EQL query. EQL query: select entity.name from entity where entity.folder.name = 'Printer' Search web service response: <?xml version="1.0" encoding="utf-8"?> <result> <string>hp Laserjet 6L</string> <string>hp LaserJet 6L</string> <string>hp Laserjet 8150 N</string> <string>hp LaserJet III</string> <string>hp psc 2210 all-in-one</string> <string>seiko Instruments SLP220</string> <string>stork Amber-reactive</string> <string>hp DeskJet 990Cxi</string> </result>

10 10 (17) Example with several rows When selecting several fields, the results are grouped using <row> elements. EQL query: select $serialnumber$, $software_name$ from entity where entity.template.code = 'installed_software' Search web service response: <?xml version="1.0" encoding="utf-8"?> <result> <row> <integer>85730</integer> <string>matrox Graphics Software (remove only)</string> </row> <row> <integer>85730</integer> <string>microsoft Office 2000 Proofing Tools Disc 1</string> </row> <row> <integer>85730</integer> <string>microsoft Internet Explorer 6 SP1 and Internet Tools</string> </row> <row> <integer>85730</integer> <string>microsoft Office 2000 SR-1 Professional</string> </row> <row> <integer>85730</integer> <string>microsoft Office 2000 SR-1 Disc 2</string> </row> <row> <integer>85730</integer> <string>microsoft Outlook Express 6</string> </row> </result> Example with embedded Entity XML In this case, the generic result XML includes complete Entity XML documents "embedded" in it, along with simple <string> values: EQL query: select entity.folder.name, entity.referencedata.target from entity where entity.templateid = 340 Search web service response: <?xml version="1.0" encoding="utf-8"?> <result> <row> <string>desktop-integraatio</string> <entity id="565657" name="joo"> <template id="342" name="hyvin pitkäniminen testimalli" code="111"/>

11 11 (17) <group id="457" name="groupnodes"/> <attribute id="3245" name="name" code=""> <value>joo</value> </attribute> </entity> </row> <row> <string>kansio 2</string> <entity id="565660" name="hello, world"> <template id="342" name="hyvin pitkäniminen testimalli" code="111"/> <group id="457" name="groupnodes"/> <attribute id="3245" name="name" code=""> <value>hello, world</value> </attribute> </entity> </row> </result> The case of embedded Template XML is analogous with that of embedded Entity XML. 2.4 FileMetadata service Since: Efecte 4.1 patch 4108 URL: filemetadata.ws Example: File Metadata service is used to get information about the file attachments attached to a data card. If the data card contains multiple fields with attachments, information of all those attachments is returned at the same time. This makes the API less verbose. Since Efecte 4.2, the Metadata service returns not only name but also displayname for each attachment. Name is an internal filename (e.g _43.txt ) that is used as an identifier when making requests to the File Download Service (see next section). Displayname is the original name of the attachment file, which usually more human-readable (e.g. readme.txt ). Parameter Name Required Possible Values entityid x Id of any data card in the system, therefore an integer Specifies the data card whose file metadata is fetched Table 5. Possible HTTP parameters for the File Metadata service File Metadata service usage example We have a data card with ID 123. We call the metadata service with URL and receive the following XML as a result: <?xml version="1.0" encoding="utf-8"?> <entity-attachment-metadata> <entity id="123"> <attribute id="443" code="attachment_link"> <attachment> <name> _32.exe</name> <displayname>setup.exe</displayname>

12 12 (17) <size>305664</size> <last-modified> :53:44 EEST</last-modified> </attachment> <attachment> <name> _4.exe</name> <displayname>iview398.exe</displayname> <size>905216</size> <last-modified> :53:44 EEST</last-modified> </attachment> </attribute> </entity> </entity-attachment-metadata> 2.5 FileDownload Service Since: Efecte 4.1 patch 4108 URL: filedownload.ws Example: File download service is used to download files attached to data cards residing in Efecte. Files are returned in the HTTP response. The client should always first check the HTTP status code of the response. The body of the response may be interpreted as the requested file only when the status code is 200 OK. Other status codes that the service typically sets are: 400 Bad Request - if some of the required parameters are missing 403 Forbidden if the webservice user has no permissions for the specified data card or attribute 404 Not Found if the requested file is not found In these error situations, the HTTP response body is an XML error message with more detailed information. Parameter Name Required Possible Values entityid x Integer attributeid x Integer filename x String Specifies the data card where the requested file is attached Specifies the data card field where the requested file is attached Specifies the name of the requested file. This corresponds to an attachment s name element (not the displayname), as returned by the Metadata service. Table 6. Possible HTTP parameters for the File Download service 2.6 FileUpload Service Since: Efecte 4.1 patch 4108 URL: fileupload.ws Example:

13 13 (17) File upload service is used to upload files to a Efecte data card. File upload service parses HTTP requests which conform to RFC 1867, "Form-based File Upload in HTML". That is, if an HTTP request is submitted using the POST method, and with a content type of "multipart/formdata". It is possible to send multiple files at once, if needed. Parameter Name Required Possible Values entityid x Integer attributeid x Integer operationtype String Specifies the data card where the uploaded file should be attached to Specifies the data card field where the uploaded file should be attached to add means that the uploaded file is added amongst other files that may already be present in the selected field. set means that the uploaded file replaces the files already present in the selected field. The default operation is set. Table 1. Possible HTTP parameters for the File Upload service 2.7 Fetching Data Card Schema, i.e., Template Efecte data card metadata, i.e., information of what fields it can contain and their properties, can be accessed through the datacardsearch web service with an EQL query to the templates. Here is an example EQL query that selects all templates: select template from template For more information on EQL, refer to the document Efecte Query Language. 2.8 Business Day service Since: Efecte 7.0 patch URL: businessday.ws Example: Business+Hours&date= T08%3A00%3A00.000%2B02%3A00 Business day service can be used to detect when Service Desk implemented by Efecte Service Management is open. Business hours are configured by data cards of Business Ho urs - template. There must exist exactly one Business Hours data card for given name parameter in Efecte or error codes EFE-6003 (Found nothing) or EFE-6004 (Found too many) will be returned.

14 14 (17) Parameter Name Required Possible Values businesshours x String date Date in ISO8061 Specifies the name of data card for calculating the business hours. Value must be url encoded. Date to be checked. Value is in ISO8061 format and must be url encoded. If date is left blank, current date will be used. Table 8. Possible HTTP parameters for the Business Day service All parameters must be url encoded for example: Business Hours -> Business+Hours T00:00: :00 -> T08%3A00%3A00.000%2B02%3A00 Example result: <?xml version="1.0" encoding="utf-8"?> <business_day> <name> Business Hours</name> <exceptional_date>good Friday 2014, 10:30-12:30</exceptional_date> <date> t00:00: :00</date> <start_time> t10:30: :00</start_time> <end_time> t12:30: :00</end_time> </business_day> See potential errors and error codes from table 14: Business day service errors 2.9 Security Encryption HTTP basic authentication sends credentials as plaintext, so it is essential to use HTTPS Authentication Efecte web API services are authenticated by using HTTP basic authentication. You have to create the credentials to Efecte to use web services. (In Permissions tree, create a role that has permissions to use Efecte Web API Services, and add one or more users to that role.) All operations are executed with the permissions of the authenticated Efecte user. These permissions specify, e.g., which templates, attributes and folders the web service user may access. 3 Web API errors This chapter offers a brief explanation for the Efecte Web API error codes. Errors may be caused, for example, by failed authorization, erroneous parameters, or a badly formatted search query.

15 15 (17) Code Explanation 1001 User not authorized to use web services. Make sure the user belongs to a role which has product permission for Efecte Web API Efecte Web API license not found. Table 9. General authorization errors Code Explanation 2001 Error in import No parameters received Invalid parameters Invalid parameters: no folderid or code found Invalid parameters: only either folderid or code is allowed Invalid parameters: only either restrictupdatetofolderid or restrictupdatetofoldercode is allowed Target folder not found Folder defined in restrictupdatetofolderid or folderrestrictupdatetofoldercode not found User not authorized to write into target folder Error in xml-import. Table 10. Import service errors

16 16 (17) Code Explanation 3001 Invalid search query. Make sure that the request includes the query parameter. The value must be a valid EQL expression Syntax error in search query. Make sure the query parameter value is valid EQL expression. For more information on EQL, refer to the document Efecte Query Language No such class found. EQL query targeted a non-existent or unsearchable class. For more information on searchable classes, refer to the document Efecte Query Language. Table11. Search service errors Code Explanation 4001 Error in data card deletion Error in deletion: No parameters received Error in deletion: No id or query received Error in deletion: invalid id parameter Error in deletion by search query Error in deletion by search: search results should only contain entities Error in deletion by search: the query found no results Error in deletion by search: Invalid query. Table 2. Delete service errors

17 17 (17) Code Explanation 5001 Error in file operations Error in file operations: missing parameters Error in file operations: invalid parameters Error in file operations: not authorized to access entity or attribute Error in file operations: not authorized to download file Error in file operations: specified file not found File upload error. Table 3. File operation errors (FileMetadata, FileDownload, FileUpload services) Code Explanation 6001 Business Hours data card name missing missing parameter Date can't be parsed. Format is (url-encoded) ISO8601. Optional date-parameter was in wrong format and cannot be parsed as date Could not find business hours data card for given name. (Value should be url-encoded). Name may be wrong, encoded badly or user may not have permissions to that data card Found more than one business hours data cards for given name. Name of the business hours datacard must be unique. Now there exist multiple data cards for the given name. Table 4. Business Day service errors