Debugging Inbound REST Calls and the Business Rules/ACLs that Impact Them

#REST , #Debugging , #REST API Explorer , #REST Debugging

Josh Nerius

7 minute read

Have you ever run into unexpected behavior when making inbound REST calls to your ServiceNow instance? Perhaps the result of a GET doesn’t contain all of the records you expect it to, or nothing happens when you try to modify a record.

In this post, we’ll explore some of the options available for debugging inbound REST API calls and the Business Rules / ACLs that might be impacting those calls.

Spoilers

I’m going to introduce a few concepts that are not well known later in this post: The Log File Tailer and the X-WantDebugMessages & X-WantSessionNotificationMessages headers.

Handling Unexpected Results When Retrieving Records

Let’s start by looking at a common scenario we might encounter. We want to retrieve a list of Incident records using the Table API. However, when the results come back from the API call, we notice that there are missing records in the response and we can’t see every field that we expect.

So, what should we do next? With practice, you’ll start to get a better feel for when you should try one thing or another, but here’s the approach I generally take.

1. Validate assumptions

Before starting down the path of more complex debugging techniques, check the basics. Take a look at the records in a list or form view and make sure they are what you think they are. For this example, we want every incident where Category is Inquiry/Help. Do you see every incident in a list view that you expect to see?

blog_rest_debugging_incident_list_27.png

Next, impersonate the user used to make API calls. In this example, the incident count went down to 18. Clearly something is filtering the results.

blog_debug_inbound_rest_incidents_18.png

Enable Business Rule and Security Debugging

If you haven’t used the Debug Business Rule and Debug Security session debug options before, they’re tremendously useful tools when trying to determine how Business Rules and ACLs are impacting a transaction or query. To enable them, navigate to System Diagnostics > Session Debug. Click on Debug Business Rule and again on Debug Security.

blog_rest_debug_menu.png

With these debug options enabled, navigate to a list or form view and examine the output at the bottom of the screen. There’s a LOT of useful information here that can help us determine what’s happening during the transaction.

Here’s the Debug Business Rule output. We can see that there is a “before query” rule running before results are returned to us. Before query business rules have the potential to filter out records, so this is one of the first places to look if records are “missing”. In this example, we identified a business rule that is filtering out incidents opened by VIP users if the logged in user doesn’t have the incident_vip role. This explains why we can see the records as admin, but we cannot see the records from our integration user.

blog_debug_inbound_rest_before_query_br_output.png

Taking a look at the Debug Security output, we find that an Access Control is preventing us from reading the value of the “secure_value” field.

blog_rest_debug_security_output.png

At this point, we’ve identified the issue without doing anything special with the API call just by using standard platform debugging tools.B However, it isn’t always this simple. Throughout the rest of this post, we’ll look at ways to get more debug output that is specific to the API calls we’re making.

2. Validate the HTTP request and enable REST Debugging

Errors or unexpected results are often the result of small discrepancies in the HTTP call you’re making. Maybe there’s a bad query parameter or broken path in the URL. You can look for these sorts of issues by enabling REST Debugging and examining the node log.

  1. Create a new true/false system property named glide.rest.debug with value true.
  2. Initiate a test API call from a testing tool such as REST API Explorer, Postman, etc.
  3. Examine the node log file.

There’s just one big problem: we don’t want to download the node log every time we make a test request, and this is where the Log File Tailer comes in handy.

Using the Log File Tailer

The Log File Tailer allows you to view the node log for the node you’re currently connected to in real time. To use it, navigate to https://.service-now.com/channel.do?sysparm_channel=logtail.This will open the Log Tailer interface.

blog_rest_debug_log_file_tailer.png

REST debug log lines will start with something like this: 10/18/17 23:25:25 (984) 6825C50B137D8B409718B9B76144B0C1 #206480 [REST API]:

