Develop > Developer reference > Record bulk update and collection APIs

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. All mandatory fields need to be included when creating a new record. To check which fields are mandatory, go to Administration > Configuration > Studio > Fields, select the record type from the drop-down list, and check which fields are marked as Required.

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.

Related topics