K*I*S*S REST API Troubleshooting made simple

[kobby_adu-nti]

In my capacity as a Integrations engineer, I have been given the opportunity to work with many of Service Now's technology partners. In my role, I often address the friction points that may arise during a solution implementation, especially in areas where attempts have been made to customise the Service Now platform. Working in this fashion is fruitful for all parties. During our interactions with partners and customers, Service Now internal staff are able to share knowledge and best practice. And in return, our customers share their vision, innovation and enterprise with us.

In this blog post, I will be discussing an incident raised by one of Service Now's technology partners and how we, in turn, managed to assist the partner in question to successfully deliver their customised business requirement.

The issue:

The partner in question had developed an inbound web service to CREATE/UPDATE a record on their cmdb_ci table utilising the PUT method in the REST API. During the course of developing their solution, a decision was made that a custom field on the cmdb_ci table should hold a default value. The pain point they found was that whenever they tested their PUT method to create a record on the cmdb_ci table the configured default value on their custom field would overwrite any value received from the PUT method.

Allow me to illustrate this friction point clearer. For argument's sake, let us say that the custom field on their cmdb_ci table is named u_impact (cmdb_ci.u_impact) and the field has been configured to contain the value '2' by default within the Service Now frameset UI.

Given the above configuration following payload from the PUT method would be expected to create a record with a cmdb_ci.u_impact value of '1'

PayLoad : {"company":"IT Corp","name":"Test CI 1","u_impact":"1"}

However, our intrepid partner found that although the PUT method did successfully create the new record the value of the cmdb_ci.u_impact field on the new record remained that of which was configured by default, in the case presented the value '2'.

To troubleshoot this issue I engaged in the activities below:

• I began by following the partners concise instructions to reproduce the incident. The details I required were as follows:
  • The name of the instance where the web service was configured
  • The name of the web service
  • Valid test data for the web service
• Once I was able to reproduce the issue I intentionally caused it to occur so the behaviour of the instance could be observed as it happened. Beforehand, I reconfigured the instance in question so that the system property glide.rest.debug was set to true. Taking this action causes the instance to generated verbose REST web service messages in the instance application server logs.
• The application Server logs displayed something similar to the following message:

2017-09-08 07:01:52 (403) API_INT-thread-4 E36EE68EDB494300635158A8DC96198A DEBUG: #28323 [REST API] RequestDeserializer : Incoming Request Body:{"name":"Test CI 1","company":"IT Corp","u_impact":"1"}

2017-09-08 07:01:52 (444) API_INT-thread-4 E36EE68EDB494300635158A8DC96198A WARNING *** WARNING *** Get for non-existent record: core_company:IT Corp

• From the above we can clearly see that the GET method is invoked and fails as the system attempt to process the PUT method. The reason behind this is the company field on the cmdb_ci table. The company field is a reference to another table within the instance database, this table being core_company. And, using the test data supplied by our development partner, the data being parsed via the PUT method failed on the invoked GET method as it did not exist in the core_company table
• Finally, once I had a hypothesis of the root cause of the issue, I performed the steps to reproduce the issue again. Only this time I updated the payload received from the PUT method so that a valid company value could be located on the core_company table. Sending something similar as displayed below.

PayLoad : {"company":"6ea700d1f5ed2d009d4406726f5d346d","name":"Test CI 1","u_impact":"1"}

The outcome, I was able to successfully insert a record into the cmdb_ci table with the correct value in the u_impact field.

So let us breakdown the process I followed

1. First gather information. I required the details of how to recreate the issue. Once I had this information I could utilise the Service Now REST API explorer to send the REST request and report back the responses I received and the HTTP codes. The REST API Explorer is a useful utility for both troubleshooting and developing REST requests and is therefore a useful addition to more well known troubleshooting tools such as Postman, or SOAP UI. You can read more about the REST API Explorers functionalities in the links I have provided below
2. Service Now has numerous system properties that affect the logging level displayed in the platforms application server logs. If it is the case that you are concerned with REST web services then you should activate the glide.rest.debug property. Below I have provided a link to a list of the most useful system properties used in debugging the platform.
3. Analyse and interpret the messages displayed in the application server logs. For our customers, Service Now does not provide a means of direct access to the application server logs of an instance. However, Service Now has made provisions for customers to gain the ability to read the application server logs through the System Logs module. I have taken the liberty of providing a link to the platform documentation for the System Logs module below, there you will find instructions on how this product feature can be best utilised. However, for those of you that prefer to witness system log updates and changes in real time, I would suggest utilising the logtail module. This application utilised by user accounts that have been granted admin access. I have taken the liberty of creating a short film, linked below, that demonstrates the logtail module in action. Try it yourself by substituting <yourInstanceName> tag for the name of the instance you wish to monitor in the following URI:

          <yourInstanceName>.service-now.com/channel.do?sysparm_channel=logtail