Searching the Help
To search for information in the Help, type a word or phrase in the Search box. When you enter a group of words, OR is inferred. You can use Boolean operators to refine your search.
Results returned are case insensitive. However, results ranking takes case into account and assigns higher scores to case matches. Therefore, a search for "cats" followed by a search for "Cats" would return the same number of Help topics, but the order in which the topics are listed would be different.
Search for | Example | Results |
---|---|---|
A single word | cat
|
Topics that contain the word "cat". You will also find its grammatical variations, such as "cats". |
A phrase. You can specify that the search results contain a specific phrase. |
"cat food" (quotation marks) |
Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase. |
Search for | Operator | Example |
---|---|---|
Two or more words in the same topic |
|
|
Either word in a topic |
|
|
Topics that do not contain a specific word or phrase |
|
|
Topics that contain one string and do not contain another | ^ (caret) |
cat ^ mouse
|
A combination of search types | ( ) parentheses |
|
- Developer reference
- Overview of the REST API
- Connect to the REST API
- Authentication endpoint service
- Single record APIs
- Record bulk update and collection APIs
- REST API queries
- REST API collection query protocol
- Analytics REST API
- Manage Persons API
- BI Integration API
- Case Exchange REST API
- Encryption domain API
- Comments API
- REST API use-case scenario - import REST API
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.
Related topics