Outbound REST Messages in ServiceNow

ServiceNow offers several integration options for their customers.   One of these is the Outbound REST capability, that is available in the base platform.  The most common use for Outbound REST Messages is to create a record in another system, such as sending an incident to a vendor’s ITSM system.

Setup

In order to configure a REST message in ServiceNow you will need to get the following information from the system that you are attempting to integrate with:

• REST API Guide for the product you are integrating with. (just google it)
• Endpoint (https://blah.blah.com/api/etc)
• Authentication Type (None, Basic, Oauth, Mutual)
• Headers (Accept, Content-type,etc)
• JSON Content Request Body (If SN, Use API Explorer)

Authentication

In order to connect to the remote system, you will need to authenticate.  This can be done one of three ways:

None

Everything is open, so no need for authentication (i.e. Yahoo Finance and other Open REST APIs).

Basic

Username and Password

OAuth

This is the most secure method, which is token based and usually entails getting an Authorization Code from the provider.

Variables and JSON Content

In the message body, you will want to get agreement with the remote system administrators as to what content you are going to send them.  The message body needs to be in a JSON format and it should look something like this:

{“caller_id”:”${caller_id}”,”short_description”:”${short_description}”,”description”:”${description}”,”category”:”${cateogry}”,”cmdb_ci”:”${cmdb_ci}”}

The ${} is what you will be supplying in your script.

Once you have filled out the content field, click on Auto-generate variables.

Triggering the REST Message

Once you have the REST message configured you can use the “Preview Script Usage” link and ServiceNow will provide you with a script sample that you can copy and paste, make some adjustments to, and then use in one of three ways:

Business Rules

You can trigger the REST message from a business rule running a script.  This is good for transactional integrations such as sending an incident to a vendor’s ticketing system.

Events and Script Actions

You can create an event, which can be generated from any number of places that can trigger a Script Action which runs your REST script.

Scheduled Jobs

You can configure a Scheduled Job to run a script which calls your REST message.  This is useful for things like retrieving bulk data.

Dealing with the JSON response

When you make a REST call, the receiving system will provide you with a response.  This response will be in JSON format if you configured your Accept and Content-type headers as “application/json”.  You can use the JSONParser to parse the response and populate fields on your form from that response.  Maybe something like “Vendor Ticket Number” or updating the work notes.

The preview script will give you this part:

 var response = r.execute();

 var responseBody = response.getBody();

 var httpStatus = response.getStatusCode();

You can then add something like this to update the record:

// If the response is: {“result”:{“status_message”:“”,”status_code”:200}}

//Update the task with the result

            var parser = new JSONParser();

            var parsedResponse = parser.parse(responseBody);

            current.work_notes = “REST Result: ” + responseBody + ” HTTP Status: ” + httpStatus;

            current.u_vendor_ticket_number = parsedResponse.result.status_message;

            current.update();

A note on logging and troubleshooting

With any REST message, you can specify what level of logging you want by clicking on “Set HTTP Log Level.”  You will get three options:

Basic

You want this for high performance production.  Doesn’t include Request or response.

Elevated

Includes headers, but still no request or response body

All*

Obviously, this is everything available used for troubleshooting.   If you use this option, you will most likely want to update the glide.outbound_http.content.max_limit system property to something large like 1000 – 4000 to see the entire request body in All.  You can access the logging output under “Outbound HTTP Requests”

For more information on ServiceNow, please Contact Us.