One of the upcoming features of the Dublin Release at ServiceNow is an updated JSON Web Service processor. While it is still not an official REST API for the platform, it is a huge improvement on the original JSON processor that was release a few years ago.

Why the Update

The original JSON Web Service was created to address some basic needs that a handful of customers were requesting in order to use simple RESTful calls to interact with the ServiceNow platform. However, there were some serious performance issues and bulk data limitations that hindered the processor. Secondly, the original processor had some slight security issues that made the processor a risk to some organizations based on their use case. Lastly, the JSON Web Service was inconsistent with how its counterparts worked (eg. JSON web service issue with Web Service Import sets).

Due to the underlying issues in the JSON web service plugin, ServiceNow rewrote the plugin from scratch and worked to get it more similar to the capabilities our SOAP Web Services as well as our other CSV and XML processors for handling bulk data.

Starting with Dublin, ServiceNow will enable the JSONv2 plugin by default. They will also deprecate (and remove) the original JSON web service plugin (can possibly be loaded on special request). Additionally, the processor is now being moved to the Java code rather than using the Javascript implementation.

Rumor has it that the JSONv2 plugin will be made available for Calgary instances in the next publicly released Calgary Patch.

I highly recommend customers discontinue the use of the JSON Web Service plugin and migrate those integrations to be compatible with the JSONv2 format (not much has changed in the interface…so this shouldn’t be too hard).

General Information

The JSONv2 Web service will be accessed by using the URL parameter: “JSONv2” (instead of the “JSON” parameter used by the original processor).

The JSONv2 Web Service can use either GET or POST requests for querying or deleting data. POST requests are required for creating or modifying data through the web service.

Like its predecessor, JSONv2 web service goes through a Basic Authentication layer for determining a client’s access to the resources being referenced.

A “Content-Type” header is now required on all requests. This will be important (and easy) to implement as you migrate old JSON web service clients over to JSONv2.

Using the JSONv2 Web Service

1) Set up the base URL

In order to access a table’s resources through JSONv2, you must reference the table URL that you are going to work with.

In ServiceNow, you can access a table resource by appending it’s database name to the end of the URL and then adding a “.do” exention. For example, the “Incident” table in ServiceNow has a Database Name of “incident”. You would form that URL in this manner:

https://MYINSTANCE.service-now.com/incident.do

For the “ECC Queue” table (ecc_queue), you would use:

https://MYINSTANCE.service-now.com/ecc_queue.do

This is as simple as adding "JSONv2" or "JSONv2=true" to your URL. So, if you were accessing the incident table, your URL might look like:

https://MYINSTANCE.service-now.com/incident.do?JSONv2

3) Set your Content-Type Header

Remember that this header needs to be set. It is always going to have the same value, but you have to include it. Your header string would look something like:

Content-Type: application/json

4) Set your desired action

You can do the following actions with the Web Service (see the official documentation for definitions on what these actions do): get, getKeys, getRecords, insert, insertMultiple, update, deleteRecord, deleteMultiple.

If we wanted to do a getRecords call, we would set up our sysparm_action parameter in the following way:

https://MYINSTANCE.service-now.com/incident.do?JSONv2&sysparm_action=getRecords

5) Add additional parameters as needed

Depending on what you want to do, you will need/want additional URL parameters. The ones most commonly used by me are as follow:

• displayvalue (true, false, or all - if true, it returns display values instead of sys_id's for reference fields. If all, it returns BOTH the display value and the sys_id of reference fields)
• sysparm_view (a view name - limits what fields are returned with the record data - used with "getRecords")
• sysparm_query (an encoded query to filter records - used with "getKeys", "getRecords", "deleteMultiple"
• sysparm_record_count (limits amount of records returned - used with "getRecords" only)
• sysparm_sys_id (used with "get" or "deleteRecord" only)

6) Add body content for the POST

If you are performing an insert, insertMultiple or an update, you will need to post the data in JSON format as the Body of the HTTP POST request. For more information on the format, see the wiki documentation for JSONv2 Data Modification.

Example usage of the JSONv2 Web Service

In the following example, we are going to query the incident table of an instance. Since we may have more incident records that are allowed, we are going to limit the number of returned records and chuck the requests. Also, we don't care about a lot of the fields, so we are only going to require the fields from the "mobile" view to be returned through the web service calls. Finally, we will request display values rather than sys_ids for reference fields.

Let's follow our steps to generate the first RESTful request:

1) Set up the URL to operate against the incident table

https://MYINSTANCE.service-now.com/incident.do

2) Invoke the JSONv2 Processor

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2

3) Set the Content-Type to "application/json"
4) Specify the "getRecords" action

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords

5) Use some optional parameters to get what we want
We will ask for display variables to be returned for reference fields:

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords
 &displayvalue=true

We will restrict the number of fields to just those of the mobile view:

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords
 &displayvalue=true
 &sysparm_view=mobile

We will want to order the results by sys_id since we are going to page through them:

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords
 &displayvalue=true
 &sysparm_view=mobile
 &sysparm_query=ORDERBYsys_id

We will page the data to manageable sets. For this example, we will say "3" records. That is really low, but this is just a demo:

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords
 &displayvalue=true
 &sysparm_view=mobile
 &sysparm_query=ORDERBYsys_id
 &sysparm_record_count=3

This will get us the following response:

Those are the first three records. We are then going to take the sys_id from the last record and query for the next set of records with the following URL:

https://MYINSTANCE.service-now.com/incident.do?
 JSONv2
 &sysparm_action=getRecords
 &displayvalue=true
 &sysparm_view=mobile
 &sysparm_query=sys_id>1a0db534df120100cd7da5f59bf26304^ORDERBYsys_id
 &sysparm_record_count=3

This gets us the next set of three.