This section describes the Efecte Web API and 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 service we want to call. For example: https://localhost:8080/esm/search.ws or in Efecte cloud https://base_url/api/itsm/search.ws.

Before using Web API, please take a look into chapter “Authentication”, which describes authentication to Web API and provides additional information on roles and permissions. This chapter also covers how to create web API role and user. Web API user must be local ESM account, not an EIM account that is used to cloud environment logins.

There are some operations that can be slow to process. For example, usually operations that imports multi-value references takes more time compared to imports without references. Also, complicate expressions in template can take slow processing imports. You should always filter out results using where and e.g. templateCode in search.ws.

DataCardImport Service 

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 Description 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.

When updating data cards, 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.
Note that in integration purposes, a good way to handle imports is to import only one data card at time and keep traffic on reasonable level for the following reasons:

• Error inspection is easier, this way erroneous entities from import can be identified right away.
• Importing amount of data cards may cause timeouts.

HTTP parameters

Here is a list of the possible HTTP parameters that can be used (DataCardImport service HTTP parameters):

* Either folderId or folderCode has to be included in the parameters

Errors in DataCardImport

In general, if any of the required parameters (listed in Table 7) 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 5 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 <entity-import-report> containing information about handled data cards and about any errors that occurred during the import.

Values to be imported should be inside <value> element. If values are imported within <reference> elements, this will create faulty references to data card itself. If references are needed, make sure that web API user has access to template you are referring to, otherwise reference won’t be created. References must be targeted to template’s primary value.

Example Request and Response

Request

Service: dataCardImport.ws

URL example: 
https://localhost:8080/esm/dataCardImport.ws?folderCode=incident_management

Message body:

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>Test incident</value>
     </attribute>
     <attribute code="category">
       <value>Testing</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>  
</entityset>

Response

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>09.07.2018 09:03:04</start-time>
   <total-time>10,494</total-time>
   <entities-handled-per-second>0,095</entities-handled-per-second>
   <average-entity-handling-time>10,494</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Delete service

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.

HTTP Parameters

Delete service HTTP parameters:

* 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.

Example Request and Response, Deleting Data Card with Entity ID

Request

Service: delete.ws

URL example: 
https://localhost:8080/esm/delete.ws?ids=15021

Response

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Example Request and Response, Deleting Data Card Using EQL

Request

Service: delete.ws

EQL: SELECT $efecte_id$, $subject$, $status$ FROM entity WHERE entity.template.code = 'incident' AND $efecte_id$='INC-000270'

URL example: 
https://localhost:8080/esm/delete.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'%20and%20%24efecte_id%24%3D'INC-000270'

Response

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Search Service

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 Chapter 2 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 Description document. The “generic” XML format is described with examples below. Note that the generic format may include complete instances of Entity XML and Template XML, depending on the EQL query.

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 time zone. Note that if “multiple time zone support” is enabled, this may differ from Entity XML, where datetime values are adjusted to the Web service user's time zone 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-8.

If there is no need to show deleted or hidden data cards, use entity.deleted=0 or entity.hidden=0 in query parameter.

Generic Result XML

Possible datatype elements for generic search results:

HTTP Parameters

Search service HTTP parameters:

Example Request and Response, Only Returns Names of Entities

A document consisting of <string> values, directly below the <result> element, is returned in response to the simple EQL query. 

Request

Service: search.ws

EQL: SELECT entity.name FROM entity WHERE entity.folder.name = 'Incident management'

URL example: 
https://localhost:8080/esm/search.ws?query=select%20entity.name%20from%20entity%20where%20entity.folder.name%20%3D%20'Incident management'

Response

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <string>Problems in CRM</string>
   <string>Mobile phone not working</string>
   <string>Test incident</string>
   <string>API incident</string>
</result>

Example Request and Response, Using Attribute Codes of Template

When selecting several fields, the results are grouped using <row> elements. Notice that order of strings within row is same as attribute order in select (positions are bound).

Request

Service: search.ws

EQL: SELECT $efecte_id$ ,$subject$, $status$ FROM entity WHERE entity.template.code = 'incident'

URL example: 
https://localhost:8080/esm/search.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'

Response

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>INC-000270</string>
       <string> Problems in CRM </string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000273</string>
       <string>Mobile phone not working</string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000272</string>
       <string>Test incident </string>
       <string>2 - Solving</string>
   </row>
</result>

Example Request and Response, Return Folder Name and Reference Data Target

In this case, the generic result XML includes complete Entity XML documents "embedded" in it, along with simple <string> values: 
Request

Service: search.ws

EQL: SELECT entity.folder.name, entity.referenceData.target FROM entity WHERE entity.templateId = 2597

URL example: 
https://localhost:8080/esm/search.ws?query= select%20entity.folder.name%2C%20entity.referenceData.target%20from%20entity%20where%20entity.templateId%20%3D%202597

Response

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>Incident management</string>
       <entity id="14549" name="18.06.2018 09:03">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
   <row>
       <string>Incident management</string>
       <entity id="15066" name="18.06.2018 13:56">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
</result>

Example Request and Response, Return Given Attributes by Using attributeCodes

attrbuteCodes define which attributes are returned in response message. This way web API won’t return attributes that user does not need.

Request

Service: search.ws

EQL: SELECT entity FROM entity WHERE template.code='workstation'

AttributeCodes: efecte_id,workstation_model,status

URL example: 
https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,workstation_model,status&query=select%20entity%20from%20entity%20where%20template.code%20%3D%20'workstation'

Response

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19103" name="Test User">
       <template id="1622" name="Workstation" code="workstation"/>
       <group code="asset"/>
       <attribute id="1628" name="Device model" code="workstation_model">
           <reference id="19125" name="MacBook Pro 15"/>
       </attribute>
       <attribute id="1380" name="Status" code="status">
           <value>2 - In use</value>
       </attribute>
       <attribute id="1311" name="Efecte ID" code="efecte_id">
           <value>WS-000148</value>
       </attribute>
   </entity>
