Case Exchange REST API

Service Management provides a Case exchange REST API to exchange data between Service Management and an external system. The REST API enables you to create and update records in Service Management as well as to relate those records to records in the external system. The API is used in the preconfigured Case exchange framework with Service Manager for exchanging incident and request records. For information on the Service Manager integration, see External systems - Service Manager integration.

The following REST calls are available:

• Get multiple records. Retrieves multiple records.
• Get single record. Retrieves a specific record.
• Get attachments. Retrieves the attachments to files.
• Create record. Creates new records.

• Update record. Updates existing records.

• Add attachments. Adds attachments to files.

Get multiple records

Enter the following GET request URI:

The parameters are as follows:

• Layout. The list of record properties to retrieve.
• Type. The record type.
• System. The name of the external system as defined in the External systems under Integration Management.
• Time. The time of the last call. All records created since this time are retrieved. Enter 0 to retrieve all records.
• Skip. The offset (where the page starts). Used for pagination. The default is 0.
• Size. The maximum number of records to be retrieved (starting from offset). Used for pagination. The default is 4000.

For example, enter the following REST call to retrieve multiple incidents:

GET http://.../rest/100000001/ces?layout=Id,DisplayLabel,ImpactScope,Urgency, 
RegisteredForActualService.DisplayLabel,IncidentAttachments&type=Incident&system=SM
&time=0&skip=0&size=100

The following is the response JSON:

    {
        "entities": [
            {
                "entity_type": "Incident",
                "properties": {
                    “Id": “11385",
                    “DisplayLabel”: “Incident for Central IT”,
                    “ImpactScope”: “SingleUser”,
                    “Urgency”: “SevereDisruption”,
                    "IncidentAttachments": "{\"complexTypeProperties\":[{\"properties\":
		      {\"id\":\"e940074a-50da-45e7-aaf6-04738946d86e\",\"file_name\":\"CDP 
		      Quick Start Guide for Individuals.docx\",\"file_extension\":\"docx\",
		      \"size\":1246120,\"mime_type\":\"application/vnd.openxmlformats-
		      officedocument.wordprocessingml.document\",\"Creator\":\"devUser1\",
		      \"LastUpdateTime\":1397011728993}},{\"properties\":{\"id\":\
		      "22291a78-c529-470f-965a-8f5a6f6414bf\",\"file_name\":\
		      "Analytic_Reqs.xlsx\",\"file_extension\":\"xlsx\",\"size\":14830,
		      \"mime_type\":\"application/vnd.openxmlformats-officedocument.
		      spreadsheetml.sheet\",\"Creator\":\"devUser1\",\"LastUpdateTime\":
		      1397064286794}}]}"
                },
                "related_properties": {
                    "RegisteredForActualService": {
                        "DisplayLabel": "PC Support"
                },
                "ext_properties": {
                    "Operation": "Update",
                    "ExternalId": "External Test Incident 1",
                    "ExternalEntityType": "Incident",
                    "OperationTime": 1395428400000,
                },
                "Comments": [
                    {
                        "Name": Dave Davies,
                        "Body": Need to assign to IT
                        "CreatedTime": 1366201234968
                    }
                ],
            }
        ],
        "meta": {
            "completion_status": "OK",
            "total_count": 3
        }
    }

Get single record

Enter the following GET request URI:

The parameters are as follows:

• Record Id. The Id of the specific record to retrieve.
• Layout. The list of record properties to retrieve.
• Type. The record type.
• System. The name of the external system as defined in the External systems under Integration Management.

For example, enter the following REST call to retrieve a single incident:

The following is the response JSON:

{
    "entities": [
        {
            "entity_type": "Incident",
            "properties": {
                "ImpactScope": "SingleUser",
                "Description": "<p>Case exchange test incident</p>\n",
                "IncidentAttachments": "{\"complexTypeProperties\":[]}",
                "Id": "16116"
            },
            "related_properties": {
                "RegisteredForActualService": {
                    "DisplayLabel": "Backup - Data Center"
                }
            },
            "ext_properties": {
                "Operation": "Assign",
                "OperationTime": 1404950069913
            },
            "Comments": []
        }
    ],
    "meta": {
        "completion_status": "OK",
        "total_count": 1
    }
}

Get attachments

Enter the following GET request URI:

where the <attachment-id> parameter is taken from the response JSON in the Get single record or Get multiple records call. Make sure to include this property in the layout parameter of the Get call. In the above example for incidents, the property is: IncidentAttachments.

