Record bulk update and collection APIs
Bulk update APIs are highly recommended from a performance perspective because they reduce traffic and enable the EMS to optimize interaction with the database and increase its capacity.
Getting a record collection
To execute an HTTP GET method for a collection, the following syntax is supported:
rest/<tenant-id>/ems/<entity-type>?<query-params>
where:
tenant-id represents the tenant ID. To access the tenant ID, right-click the Launch button next to the required product on MyAccount, select Copy link address and paste it into a browser. The tenant ID is the number following TENANTID=.
entity-type represents the logical name of the record to return. Example: incident.
query-params represents query parameters compatible with the query language specifications.
Enter the following request URI:
https://<serverAddress>/rest/<tenant-id>/ems/Incident/11704?layout=SolvedTime,RegisteredForActualService,UserOptionsType,EntityModel, Urgency,KnowledgeCandidate,ClosedByPerson,ExpectedResolutionTime,TasksExecutionPlanClassify,IncidentAttachments,MajorIncident, TasksExecutionPlanInitialSupport,ImpactScope,Active,RequestedByPerson, IsDeleted,Id,TasksWorkspace,CompletionCode,CloseTime,ExplicitStakeholders,TasksInternalData, PhaseId,ProcessId,LastUpdateTime,recordedByPerson,ExternalProcessReference,OwnedByPerson, ServiceDeskGroup,ProblemCandidate,RegisteredForLocation,Solution,AssignedGroup,Escalated, GlobalId,Description,LastUpdatedByPerson,TasksExecutionPlanEscalate,Priority,Name, AllStakeholders,Status,Category,NextTargetTime,DisplayLabel,UserOptions,SolvedByPerson, EmsCreationTime,TasksExecutionPlanValidate,AssignedPerson,FirstTouch
The following is an example of the structure of the returned data in JSON format:
{
"entities": [
{
"entity_type": "Incident",
"properties": {
"RegisteredForActualService": "10938",
"Urgency": "TotalLossOfService",
"IncidentAttachments": "{\"complexTypeProperties\":[]}",
"ImpactScope": "Enterprise",
"Active": false,
"RequestedByPerson": "10426",
"IsDeleted": false,
"Id": "11704",
"CompletionCode": "NoFaultFound",
"PhaseId": "Close",
"ProcessId": "normal",
"LastUpdateTime": 1388039152247,
"OwnedByPerson": "10620",
"ServiceDeskGroup": "10649",
"Solution": "Changed the fanTry reading the following article:
<a href=\"https://{serverAddress}/saw/ess/viewResult/13422\">BlackBerry</a><br><br>
<p>sdfgsdgsdg</p>",
"Description": "<p>Everyday around lunch time my PC starts
rebooting for no apparent reason. Can you please check what's wrong? I'm getting an error
message about CPU temperature.</p>",
"Priority": "CriticalPriority",
"Name": "IM000003",
"Status": "Complete",
"Category": "10707",
"DisplayLabel": "Computer reboots for no apparent reason",
"EmsCreationTime": 1385656925089
},
"related_properties": {}
}
],
"meta": {
"completion_status": "OK"
}
}
Bulk Create/Update
For executing a Create or Update command for a collection, the following syntax is supported for the request URI:
rest/<tenant-id>/ems/bulk
where:
tenant-id represents the tenant ID. To access the tenant ID, right-click the Launch button next to the required product on MyAccount, select Copy link address and paste it into a browser. The tenant ID is the number following TENANTID=.
entity-type represents the logical name of the record to retrieve. Example: incident.
query-params represents query parameters compatible with the query language specifications.
A bulk processing request gets a JSON object which contains record and relationship data and an operation to process. A bulk may contain multiple record and relationship types but only a single operation.
The operation property specifies the bulk operation type. Supported values are: CREATE and UPDATE.
The record's JSON array contains the records to be processed. When processing an UPDATE operation, the EMS assumes that the provided properties are the subset of the record properties that need to be updated.
The relationship's JSON array contains the relationships to be processed. Each relationship entry includes the following properties:
-
name. The name of the relationship (as defined in the metadata).
-
<FirstEndPoint-Name>. The name of the first endpoint record (as a string).
-
<SecondEndPoint-Name>. The name of the second endpoint record (as a string).
Note The bulk processing order is not defined.
The following is an example of the structure of the bulk operation payload JSON format:
https://{serverAddress}/rest/{tenant-id}/ems/bulk{
"entities": [
{
"entity_type": "Incident",
"properties": {
"ImpactScope": "SingleUser",
"Active": true,
"RequestedByPerson": "10073",
"PhaseId": "Log",
"ProcessId": "normal",
"FirstTouch": true,
"Urgency": "SlightDisruption",
"RegisteredForActualService": "10916",
"ServiceDeskGroup": "10646",
"CompletionCode": null,
"DisplayLabel": "Test_Incident",
"Priority": "LowPriority",
"IncidentAttachments": "{\"complexTypeProperties\":[]}",
"Description": "<p>Test</p>"
},
"layout": "SolvedTime,RegisteredForActualService,UserOptionsType,EntityModel,Urgency,
KnowledgeCandidate,ClosedByPerson,ExpectedResolutionTime,TasksExecutionPlanClassify,
IncidentAttachments,MajorIncident,TasksExecutionPlanInitialSupport,ImpactScope,Active,
RequestedByPerson,IsDeleted,Id,TasksWorkspace,CompletionCode,CloseTime,
ExplicitStakeholders,TasksInternalData,PhaseId,ProcessId,LastUpdateTime,recordedByPerson,
ExternalProcessReference,OwnedByPerson,ServiceDeskGroup,ProblemCandidate,
RegisteredForLocation,Solution,AssignedGroup,Escalated,GlobalId,Description,
LastUpdatedByPerson,TasksExecutionPlanEscalate,Priority,Name,AllStakeholders,Status,
Category,NextTargetTime,DisplayLabel,UserOptions,SolvedByPerson,EmsCreationTime,
TasksExecutionPlanValidate,AssignedPerson,FirstTouch"
}
],
"operation": "CREATE"
}
The following is an example of the structure of the bulk operation result JSON format:
{
"entity_result_list": [
{
"entity": {
"entity_type": "Incident",
"properties": {
"Id": "20036",
"LastUpdateTime": 1388060910959
},
"related_properties": {}
},
"completion_status": "OK"
}
],
"relationship_result_list": [],
"meta": {
"completion_status": "OK"
}
}
A bulk response body contains an aggregated completion_status, which represents the overall success of the bulk operation. The status is marked as OK only if all the contained operations were processed successfully.
In addition, the response body contains a JSON object for each request element (record or relationship) that failed to process, that represents the failed object with details. The response body JSON should be symmetrical to the request body, with records listed in one array and relationships in a separate one.
The following limitations apply to bulk requests:
- A bulk request can only execute a single CREATE or UPDATE operation.
- Records are processed one by one, in order to enable workflow rules on each record.
