Welcome Login
Blog Photos Links

RSS Feed

RESTful JSON Web Services in ServiceNow - Part 2, How To

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.

RESTful JSON Web Services in ServiceNow - Part 1, The Background

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

In my work at BYU I work on the Office of IT's website and internal tools that are powered by ServiceNow. This has been a good solution for us giving us more flexibility out of a purchased solution than I have ever seen. At BYU we are trying to build out a Service Oriented Architecture (SOA) and have been creating many web services to enable systems to talk to each other.

ServiceNow has been very powerful in enabling us to fully participate in SOA. We are one of the largest consumers of various web services on-campus. ServiceNow's native web services have made it possible for others to consume information from us as well. This is a win-win situation.

In the Office of IT we started with a preference for SOAP web services and have since migrated to RESTful JSON web services since they have generally turned out to be simpler to set up, understand, and consume. They are also significantly less verbose (if you've may it this far into this article then I'm guessing this isn't news to you).

Generally any set of data or table in ServiceNow is automatically accessible via several forms of web services. This has been great, but there are some cases where we need to do a little more heavy lifting than just basic querying, inserting, and updating. This is where Scripted Web Services come in. We've made a couple of these. The most notable of which provides others the ability to tie into an order process in the Service Catalog.

This has been a good tool, it is for SOAP web services and lets you easily take inputs, script the heavy lifting, and then return the outputs, but it was not designed to return multiple records and isn't our preferred way of building web services.

Then a few days ago I ran into a post by John Anderson, a ServiceNow integration specialist, on his blog about how to launch a scheduled job from a URL. That sounded an awful lot like a REST web service to me.

He used a Processor to do the job. These are essentially undocumented and advanced parts of ServiceNow. I had run into them a little bit at a ServiceNow conference but hadn't explored it much. When I saw John's post the lights started going on.

It was convenient that yesterday we also had a request for a web service to return some data that can't be easily obtained with the default web services.

One of my student employees and I took the head start John gave us and spent a combined 12 hours yesterday to learn about, build, document, and turn over to the users for validation a RESTful JSON web service. I'd say that was a successful day.

Now that I've written a whole bunch of history I think I'll split the how to into a separate post, Part 2.


What's New

There are currently no new items, please check back later.

Archives
2021 (2)
  September (1)
  May (1)
2019 (1)
  August (1)
2018 (3)
  August (1)
  April (1)
  January (1)
2017 (1)
  January (1)
2016 (4)
  December (1)
  November (1)
  May (1)
  January (1)
2015 (1)
  December (1)
2014 (2)
  August (1)
  February (1)
2013 (4)
  October (1)
  July (1)
  June (1)
  April (1)
2012 (11)
  December (2)
  October (3)
  September (1)
  May (1)
  April (1)
  February (2)
  January (1)
2011 (14)
  December (1)
  November (1)
  September (2)
  July (2)
  June (1)
  May (1)
  April (2)
  March (3)
  January (1)
2009 (2)
  October (1)
  June (1)
2008 (1)
  September (1)