personsleepingred

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>");