ServiceNow’s JSON Web Service interface 2 / 3

Data retrieval functionality

In the previous instalment of this blog series I briefly covered the JSON notation, compared it to SOAP and wrote about the overview of the ServiceNow platform’s JSON Web Service Interface.

In this blog post I will be covering the data retrieval functionality of the JSON Web Service interface. Namely the “get”, “getKeys” and “getRecords” actions. I will also cover the “action parameters” used to alter the behaviour of the JSON Web Service.

URL

As described in the ServiceNow’s documentation, the JSON Web Service is provided by a platform level Processor and the service is triggered by a standalone URL parameter ‘JSON’.

The URL is used to pass parameter information to ServiceNow in HTTPS GET call.

https://<instance>/<table>.do?JSON&<parameter>=<value>&<parameter2>=<value>

Most of the parameters can also be sent as part of the HTTPS POST calls payload, in which case the URL is

 https://<instance>/<table>.do?JSON

Action parameters

Before delving into the actions, let us briefly go through the “action parameters” used in the Data retrieval (and also data modification). The action parameters are used to alter the behaviour of the JSON Web Service, and to define the target of the action. The parameters are concatenated to URL or added to HTTPS request payload. 

• sysparm_action : specifies the action we want to make. E.g. “get” or “insert”
• sysparm_query : specifies the query to be used in “get", "getRecords", "update" or "deleteMultiple" actions
• sysparm_view : if you are reading this you probably already know that this selects the view (e.g. “ess”) to be used, and hence the fields which are returned
• sysparm_sys_id : used to specify the target record’s sys_id during a "get" or "delete" action

The abovementioned parameters can be used in JSON formatted HTTPS POST request, but the parameters below seem to only work as part of the URL.

• displayvariables: Boolean value. If set to true during a “get” or “getRecords” action, retrieves all variables attached to the record (example variable below).

One additional parameter (although not called “action parameter” by ServiceNow documentation) is 

• displayvalue : governs how to handle reference fields and similar
• “false” : the default value, reference fields return sys_id
• ”true” : reference fields show the display value
• “all” : reference fields show the sys_id, but an additional field prefixed with “dv_” e.g. “dv_assigned_to” will show the display value of a field

Differences in reply message are shown below.

get action

The “get” sysparm_action is used in conjunction with the sysparm_sys_id parameter to retrieve a single record from the system. The request can be made using HTTPS GET to an instance.

https://<instance>/incident.do?JSON&sysparm_action=get&sysparm_sys_id=e8caedcbc0a80164017df472f39eaed1 

or by specifying the same information in a HTTPS POST message payload.

{"sysparm_action":"get", "sysparm_sys_id":"e8caedcbc0a80164017df472f39eaed1"}

ServiceNow system will respond with the record wrapped in the “records” array (see one of the earlier examples), or with an empty “records” array if a record with the given sys_id is not found.

An error is returned if the sysparm_sys_id URL parameter is missing.

{"error":"sysparm_sys_id parameter required for get call: incident"}

getKeys action

The getKeys sysparm_action is used in conjunction with the sysparm_query action parameter to retrieve a list of sys_ids belonging to records matching the query.

 https://<instance>/incident.do?JSON&sysparm_action=getKeys&sysparm_query=number=INC0000003

As with the get sysparm_action, the same request can be made using the HTTPS POST method with the following message payload.

{"sysparm_action":"get", "sysparm_sys_id":"e8caedcbc0a80164017df472f39eaed1"}

Both requests will yield the response message containing the “records” array. Only this time, the array is an array of sys_id strings.

{"records":["e8caedcbc0a80164017df472f39eaed1"]}

getRecords action

The getRecords sysparm_action is used in conjunction with the sysparm_query action parameter to retrieve a list of records matching the provided query.

As with the get and getKeys, making a HTTPS GET request to the instance will return the results

 https://<instance>/incident.do?JSON&sysparm_action=getRecords&sysparm_query=numberININC0000003,INC0000004&sysparm_view=ess

or by making a HTTPS POST request with payload defining the parameters.

{"sysparm_action":"getRecords",
"sysparm_view":"ess",
"sysparm_query":"numberININC0000003,INC0000004"}

The message returned from the ServiceNow instance is the (now familiar) “records” array containing objects which match the query, or an empty array if no records match the query.

Next

In the next instalment of this blog series I will cover the data modification actions.