</entityset>

FileMetaData Service

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 display name for each attachment. Name is an internal filename (e.g. “20180717_1.xml”) 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 is more human-readable (e.g. “readme.txt”). 

HTTP Parameters

FileMetaData service HTTP parameters:

Example Request and Response

Request

Service: fileMetadata.ws

URL example:
https://localhost:8080/esm/fileMetadata.ws?entityId=15048

Response

<?xml version="1.0" encoding="utf-8"?>
<entity-attachment-metadata>
   <entity id="15048">
       <attribute id="2696" code="file_attachments">
           <attachment>
               <name>20180717_1.xml</name>
               <displayname>test.xml</displayname>
               <size>4871</size>
               <last-modified>2018-07-17 09:35:12 EEST</last-modified>
           </attachment>
       </attribute>
   </entity>
</entity-attachment-metadata>

FileDownload Service

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.

HTTP Parameters

FileDownload service HTTP parameters:

Example Request and Response

Request

Service: fileDownload.ws

URL example: 
https://localhost:8080/esm/fileDownload.ws?entityId=15048&attributeId=2696&fileName=20180717_1.xml

Response

In this case response shows data from file

<?xml version="1.0" encoding="UTF-8"?>
<inventory>
   <item>
       <title>Computer</title>
       <price>1000</price>
       <company>Customer</company>
   </item>
<inventory>

FileUpload Service

File upload service is used to upload files to an 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/form-data". It is possible to send multiple files at once, if needed. 

Data card must be created before file can be uploaded into it! FileUpload service does not create new data card.

HTTP Parameters

FileUpload service HTTP parameters:

Example Request and Response

Request

Service: fileUpload.ws 

URL example: 
https://localhost:8080/esm/fileUpload.ws?entityId=14938&attributeId=2696&operationType=set

Content-Type: multipart/form-data

Response

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180717_15.xml</name>
   </attachment>
</attachment-upload-result>

Step by Step Example of Creating Data Card and Uploading File to It

This step by step example shows all steps required to upload file from nothing. Key attributes are bolded. It consists of following steps:

1. Importing (creating) data card.
2. Querying data card’s entityId.
3. Finding out templates attributeId for file attachment attribute.
4. Uploading file to data card that was created.

First data card must be created:

Request

Service: dataCardImport.ws

URL example: 
https://localhost:8080/esm/dataCardImport.ws?folderCode=incident_management

Message body:

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>File upload test</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>
</entityset>

Response

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>04.09.2018 08:27:29</start-time>
   <total-time>0,602</total-time>
   <entities-handled-per-second>1,661</entities-handled-per-second>
   <average-entity-handling-time>0,602</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Before file can be uploaded, entityId and attributeId must be known for file attachments of data card that was just created. Below is a query that can be used to get entityId and also to validate other data:

Request

Service: search.ws

EQL: SELECT entity FROM entity WHERE template.code='incident' AND $created$>'NOW-1m' AND $created$<'NOW'
AttributeCodes: efecte_id,file_attachments,status,subject,description,created

URL example:
 https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,file_attachments,status,subject,description,created&query=select%20entity%20from%20entity%20where%20template.code%3D'incident'%20and%20%24created%24%3E'NOW-1m'%20and%20%24created%24%3C'NOW'

Response

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19221" name="File upload test">
       <template id="2597" name="Incident" code="incident"/>
       <group code="incident_management"/>
       <attribute id="2612" name="Incident ID" code="efecte_id">
           <value>INC-000275</value>
       </attribute>
       <attribute id="2623" name="Status" code="status">
           <value>1 - Untouched</value>
       </attribute>
       <attribute id="2632" name="Subject" code="subject">
           <value>File upload test</value>
       </attribute>
       <attribute id="2789" name="Created" code="created">
           <value>04.09.2018 08:27</value>
       </attribute>
   </entity>
</entityset>

AttributeId can be get, for example with following methods:

Via administration page, selecting correct template and editing attribute of which we need the attributeId. When attribute is opened, id is the digits after last /, e.g.:
https://localhost:8080/esm/EfecteFrameset.do#/admin/templates/edit/2597/2680/2696

Using search service to get template schema.

Querying template schema:

Request

Service: search.ws

EQL: SELECT template FROM template WHERE template.code='incident'

URL example:
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

Response
From response we need to find <attribute> in which <code> is attribute code of file attachment attribute and from this attribute we want to get value of <class-attribute-id>, like:

…
<attribute>
               <id>2695</id>
               <class-attribute-id>2696</class-attribute-id>
               <code>file_attachments</code>
               <name>File attachments</name>
…

Now that we have entityId and attributeId, we can upload file:

Request

Service: fileUpload.ws 

URL example: 
https://localhost:8080/esm/fileUpload.ws?entityId=19221&attributeId=2696&operationType=set

Content-Type: multipart/form-data

Response

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180904_1.xml</name>
   </attachment>
</attachment-upload-result>

Fetching Data Card Schema

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

URL example: 
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

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 define, which templates, attributes and folders the web service user may access.

Root user should not be used as a Web API user, since it has access to everything, therefore using root can be dangerous. Al though, while investigating problems with Web API, promoting Web API user to root level can be helpful just to check if there are problems with permissions or if problems are caused by Web API request itself.

Creating Web API user

• Create role and select Web API product permission.
• Add folder permissions to role.
• Add template permissions to role.
• Create web API user.
• Add user to previously created role.
• Test that you are able to do desired operations via web API. You can do this in browser with /search.ws?query=select count(id) from entity