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:
https://<serverAddress>/rest/<tenant-id>/ces?layout=<list-of-record-properties>&type=<record-type>&system=<external-system-name>&time=<last=update-time>&skip=<offset>&size=<page-size>
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:
https://<serverAddress>/rest/<tenant-id>/ces/<record-id>?layout=<list-of-record-properties>&type=<record-type>&system=<external-system-name>
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:
GET http://.../rest/100000001/ces/16116?layout=Id,Description,ImpactScope,IncidentAttachments,
RegisteredForActualService.DisplayLabel &type=Incident&system=SM
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:
https://<serverAddress>/rest/<tenant-id>/ces/attachment/<attachment-id>
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:
https://<serverAddress>/rest/<tenant-id>/ces
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:
| One to one, One to many relationships | Many to many asymmetric relationships | Many to many relationships to records of the same type | |
|---|---|---|---|
| Related record ID |
Set relationship to related record specified by ID. Syntax: RelationName:Id Example: RegisteredForActualService: 20132 |
Set relationship to a list of related records specified by IDs. Syntax: RelationName: [Id-1, Id-2, …, Id-n] Example: DeviceAffectedByIncident: [11534, 11535] |
Set relationship to a list of related records specified by Ids. The relationship side of RelationName corresponding to the related records must be specified (< = left side, > = right side). Syntax: RelationName(<|>): [Id-1, Id-2, …, Id-n] Example: IncidentCausedByIncident<: [12324, 12327] |
| Related record property value |
Set relationship to a related record specified by a value of a property on the related record. Syntax: RelationName.Property:Value Example: RegisteredForActualService.DisplayLabel: Catalog |
Set relationship to a list of related record specified by the values of a property on the related records. Syntax: RelationName.Property: [Value-1, Value-2, …, Value-n] Example: DeviceAffectedByIncident.DisplayLabel: [SERV02SD059, SERV02SD063] |
Set relationship to a list of related records specified by the values of a property on the related records. The relationship side of RelationName corresponding to the related entities must be specified (< = left side, > = right side). Syntax: RelationName(<|>).Property": [Value-1, Value-2, …, Value-n] Example: IncidentCausedByIncident<.Category: [12345, 12346] |
| Related record related property value |
Set relationship to a related record specified by the value of a related property on the related record. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) Syntax: RelationName.RelatedEntityRelationName.Property :Value Example: RegisteredForActualService.SupportLevel1Group.Name: CAB Group |
Set relationship to a list of related records specified by the values of a related property of the related records. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) Syntax: RelationName.RelatedEntityRelationName.Property: [Value-1, Value-2, …, Value-n] Example: DeviceAffectedByIncident.SupportLevel1Group.Name: [CAB Group] |
Set relationship to a list of related records specified by the values of a related property on the related records. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) The relationship side of RelationName corresponding to the related entities must be specified (< = left side, > = right side). Syntax: RelationName(<|>).RelatedEntityRelationName.Property: [Value-1, Value-2, …, Value-n] Example: IncidentCausedByIncident<.Category.DisplayLabel: [Category-1, Category-2] |
Update record
Enter the following POST request URI:
https://<serverAddress>/rest/<tenant-id>/ces
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:
| One to one, One to many relationships | Many to many asymmetric relationships | Many to many relationships to records of the same type | |
|---|---|---|---|
| Related record ID |
Update relationship to related record specified by ID or to null. Syntax: RelationName:Id | null Example: RegisteredForActualService: 2013,Category: null |
Update the existing set of related records by adding and/or deleting a list of related records specified by IDs. You can specify Add only, Delete only, or both. Syntax: RelationName: {add: [Id-add-1, Id-add-2, …, Id-add-n], delete: [Id-del-1, Id-del-2, …, Id-del-m]} Example: DeviceAffectedByIncident: {add: [11534, 11535, 11536], delete: [11537, 11538]} |
Update the existing set of related records by adding and/or deleting a list of related records specified by IDs. You can specify Add only, Delete only, or both. The relationship side of RelationName corresponding to the related records must be specified (< = left side, > = right side). Syntax: RelationName: {add: [Id-add-1, Id-add-2, …, Id-add-n], delete: [Id-del-1, Id-del-2, …, Id-del-m]} Example: IncidentCausedByIncident<: {add : [12324, 12327], delete: [12328]} |
| Related record property value |
Update relationship to a related record specified by a value of a property on the related record. Syntax: RelationName.Property:Value Example: RegisteredForActualService.DisplayLabel: Catalog |
Update the existing set of related records by adding and/or deleting a list of related records specified by the values of a property on the related records. You can specify Add only, Delete only, or both. Syntax: RelationName.Property: {add: [Value-add-1, Value-add-2, …, Value-add-n], delete: [Value-del-1, Value-del-2, …, Value-del-m]} Example: DeviceAffectedByIncident.DisplayLabel: {add: [SERV02SD059, SERV02SD063, SERV02SD064], delete: [SERV02SD065, SERV02SD066]} |
Update the existing set of related records by adding and/or deleting a list of related records specified by the values of a property on the related records. You can specify Add only, Delete only, or both. The relationship side of RelationName corresponding to the related entities must be specified (< = left side, > = right side). Syntax: RelationName.Property: {add: [Value-add-1, Value-add-2, …, Value-add-n], delete: [Value-del-1, Value-del-2, …, Value-del-m]} Example: IncidentCausedByIncident<.Category: [12345, 12346] |
| Related record related property value |
Update relationship to a related record specified by the value of a related property on the related record. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) Syntax: RelationName.RelatedEntityRelationName.Property :Value Example: RegisteredForActualService.SupportLevel1Group.Name: CAB Group |
Update the existing set of related records by adding and/or deleting a list of related records specified by the values of a related property on the related records. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) Syntax: RelationName.RelatedEntityRelationName.Property: {add: [Value-add-1, Value-add-2, …, Value-add-n], delete: [Value-del-1, Value-del-2, …, Value-del-m]} Example: DeviceAffectedByIncident.SupportLevel1Group.Name: {add:[CAB Group, ECAB Group], delete: [Change Manager Group]} |
Update the existing set of related records by adding and/or deleting a list of related records specified by the values of a related property on the related records. (RelatedEntityRelationName must be a one to one or one to many relationship of the related record.) The relationship side of RelationName corresponding to the related entities must be specified (< = left side, > = right side). Syntax: RelationName.RelatedEntityRelationName.Property: {add: [Value-add-1, Value-add-2, …, Value-add-n], delete: [Value-del-1, Value-del-2, …, Value-del-m]} Example: IncidentCausedByIncident<.Category.DisplayLabel: {add: [Category-1, Category-2], delete: [Category-3]} |
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:
https://<serverAddress>/rest/<tenant-id>/ces/attachment/
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.
Note You must always provide the full list of current attachments in the IncidentAttachments property, not only the ones that have just been added.
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 are also unable to retrieve attachments via the FRS API; they must do it by using the Case exchange API.