For example, enter the following REST call:

GET http://.../rest/100000001/ces/attachment/e940074a-50da-45e7-aaf6-04738946d86e
 

Create record

Enter the following POST request URI:

There are no parameters for this URI.

To create a new record, the Operation field must be set to Create.

For example, enter the REST call with following JSON body to create incident records:

    {
        "entities": [
            {
                "entity_type": "Incident",
   "template": "SAW Template name to apply on create (optional)",
                "properties": {
                    "DisplayLabel": "This incident opened from external system.",
                    "Description":  "Description of incident",
                    "ImpactScope": "MultipleUsers",
                    "Urgency": "SevereDisruption",
                    "RegisteredForActualService":  "20132",
                    "Category.DisplayLabel": "Cloud",
                    "DeviceAffectedByIncident.DisplayLabel": ["SERV23SD090", "SERV23SD090"],
                    "IncidentCausedByIncident<": ["20500", "20505"],
                    "IncidentCausedByIncident>": ["20510", "20515"],
                    "IncidentAttachments": "{\"complexTypeProperties\":[{\"properties\":
		      {\"id\":\"161ecd4d-0fa4-4a48-a9c8-12371561545e\",\"file_name\":
		      \"attach1.txt\",\"file_extension\":\"txt\",\"size\":26,\"mime_type\":
		      \"text/plain\",\"Creator\":\"devUser1\",\"LastUpdateTime\":
		      1398389475854}}]}"
                },
                "Comments": [
                    {   
                        "Name": "John Smith"
                        "Body": "Assigned to Central IT.",
                        "CreatedTime": "April 24, 2014 5:00 PM PST"
                    }
                ],
                "ext_properties": { 
                    "ExternalSystem": "SM",
                    "Operation": "Create",
                    "ExternalId": "IM20123",
                    "ExternalEntityType": "Incident",
                    "ExternalStatus": "Pending Vendor",
                    "URL": <optional URL to external system>,
                }
             }
         ]
    }

The following is the response JSON:

    {
        "entities": [
            {
                "entity": {
                    "entity_type": "Incident",
                    "properties": {
                        "Id": "10034"
                    }
                },
                "completion_status": "OK",
                "operation": "Create",
                "warningDetails": […],
                "errorDetails": {…}
            }
        ],
        "meta": {
            "completion_status": "OK",
            "errorDetails": {…}
        }
    }

The possible completion status values are:

• OK
• FAILED

Comments

You can add comments to a Create call by including a Comments section in the request JSON. The Name and CreatedTime parameters under each comment must be provided as strings in any format. These strings are not interpreted by Service Management but they are added to the body of the comment for identification purposes.

Comments are always added as new comment records. Older comments cannot be updated via this POST API. Comments submitted in a POST by a user are not presented back to the same user as part of a GET response.

Relationships

When setting relationships in a Create call, the following options are supported:

Update record

Enter the following POST request URI:

There are no parameters for this URI.

To update a record, the Operation field must be set to must be set to any valid operation value except Create.

For example, enter the REST call with following JSON body to update incident records:

    {
        "entities": [
            {
                "entity_type": "Incident",
                "properties": {
                    "Id": "10034",
                    "DisplayLabel": "This incident is updated from external system.",
                    "Description":  "Update of the Description of incident",
                    "ImpactScope": "SingleUser",
                    "Urgency": "NoDisruption",
                    "RegisteredForActualService":  "20135",
                    "Category.DisplayLabel": "Cloud",
                    "DeviceAffectedByIncident.DisplayLabel": {"add": ["SERV18SD018", 
                    "SERV18SD019"], "delete": ["SERV23SD090"]},
                    "IncidentCausedByIncident<": {"add": ["20600", "20605"]},
                    "IncidentCausedByIncident>": {"delete": ["20510"]},
                    "IncidentAttachments": "{\"complexTypeProperties\":[{\"properties\":
                    {\"id\":\"161ecd4d-0fa4-4a48-a9c8-12371561545e\",\"file_name\":\
                    "attach1.txt\",\"file_extension\":\"txt\",\"size\":26,\"mime_type\":\
                    "text/plain\",\"Creator\":\"devUser1\",\"LastUpdateTime\":1398389475854}},
                    {\"properties\":{\"id\":\"90166d96-031f-46b8-9a6f-02067092a552\",\
                    "file_name\":\"attach2.txt\",\"file_extension\":\"txt\",\"size\":32,\
                    "mime_type\":\"text/plain\",\"Creator\":\"devUser1\",\"LastUpdateTime\
                    ":1398389674101}}]}"
                },
                "Comments": [
                    {   
                        "Name": "John Smith"
                        "Body": "Any updates?",
                        "CreatedTime": "April 24, 2014 5:30 PM PST"
                    }
                ],
                "ext_properties": { 
                    "ExternalSystem": "SM",
                    "Operation": "Update",
                    "ExternalId": "IM20123",
                    "ExternalEntityType": "Incident",
                    "ExternalStatus": "Pending Vendor",
                    "URL": <optional URL to external system>,
                }
             }
         ]
    }

