Dot-Walking in the REST Table API

#REST , #Dot-Walk , #Web Services , #REST API , #Table API

Bryan Barnard

3 minute read

If you’ve used ServiceNow for a bit then you are probably familiar with using Dot-walking to access data on related records. In case you are new to the concept here is the definition and a link to product documentation.

From the product docs:

Dot-walking in ServiceNow provides access to fields on related tables from a form, list, or script. If the current table contains a reference to another table, any field on the referenced table can be accessed using dot-walking.

I use dot-walking all the time in ServiceNow to help me view data about related records without needing to navigate to the referenced record. ServiceNow makes it really easy to dot-walk via the UI in lists and scripts but how can I leverage this functionality when using the REST Table API?

The REST Table API (available in the Eureka release and after) supports dot walking for GET requests via the sysparm_fields parameter. This parameter allows you (the requester) to provide a comma-separated list of field names that will be returned in the response. The most common use of the sysparm_fields parameter is to limit the fields that will be returned in the response. For example if you are using the ServiceNow REST Table API to query incident records if you make the following request you will receive a response that contains all the fields that you have access (permissions) to read in ServiceNow (on most systems this result in 40+ fields being returned.

Sample Request to a ServiceNow Demo Instance - All Fields

Sample Request Table API to GET an Incident B7 GitHub

GET /api/now/table/incident?sysparm_limit=1 HTTP/1.1

Authorization: Basic <removed on purpose>

Host: demo003.service-now.com

Connection: close

Sample Response - All Fields

Sample Response B7 GitHub

HTTP/1.1 200 OK

{

  "result": [

    {

      "skills": "",

      "upon_approval": "",

      "location": {

— response cut off to save space — see the GitHub Gist for full response content.

We can use the sysparm_fields parameter to limit the fields returned in the response. For example we can only include the number and location field by adding the sysparm_fields parameter as shown in the following request/response.

Sample Request to a ServiceNow Demo Instance - using sysparm_fields to limit response

sample request using sysparm_fields B7 GitHub

GET /api/now/table/incident?sysparm_limit=1&sysparm_fields=location,number HTTP/1.1

Authorization: Basic YWRtaW46YWRtaW4=

Accept: application/json

Host: demo003.service-now.com

Connection: close

Sample Response - using sysparm_fields to limit response

Sample Response - using sysparm_fields to limit response B7 GitHub

HTTP/1.1 200 OK

{

  "result": [

    {

      "location": {

        "link": "https://demo003.service-now.com/api/now/table/cmn_location/1083361cc611227501b682158cabf646",

        "value": "1083361cc611227501b682158cabf646"

      },

      "number": "INC0000001"

    }

  ]

}

When using the sysparm_fields parameter we were able to limit the response to only include the location and number field from the incident. Location is a reference field on Incident and refers to a record in the cmn_location table. cmn_location records have multiple fields including a name and city field but they are not included in the response by default. So how can we have those fields included in our response? That is where dot-walking comes in. You can dot-walk in the REST Table API using the sysparm_fields. If I add the name and city to the sysparm_fields parameter I can have them included in the response as is shown in the request and response below.

Sample Request to a ServiceNow Demo Instance - using sysparm_fields dot-walk

Sample Request to a ServiceNow Demo Instance - using sysparm_fields dot-walk B7 GitHub

GET /api/now/table/incident?sysparm_limit=1&sysparm_fields=number%2Clocation%2Clocation.name%2Clocation.city HTTP/1.1

Authorization: <removed>

Accept: application/json

Host: demo003.service-now.com

Connection: close

Sample Response to a ServiceNow Demo Instance - using sysparm_fields dot-walk

Sample Response to a ServiceNow Demo Instance - using sysparm_fields dot-walk B7 GitHub

HTTP/1.1 200 OK

{

  "result": [

    {

      "location.name": "Oklahoma",

      "location": {

        "link": "https://demo003.service-now.com/api/now/table/cmn_location/1083361cc611227501b682158cabf646",

        "value": "1083361cc611227501b682158cabf646"

      },

      "number": "INC0000001",

      "location.city": "Oklahoma"

    }

  ]

}
Comments