Scripted SOAP web services

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Scripted SOAP web services

    Scripted SOAP web services in ServiceNow enable administrators to create custom SOAP web services with defined input and output parameters, leveraging JavaScript to perform operations. While powerful, it is recommended to use direct web services or SOAP web service import sets when possible for simpler implementation and maintenance.

    Show full answer Show less

    Security

    Scripted SOAP web services adhere to the same security options as all SOAP web services in ServiceNow. When strict security is enabled, the HTTP authenticated user must have the soapscript role to execute the scripted web service.

    WSDL and Compliance

    ServiceNow dynamically generates WSDL XML documents for all tables and import sets, describing schema and operations. For scripted SOAP web services, the WSDL is based on Input and Output Parameters related lists, while the actual SOAP response is controlled by the script.

    To enforce that output parameters in the SOAP response follow the order defined in the WSDL, you can enable the WSDL Compliance checkbox. This causes the web service to reorder output parameters accordingly and exclude any additional parameters not defined in the Output Parameters list.

    Static WSDL

    In scenarios where external clients require a specific WSDL format different from the standard ServiceNow format, you can create a static WSDL to match the required structure, ensuring compatibility.

    Global Variables Available in Scripts

    • soapRequestDocument: Java org.w3c.dom.Document object representing the incoming SOAP envelope.
    • soapRequestXML: String containing the raw XML of the incoming SOAP envelope.
    • request: JavaScript object with mapped input parameter values from the SOAP request.
    • response: JavaScript object to customize the SOAP response payload.

    Practical Use and Next Steps

    • Create new scripted SOAP web services by defining input/output parameters and scripting logic to process requests and generate responses.
    • Customize SOAP response XML to meet specific requirements using the available global variables and script logic.
    • Create scripted SOAP web services using static WSDLs when client requirements necessitate a non-standard WSDL format.

    Scripted SOAP web services allow a ServiceNow administrator to create custom SOAP web services.

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

    Security

    Scripted SOAP web services have the same base security options as all SOAP web services. For details on SOAP web services security, see SOAP web services 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.

    WSDL

    All ServiceNow tables and import sets dynamically generate Web Service Definition Language (WSDL) XML documents that describe its table schema and available operations.

    Enforcing WSDL compliance

    You can force the response to list output values in the same order as defined in the WSDL.

    When you create a scripted SOAP web service, the generated WSDL is based on the Input Parameters and Output Parameters related lists. The actual SOAP response sent by the scripted service is determined by the Script. This behavior can cause the script to return output values in a different order than defined in the WSDL.

    To enforce the order of output parameters as defined in the related list, select the WSDL Compliance check box. When this check box is selected, the web service reorders the parameters returned by the script to match the order in the WSDL.
    Note:
    If additional response parameters are returned by the script, but are not defined in the Response Parameters related list, those parameters are excluded from the response when WSDL Compliance is selected.
    Table 1. Output Parameters related list
    Parameter Order
    Param 1 200
    Param 2 300
    Param 3 100

    The following is the script that sets values for the defined output parameters. Note that in this example script the parameters are set in a different order than defined in the Output Parameters related list. Also note the additional parameter param4 that is not defined in the related list.

    Response.param1 = 1;
Response.param4 = 4;
Response.param3 = 3;

    When the WSDL Compliance check box is false, the SOAP response generated by the script is the following:

    <response>
                <param1>1</param1>
                <param4>4</param1>
                <param3>3</param1>
</response>
    When the WSDL Compliance check box is true, the SOAP response generated by the script is the following:
    <response>
                <param3>3</param1>
                <param1>1</param1>
</response>

    Static WSDL

    Some web service clients require SOAP access to your instance through a specific WSDL format. This required format may differ from the standard ServiceNow WSDL format. In these cases you can create a static WSDL that matches the required format.

    Global variables

    To facilitate custom processing of incoming SOAP requests, the following global variables are available in the script context:
    • soapRequestDocument: Java org.w3c.dom.Document object representing the incoming SOAP envelope.
    • soapRequestXML: String object representing the incoming SOAP envelope XML.
    • request: Javascript object that contains mapped values (mapped to input parameter names) of the incoming SOAP envelope.
    • response: Javascript object that allows you to customize the response values. See Customize Response