The following is the response JSON:

    {
        "entities": [
            {
               "entity": {
                    "entity_type": "Incident",
                    "properties": {
                        "Id": "10034",
                    }
                },
                "completion_status": “OK”,
                "operation": "UPDATE",
                "warningDetails": […],
                "errorDetails": {…}
            }
        ],
        "meta”: {
            "completion_status": "OK",
            "errorDetails": {…}
        }
    }

Comments

You can add comments to an Update call by including a Comments section in the request JSON. The Name and CreatedTime parameters under each comment must be provided as strings in any format. These strings are not interpreted by Service Management but they are added to the body of the comment for identification purposes.

Comments are always added as new comment records. Older comments cannot be updated via this POST API. Comments submitted in a POST by a user are not presented back to the same user as part of a GET response.

Relationships

When setting relationships in an Update call, the following options are supported:

Add attachments

To add attachments via the Case exchange REST service, you need to first upload the attachments via the attachment API. Enter the following POST request URI:

with the following JSON body:

Content-Disposition: form-data; name="files[]"; filename="<file-name>"
Content-Type: <media-type>
<Attachment body (text or binary)>

The following is an example of a response JSON:

{
	"eTag":"570b45f50d2cc11fc8de465bb6a1ac96",
       "contentLanguage":"",
       "lastModified":1439876814727,
       "contentMD5":"570b45f50d2cc11fc8de465bb6a1ac96",
       "contentType":"text/plain",
       "creator":"devUser1",
       "guid":"44067c4a-5c0a-4ca8-b2a8-b726af03d458",
       "name":"notes.txt",
       "serverTime":1439876814856,"contentEncoding":"",
       "expiredTimestamp":1439963214773,
       "success":true,
       "contentLength":819,"metadata":[]
}

Then, POST an update to the relevant property for the record type. For more information on the Update REST call, see Update record.

For example, for incidents, run a POST call to update the IncidentAttachments property, with the attachment IDs returned by the attachment API for the newly added attachments.

To delete one or more attachments, POST an update to the IncidentAttachments property with the attachment to be deleted.

Security

Configuration

Each External system record must be configured with an Authorized User property. Only users with a tenant administrator role have permission to create or update External system records, which includes setting the Authorized User.

To provide appropriate security, the following best practices are strongly recommended:

• Special Integration users should be created for external integrations. Do not use regular Service Management users.
• A different integration user should be used for each external integration.
• Integration users should be granted the minimum set of permissions necessary.

Authentication

As with other Service Management REST APIs, access to the Case exchange API requires authentication. Integration users must authenticate via the Authentication endpoint service:

/auth/authentication-endpoint/authenticate/login

For more information, see Authentication endpoint service.

Authorization

Once authenticated, the Case exchange API is restricted to the set of the Authorized Users for the External System records configured in Service Management. REST API calls from a non-authorized user are rejected.

Furthermore, separation between external integrations is also provided as follows:

• For GET calls, the authenticated user must match the Authorized User corresponding to the system URL parameter of the GET message. Therefore, each integration user is restricted to his own records only and cannot retrieve the records of a different integration.
• For POST calls, the authenticated user must match the Authorized User defined in the ExternalSystem property under ext_properties. Therefore, each integration user can only create or update records in his own integration.

By configuring integration users with the minimum permissions necessary, you also ensure that their access is limited to the Case exchange API. In particular, these users are not permitted to directly access the EMS API, they must do it by using the Case exchange API.

Related topics

• Overview of the REST API

• How to connect to the REST API

• Authentication endpoint service

• Record bulk update and collection APIs

• REST API queries

• REST API collection query protocol

• Analytics REST API

• REST API use case scenario - import REST API