How to send REST data using the “PATCH” Method from ServiceNow

REST Example

 

When beginning an integration it is important to identify which capabilities are supported on both endpoints. In my case I was trying to integrate two systems which supported REST but not all HTTP Methods were supported by ServiceNow. ServiceNow supports the following Outbound REST Methods:

GET – Pull records

POST – Create records

PUT – Update records

DELETE – Delete records

Unfortunately for me in this case the remote system’s provided API only supported GET/POST/PATCH as a means to pull/create/update (PATCH usually used to partially update) records on the remote system and unfortunately sending REST data using the “PATCH” method is not currently supported in ServiceNow*. So what if you want to integrate with a 3rd party API that only works with PATCH to update data?

The answer, hope that the 3rd party provides an override method (most Microsoft products) that can be used with “POST” or “PUT”, both of which ARE supported in Outbound REST ServiceNow. In this scenario the 3rd party application has written special logic to handle incoming REST messages that are using one method (POST/PUT), but are checking for Request Headers to determine if the incoming data should be handled in another fashion (in our case PATCH).

The key to making this work (apart from confirming the 3rd party supports this) is in the HTTP Header of your REST Message you will need to set the Request Headers either in your REST Message or via code (depending on how you are implementing your REST functionality). Then setup the method to use POST or PUT so that ServiceNow knows how to send the REST message.

Below is an example of both ways in which we use the POST method to override in these examples; in this example the Request Headers needed were for ContentType and Override:

  • X-HTTP-Method-Override = “PATCH”
  • Content-Type  = “application/json-patch+json”

Here’s our example setting it up via a REST Message definition:

REST PATCH Method3

Or setting it up entirely in code:

var r = new sn_ws.RESTMessageV2();
r.setRequestHeader("Accept","application/json");
r.setRequestHeader('Content-Type','application/json-patch+json');
r.setRequestHeader('X-HTTP-Method-Override','PATCH');
r.setHttpMethod('post');
var url = 'https://integration.url.com';
r.setEndpoint(url);

*Note that PATCH is supported inbound to ServiceNow using REST, but does not support outbound PATCH (even though the REST API Explorer tool will generate non-working outbound PATCH code for you…) as of this post (in Helsinki).

How to Debug an Object in ServiceNow?

The following tools we will discuss today should give you some great options when it comes to debugging objects in ServiceNow.

The first option we need to discuss is the “Xplore” (version 3.5 currently) utility by James Neale. If you are not using this Developer tool then you should get this must-have utility immediately. If you ever wondered what was in a GlideRecord (or most any other object), or wished the “Background Scripts” tool had a better interface then this should be your go-to utility. There are a number of additional capabilities that this tool offers but this is my favorite.

Of course there are other ways to pull info on objects, but the interface on this utility is extremely intuitive and makes dissecting objects on the server side very easy. You can find this utility on ServiceNow’s Share site, or on GitHub.

Xplore (big)

One other tip that I discovered is that once’s its installed its possible to utilize its “xplore” function to parse objects to the log as well (handy when trying to debug objects on the fly and dump to the system logs):

var xplore = new snd_xplore(object);
gs.print(xplore);

xplore Command

Note that the “xplore” function name is subject to change as they release newer versions.

So now that we’ve covered Xplore, on to other tools that should be in your toolbox for object exploration. These are needed if you are not going to use the Xplore utililty and need to troubleshoot realtime communication and logging the output from within your own scripts. Here are the other one’s I’ve used:

Other Server Side Tools
There is a cool Script Include that is included OOB in ServiceNow called “JSUtil”. If you haven’t used/seen it previously, take the time to check it out; there are some great functions including one called describeObject that can be used to parse basic objects:

JSUtil.describeObject(object)

describeObject

Note that the JSUtil is not available/callable from within scoped applications.

Another option is to try outputting your (JSON compliant) object using the built-in JSON Script Include. This tool is great for “stringifying” data to make it readable on the server side:

gs.log(global.JSON().encode(object))

 

Ok, so you’re covered on the Server side of things, but what about the Client? 

Below are some Client Side Tools that allow you to debug objects in on the client/browser:

JSON().stringify(object)

If you are not using objects as properties in your object you may be able to use the JSON methods: JSON.stringify() on the client side, or JSON.encode() on the Server side. But again, that won’t work if the object uses functions or other properties which aren’t serializable to JSON.

One final Method is to use a simple loop; note that this ignores the Prototype inherited properties by using the “hasOwnProperty” check:

for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { var val = obj[key]; // use val }}

A final tool you can use if you are in a browser like Chrome is DevTools. You can easily utilize “console.log(objectName)” in the Console (to open this just right click on a blank area of the page and choose “inspect) browser to then click through an object. Below is a screenshot showing how this can be done, I have used the “g_form” object as an example, and then started clicking through its keys/properties:

Debugging an Object - g_form

One thing to note, if you are doing this within the “Full Frame set” (includes the navigation bar), then you will need to select the “gsft_main(tableName.do), frame before you can start debugging. Alternatively just open your form in a new window that doesn’t have the navigation/top panel (control click on the link):

Console Debug iFrame

If you are not using Chrome (I’m sorry :)), you can always use something like the Firefox (Firebug) to do the same thing.

Have I missed any other common tools/methods? Please let me know!

How to Parse JSON Data?

I was working with a client recently who was just starting their journey into the world of Web Services using REST. This is a very powerful technology which allows two systems to exchange data using HTTP [POST (Create), GET (Read), PUT (Update/Replace), PATCH (Update/Modify), DELETE (Delete)] with JSON (JavaScript Object Notation) to exchange data. To work with this JSON data, ServiceNow gives a few methods. The confusing part to most new admins is that there are separate methods depending on if the parsing is done on the Server side, or Client side. Here are the methods to use for both:

Client Side:

JSON.stringify(yourJSONObject) //Encode your object into a string
JSON.parse(yourJSONString) //Decode your JSON String into an Object

Server Side:

new global.JSON().encode(yourJSONObject); //Encode your object into a String
new global.JSON().decode(yourJSONString); //Decode your JSON String into an Object

One nice thing about using REST in ServiceNow is that they provide a number of APIs (Table API, Aggregate, Import Set, Performance Analytics) based upon what type of integration is needed.

An additional nice feature that came in the Fuji release was the “REST API Explorer” which allows you to easily test the different REST methods with different data.

A similar tool that can be used externally to test can be found at http://hurl.it

Here are some more links to help you along your REST journey:
http://wiki.servicenow.com/index.php?title=Getting_Started_with_REST#gsc.tab=0
http://wiki.servicenow.com/index.php?title=REST_API
http://wiki.servicenow.com/index.php?title=Outbound_REST_Web_Service#gsc.tab=0
http://wiki.servicenow.com/index.php?title=Table_API#gsc.tab=0
http://wiki.servicenow.com/index.php?title=REST_API_Explorer#gsc.tab=0
http://wiki.servicenow.com/index.php?title=Scripting_Outbound_REST#gsc.tab=0