Scripted SOAP web services

Scripted SOAP Web Services allow a ServiceNow administrator to create new web services that are not addressed by the system.

You can define input and output parameters for the web service and use JavaScript to perform operations. Though this feature is very powerful, use Direct Web Services or Web Service import sets instead whenever possible since they are simpler to implement and maintain.

Security

When strict security is enforced on a system, the HTTP authenticated user must have the soap_script role to execute the scripted web service.

Creating a new web service

When the Web Services Provider - Scripted plugin is activated, a new module Scripted Web Services is available under the System Web Services application.

Figure 1. Scripted web service module

Click the module to display a list of example scripted Web Services.

Figure 2. Sys web service

Example 1: Retrieving a system property

The first step is to define the incoming and return parameters. This is done by adding an entry to the Input Parameters and Output Parameters. These parameters are used to construct and present a meaningful WSDL, and they do not add to the functionality of processing the actual Web Service itself.

Figure 3. Input Output
The parameters are referenced in the script of the Web Service. Any of the input parameters are retrieved using the following syntax:
var a= request.property;
The output parameters are set by using the following syntax:
response.property="ABC";

The following example demonstrates how to retrieve a system property and return it as part of the SOAP response. The example shows how to create a custom scripted Web Service to do something specific that the base ServiceNow system direct Web Services cannot.

Figure 4. Get property

Example 2: Ordering a Blackberry

Direct Web Services in ServiceNow operate on tables and their data, while the following example shows how to initiate a business solution, such as ordering a Blackberry, by invoking a scripted Web Service. The following input and output parameters will support the Blackberry example:

Figure 5. Input output blackberry
This script shows how to use the above parameters to add a Blackberry to the service catalog shopping cart and order it. The request number is returned in the request_number field of the SOAP response.
var cart =new Cart();varitem= cart.addItem('e2132865c0a8016500108d9cee411699');
cart.setVariable(item,'original', request.phone_number);
 
// set the requested forvar gr =new GlideRecord("sys_user");
gr.addQuery("user_name", request.requested_for);
gr.query();if(gr.next()){var cartGR = cart.getCart();
  cartGR.requested_for= gr.sys_id;
  cartGR.update();}
 
var rc = cart.placeOrder();
response.request_number= rc.number;

Global Variables

To facilitate custom processing of incoming SOAP requests, the following global variables are available in the script context:
  1. soapRequestDocument: a Java org.w3c.dom.Document object representing the incoming SOAP envelope.
  2. soapRequestXML: a string object representing the incoming SOAP envelope XML.
  3. request: a Javascript object containing mapped values (mapped to input parameter names) of the incoming SOAP envelope.
  4. response: a Javascript object which allows the script programmer to customize the response values. See Customize Response