Technical Tango

February 25, 2012, 10:57 am - James Farrer

This should explain the basic pieces needed to write a JSON web service in ServiceNow. The background leading up to this is contained in Part 1.

Processors

Processors in ServiceNow are an as yet relatively undocumented feature that is used in the system to provide different formats for using the data in tables. For example, for a JSON version of the data in a table you can tack on JSON as a parameter in the URL and it will use this Processor:

It takes the parameter as indicated in the Parameters field and passes it into a Script Include to do the heavy lifting.

The g_request, g_response, g_target, and g_processor variables that are passed in allow for obtaining input parameters to the Processor and assembling and outputing the response. A few options I used in my JSON web service are g_request.getParameter(), g_response.setContentType() and g_processor.writeOutput().

In order to set up the Processor the Type must be set to "script" and instead of using the Parameters field, fill in the Path. This will be the name in the URL, so if your Path has "super_cool_service" then you will access the Processor by going to "https://yourinstance.service-now.com/super_cool_service.do".

The rest of the magic happens in the script. You are most likely going to want parameters passed in. For what I did these were passed in the URL as standard GET parameters and I retrieved them with

g_request.getParameter("parameter_name")

In my case I needed to do an aggregate query on Incident data and return the summarized results. So I took the parameters, sanitized them, and used them to build the query.

Then it looped through the results and built a javascipt object with the data we wanted to send back.

There are a couple pieces of code that make it possible to return the results as a JSON web service. ServiceNow has a JSON class that allows translating to and from a JSON formatted string to a Javascript Object. I have used this in other places to parse JSON data from web services and here am doing the reverse to generate the JSON string from the object that was created.

g_response.setContentType("application/json");
var response = new JSON();
g_processor.writeOutput(response.encode(response_object));

The first line sets the HTTP content type so clients understand what format the data is coming back in. When I added this my JSON formatter browser plugin starting recognizing the content as JSON and formatting it in a bit more readable manner. The next line instantiates the JSON interpretter that is used in the last line to encode the object that was assembled. The last line also sends the resulting string back to the browser.

That's the meat of it. One of the things I did to make the service a little easier to consume was to make it self-documenting. That means that if you don't pass in the required parameters it returns an error message as well as the instructions for what inputs it expects. I've seen this in other services and have built on the idea and here's the result:

In my case I expect additional functionality to be added to this service so I set up the Operations array in the response to allow for more report options. This is the response if the service is called directly with no parameters.

Another point of note, we put the actual querying into a Script Include to allow for reuse. For example if we later need to make an HTML version of the report we can simply create a UI Page that calls the Script Include and format the returned object.

I'd be interested to hear any feedback on improvements or other options. This is advanced ground with little documentation but it promises to be incredibly flexible and useful.