Back in 2012, ServiceNow added a GUI Configuration utility and coding library that allows its users to quickly and easily set up REST based web service communication. While the “RESTMessage” library in ServiceNow is relatively new, it is socked with great features. The biggest problem with the new library is that there is very little published documentation with how to interact with the library. I hope to place some of my own documentation here as well as provide some coding tips that I use with REST Message.
RESTMessage API
RESTMessage(name, function)
Constructor
Parameters
- name: Name of the REST Message Record.
- function: Name of the function we are calling inside of the REST Message Record. These will typically be get, post, put, or delete.
Returns
- An instance of the RESTMessage class.
Example
1 | var r = new RESTMessage("WebServiceRecord", "get"); |
setBasicAuth(username, password)
This was introduced into the API with the Calgary Release.
Parameters
- username: User you wish to authenticate with
- password: Password for that user
Returns
- Nothing
Example
1 2 | var r = new RESTMessage("WebServiceRecord", "get"); r.setBasicAuth("admin", "admin123"); |
execute()
Submits the request to the REST Web Service Endpoint to be processed.
Parameters
- None
Returns
- (If a Direct call) An instance of the RESTResponse object as defined in your ServiceNow Script Includes.
- (If calling through a MID Server) Nothing is returned as this will be an asynchronous call
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | var r = new RESTMessage("WebServiceRecord", "get"); var response = r.execute(); //Direct call...no MID Server used JSUtil.logObject(response); gs.log(response.getHttpMethod()); //Returns the Java function used to make the request gs.log(response.getStatusCode()); gs.log(response.getHeader('Set-Cookie')); gs.log(response.getHeaders()); //Returns all headers as a JSON string gs.log(response.getBody()); //Returns the body of the HTTP Response gs.log(response.haveError()); //Returns T/F depending on if error gs.log(response.getErrorCode()); gs.log(response.getErrorMessage()); gs.log(response.getEndpoint()); gs.log(response.getParameters()); |
getEndpoint()
Gets the endpoint string (if set programmatically).
Parameters
- None
Returns
- A string representation of the Endpoint that will be receiving the REST Message request. This will only work if you have programmatically set the Endpoint using the “setRestEndPoint” method to set the endpoint value. Otherwise, you will get an “undefined” result.
Example
1 2 3 | var r = new RESTMessage("WebServiceRecord", "get"); r.setRestEndPoint("http://something.restbased.com"); gs.log(r.getEndpoint()); |
getResponse(waitMS)
Waits a specified amount of time and then searches the ECC Queue for the asynchronous response to a REST request that was made through the MID Server. (This only works for requests submitted through a MID Server)
Parameters
- waitMS: Number of milliseconds to wait before checking for a response on the ECC Queue
Returns
- A special object that contains all of the ECC Queue Response information
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | var r = new RESTMessage("WebServiceRecord", "get"); r.execute(); var k = 1; var response = r.getResponse(); while (response == null) { gs.log("waiting ... " + k + " seconds"); response = r.getResponse(1000); //wait 1 second before looking for the response k++; if (k > 30) { break; // service did not respond after 30 tries } } JSUtil.logObject(response); gs.log(response.getStatusCode()); gs.log(response.getBody()); //Returns the body of the HTTP Response gs.log(response.haveError()); //Returns T/F depending on if error gs.log(response.getErrorCode()); gs.log(response.getErrorMessage()); gs.log(response.getEndpoint()); gs.log(response.getParameters()); |
setEccCorrelator(correlator)
Sets an Agent Correlator on the ECC Queue request record for the request (Seldom Used)
Parameters
- correlator: Name of the correlator
Returns
- Nothing
setEccParameter(name, value)
Sets a special, custom parameter on the ECC queue record for outbound REST calls. This is only applicable if you are using a MID Server on the request. (This is seldom, if ever, used).
Parameters
- name: Name of your custom ECC Queue record parameter
- value: Value of the parameter
Returns
- Nothing
setMIDServer(midServer)
Sets the MID Server to be used for this request. It will override any MID Server setting on the actual MID Server record.
Parameters
- midServer: Name of the MID Server to be used (minus any “mid.server.” prefix)
Returns
- Nothing
Example
1 2 | var r = new RESTMessage("WebServiceRecord", "get"); r.setMIDServer("Tacky1"); |
setRestEndPoint(endpoint)
Sets the Endpoint for the REST Message call. This overrides the Endpoint setting on the actual RESTMessage record. The request will be sent to this address.
Parameters
- endpoint: String representation of the URL acting as the REST endpoint
Returns
- Nothing
Example
1 2 | var r = new RESTMessage("WebServiceRecord", "get"); r.setRestEndPoint("http://myweb.service.com/table/action/1335"); |
setStringParameter(name, value)
Searches the REST Message record (headers, endpoints, parameters, and body) for any variables in the format of ${variable_name}. For every matching variable name, it will replace the string with the specified value before submitting the request on the execute command. Please note: any XML type characters will be escaped.
Parameters
- name: The variable name to replace. This needs to match the text within the ${} indicators in the REST Message Record.
- value: The value to set wherever matching ${variable_name} strings are found
Returns
- Nothing
Example
1 2 | var r = new RESTMessage("WebServiceRecord", "get"); r.setStringParameter("account", "151616"); |
setXMLParameter(name, value)
Searches the REST Message record (headers, endpoints, parameters, and body) for any variables in the format of ${variable_name}. For every matching variable name, it will replace the string with the specified value before submitting the request on the execute command. Please note: any XML type characters will NOT be escaped, but treated as XML. Use this function if sections of your request body are expected to be in XML format.
Parameters
- name: The variable name to replace. This needs to match the text within the ${} indicators in the REST Message Record.
- value: The value to set wherever matching ${variable_name} strings are found
Returns
- Nothing
Example
1 2 | var r = new RESTMessage("WebServiceRecord", "get"); r.setXMLParameter("details", "<Person><Name>John Andersen</Name><Sex>M</Sex></Person>"); |
How do I retrieve the ECC Queue ID from the return of the getResponse?
I’ve looked in the JSUtil.logObject(response) and I can see the item there, but I am unable to retrieve it.
Thanks for sharing this John!
Hi! one question, so if I don’t use the basic authentication, which one is default authentication used? or there is another way to sent that authentication for example one base on VAS?
@Pabloariasmora – If you don’t use Basic Authentication, then it will post without authentication. Currently the ServiceNow REST Consumer only supports Basic Auth natively.
I am not able to call RESTMessage in ui pages
Client script. Is it possible to call the web services in ui pages ?