Latest update: 22.03.2024

This document describes each endpoint available with the Efecte REST API v1. This is a technical interface description - please find the REST API overview here.

Accessing Data Cards

GET /dc/{templateCode}/data

Get all data cards by template code – returns paginated list of data card-information by given template.

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

Empty results and paging

When no data cards match the request, the endpoint returns 200 OK with an empty data array and meta.count set to 0:

{
  "meta": {
    "count": 0,
    "limit": 50,
    "links": {
      "next": ""
    }
  },
  "data": []
}

Continue requesting pages with the URL in meta.links.next until that value is empty. The last page that contains data can still include a next link, for example when the number of matching data cards is an exact multiple of limit. Requesting that link returns 200 OK with an empty data array and an empty next value. Do not stop paging only because a page is empty or shorter than limit while next still contains a URL.

The endpoint returns 404 Not Found when the template does not exist, when the calling user cannot read the template, or when the template is a system template.

Aggregation in the filter

On GET /dc/{templateCode}/data, the filter parameter does not support GROUP BY or the aggregate functions count, sum, avg, max, and min. A request that includes any of them returns 400 Bad Request. The message field of the error response begins with "Aggregation (GROUP BY / count, sum, avg, max, min) is not supported by the data card list endpoint". Use the filter to select rows only.

GET /dc/{templateCode}/data/stream

Returns all available data cards by streaming. For complex and heavy operations streaming results could provide faster and more efficient results than getting paginated data.

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

PUT /dc/{templateCode}/data

Create or edit multiple data cards

REQUEST

PATH PARAMETERS

Example

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

BODY

[

 {

   "folderCode": "incident_management",

   "dataCardId": "12345",

   "data": {

     "description": {

       "values": [

         {

           "value": "Updating incident"

         }

       ]

     },

     "description": {

       "values": [

         {

           "value": "Description"

         }

       ]

     }

   }

 },

 {

   "folderCode": "incident_management",

   "data": {

     "description": {

       "values": [

         {

           "value": "Creating a new incident"

         }

       ]

     }

   }

 }

]

POST /dc/{templateCode}/data

Create a new data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

BODY

 {

   "folderCode": "incident_management",

   "data": {

     "description": {

       "values": [

         {

           "value": "Creating incident"

         }

       ]

     },

     "description": {

       "values": [

         {

           "value": "Description"

         }

       ]

     }

   }

 }

GET /dc/{templateCode}/data/{dataCardId}

Get a single data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

DELETE /dc/{templateCode}/data/{dataCardId}

Delete a single data card

REQUEST

PATH PARAMETERS

Example

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

PATCH /dc/{templateCode}/data/{dataCardId}

Edit existing data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

PATCH https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

BODY

{

   "folderCode": "incident_management",

   "data": {

     "description": {

       "values": [

         {

           "value": "Creating incident"

         }

       ]

     },

     "description": {

       "values": [

         {

           "value": "Description"

         }

       ]

     }

   }

 }

GET /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Get attribute from data card

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

PUT /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Update attribute from data card

REQUEST

PATH PARAMETERS

Example

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

BODY

{

 "values": [

   {

     "value":"Updating subject"

   }

 ]

}

POST /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Add value to attribute from data card

REQUEST

PATH PARAMETERS

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

BODY

{

 "values": [

   {

     "value":"Adding value to subject"

   }

 ]

}

DELETE /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Clear value of attribute from data card.

REQUEST

PATH PARAMETERS

Example

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

GET /dc/{templateCode}/data/{dataCardId}/{attributeCode}/file/{locationOfExternalData}

Download attachment from data card.

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01

POST /dc/{templateCode}/data/{dataCardId}/{attributeCode}/file

Upload attachment to data card.

REQUEST

PATH PARAMETERS

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01 -H "Content-Type: multipart/form-data" -F "fileName=example.png" -F "fileUpload=example.png;type=image/png"

Comments

You can read and add the comments of a Comment handler attribute through the REST API. You cannot replace an existing comment with a PUT request.

Read comments

Send a GET request to /dc/{templateCode}/data/{dataCardId}/{attributeCode}. The response lists the comments of the attribute, newest first. Each comment contains the fields value, author, commentType, and date. The author is the name of the person who wrote the comment, and date is the time when the comment was created in Pro ESM.

Add comments

Send a POST request to /dc/{templateCode}/data/{dataCardId}/{attributeCode}. Put one or more comments in the values array:

{
  "values": [
    { "value": "Text of the comment" }
  ]
}

Pro ESM assigns the author from the user who sends the request and sets the creation time to the server time. Do not include author, date, or commentType in the request. The request fails with status 400 if any of these fields is present, or if a comment is empty.

Delete comments

A DELETE request to /dc/{templateCode}/data/{dataCardId}/{attributeCode} removes all comments of the attribute. You cannot delete a single comment. The request needs permission to update the attribute and the template, and it is subject to the data card lock.

Data card lock

If the data card is locked, a POST request returns status 409. The request succeeds without a lock check when the Comment attribute has the Ignore data card lock (true/false) option set to true. The platform setting external.api.check.lock.on.datacard is enabled by default. When you disable it, the REST API does not check the lock for any request. Setting names and availability can change between versions.

To save the parent data card together with the comment, add the query parameter forceDataCardSave=true. Such a request is subject to the lock check even when the Ignore data card lock (true/false) option is enabled.

Accessing Templates

GET /dc

Get list of all templates.

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc

GET /dc/{templateCode}

Get template by code.

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident

How to Test the Interface

GET /echo

Returns the content of "message" query parameter. For testing purposes.

REQUEST

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

GET /echo/jwt

Returns the content of "message" query parameter if JWT-token is valid. For testing purposes.

REQUEST

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

Troubleshooting

REST API Errors

In case of any errors - caused for example, by failed authorization, erroneous parameters or a badly formatted query – the API will respond with standardized error-response:

 {

 "code": 401,

 "message": "Token was empty or not provided. Token should be provided in AUTHORIZATION header.",

 "error": "Unauthorized",

 "url": "https://efecte.efectecloud.com/itsm/api/v1/dc/incident/data?limit=50&filterId=0",

 "timestamp": "2021-12-21T11:41:22Z"

}

The response will always include “code”, “error”, “url” and “timestamp” and in most of the cases “message”, giving details about the underlying issue.

Possible Errors

Can’t acquire JWT-token from login-endpoint

To get a JWT-token, the user used for login needs to have a role assigned with permission to ‘External API’ -module. If the user does not have the permissions for the External API-module, the login-endpoint response will contain information about insufficient permissions.
If you get unauthorized-response even though the username and password are correct and the role has the right permissions, make sure the account is local ESM-account.

Attribute isn’t nullable and if you send a “” as value, field isn't empty anymore

String-type attribute contains the following options: string |number | date

With StaticValue:

• Value - string
• code - string
• nullable - True

Therefore, if you want empty attribute value via REST API, use this syntax:

"email": {

           "values": [

               {

                   "value": null

               }

           ]

       }