Use these lines to examine the details of the incoming request. You will see HTTP request headers, messages from the REST API code in the platform and more. A few words of warning about the Log File Tailer:

  • Do not use in production
  • Only keep the tailer window open for a short period of time

3. Session Debugging, Business Rule and Security Debugging

If everything looks good in the node log, it’s time to enable more types of debug output.

Enable Debugging for your Application

There are a number of debugging options available to you, but I’m going to focus on three. Session Debugging, Business Rule Debugging and Security Debugging.When you write gs.debug statements in your code, it doesn’t get displayed in the log file by default. If you want to see these debug messages, you must first enable session debugging. This increases the logging verbosity for the duration of your current session.

  1. Navigate to **System Applications > Application
    **

    blog_rest_debug_session_debug_ui_action.png

  2. Click the Enable Session Debug button

Getting Debug Messages in the REST API response

One of the challenges with using the Node Log is that there can be a lot of other stuff there, and it can be difficult to determine which log entries are part of the request you’re debugging. Ideally, we want to see session debug message as part of the REST API response itself. This can be accomplished by sending one or both of the following HTTP headers with the API requests:

  • X-WantSessionDebugMessages: true
  • X-WantSessionNotificationMessages: true

To demonstrate how these work, I created a simple Scripted REST API with a method that writes debug messages.

blog_rest_debugging_srapi_resource.png

Then, in REST API Explorer, I added the X-WantSessionDebugMessages header.

blog_rest_debug_rapi_explorer_debug_message_header.png

I then sent the request, and this is what the response looks like:

blog_rest_debugging_srapi_response_with_debug_log.png

The X-WantSessionNotificationMessages Header

It’s common for Business Rules to use methods like gs.addInfoMessage(msg) or gs.addErrorMessage(msg) to present information to the current user. These messages are only displayed in the UI by default, but we can also see these messages in REST responses by adding the X-WantSessionNotificationMessages header. Here’s a Business Rule Script that writes both debug and info messages. It executes before query.

blog_rest_debugging_br_with_debug_and_info_message.png

We trigger the rule by initiating a GET request. Similar to the previous example, we add the headers in REST API Explorer:

blog_rest_debug_rapi_session_and_debug.png

And in the response, we can see both messages!

blog_rest_debug_response_with_debug_and_notif.png

Using External API Testing Tools

When you enable session debugging, as the name suggests, debugging is a enabled for your current session. This is a problem if you want to see debug messages from an API testing tool like Postman or Paw since the API request won’t be coming from your browser session. In order to get session debug messages from an external tool, you must also send your current JSESSIONID took and an additional X-UserToken header.

Use your browser’s developer tools to inspect the cookies for your current session. Here’s what this looks like in Google Chrome.

  1. Open Chrome Developer Tools

    blog_debug_inbound_rest_open_dev_tools.png

  2. Navigate to the Application tab and inspect your cookies

    blog_rest_debug_chrome_cookies.png

  3. Copy the JSESSIONID cookie value

Set this aside for the next section.

The X-UserToken value

You must also send your current Session Token with the request in the X-UserToken header. The easiest way to get this token is to navigate to the ServiceNow UI in your browser and View Source. Look for this line:

Session token

This is your current session token. Copy the value in quotes and set it aside for the next step.

Put it all together

Now that you have:

  1. JSESSIONID token
  2. Session Token
  3. Enabled session (and other) debugging in ServiceNow

We can construct the request. Here’s what my example request looks like in Paw, the API testing tool I use.

The Request

blog_debug_rest_paw_request.png

The Response

blog_rest_debug_paw_response.png

Summary

Start with the basics. Use simple list/form views and impersonation before you dig into the more complicated options.

I covered Business Rule and Security Debugging, but there are other session debug options to explore. Check out the other options under the Session Debug menu for additional kinds of output.

For another look at debugging for a slightly different use case, check out K*I*S*S REST API Troubleshooting made simple written by kobby.adu-nti.

Comments