Please use docs.servicenow.com for the latest documentation.

This site is for reference purposes only and may not be accurate for the latest ServiceNow version

Outbound SOAP Web Service

From Wiki Archive
(Redirected from Web Service Consumer Plugin)
Jump to: navigation, search
Note
Note: This article applies to Fuji and earlier releases. For more current information, see Outbound SOAP Web Service at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.


Overview

The SOAP Message module can be used to develop, prototype, and save outbound SOAP messages that can be reused in business rules and scripts. Outbound SOAP web services comply with SOAP1.1 standards.

You can use outbound SOAP messages in scripts using the SOAPMessageV2 API and the SOAPResponseV2 API, starting with the Fuji release. Examples detailing how to script outbound SOAP are available. For versions prior to Fuji, refer to previous version documentation.

Video Tutorial

The following video tutorial demonstrates how to configure outbound SOAP web service messages to consume third-party web services from the ServiceNow platform. Applies to all supported releases as of Fuji.

How to Consume Third-Party SOAP Web Services
xHKD8W6stHI|500}}

SOAP Message

Information needed to send SOAP requests is stored in SOAP message records. Each record specifies an endpoint for the request, the required format of the request as a web services description language (WSDL) file, authentication information, and a list of functions that can run against the endpoint.

Creating a SOAP Message

  1. Navigate to System Web Services > SOAP Message.
  2. Click New.
  3. Enter a Name to identify the SOAP message.
  4. Specify a WSDL using one of these options:
    • To download and use an online WSDL source, select the Download WSDL check box and enter the URL for the WSDL in the WSDL field
    • To enter the WSDL directly, clear the Download WSDL check box, and then copy and paste the WSDL XML into the WSDL XML field.
  5. If the endpoint is protected by basic authentication, select the Use basic auth check box and enter the credentials.
  6. If the endpoint requires mutual authentication, select the Enable mutual authentication check box and select a Protocol profile to use for mutual authentication (starting with the Fuji release).
  7. Click Submit.

This image shows an example of a SOAP message that connects to a demo instance of ServiceNow.


Soap message demoi1.png

SOAP Message Functions

After you create a SOAP message record, you can click Generate sample SOAP messages to populate the SOAP Message Functions related list. The instance creates these functions by reading the supplied WSDL definition.

Soap message function.png

The SOAP action, SOAP endpoint, and Envelope fields should be populated automatically based on the WSDL definition. The Envelope defines the message to send to the endpoint. In this example, the Envelope values have this format:

<source lang="xml"> ... <short_description xsi:type="xsd:string">String</short_description> ... </source>

To submit a specific value, enter the value directly in the appropriate XML tag. In this example, to set the Short description for a record, enter:

<source lang="xml"> ... <short_description xsi:type="xsd:string">This is the short description</short_description> ... </source>

Variable Substitution

To use variable substitution, use the format ${<variable_name>} instead of defining a specific value.

<source lang="xml"> ... <short_description xsi:type="xsd:string">${short_desc}</short_description> ... </source>

To test variable substitution after you have modified the SOAP envelope with the variables, define values for the variables in the SOAP Message Parameters related list. For example, click New and enter the following information:

Soap message parameters.png

Testing

To test the SOAP message, click the Test related link. You are redirected to a test result form as shown below.


Soap message test.png


You can see the original SOAP request message, the resulting HTTP status code, and the SOAP response in this screen. You can also click the Rerun test related link to resubmit the SOAP request.

Note
Note: A test SOAP message will time out after 60 seconds if a response is not received.


Using a SOAP Message in a Script

After you have developed and tested the SOAP message, click the Preview script usage related link in the SOAP Message Function form. The dialog box displays an example of how you can invoke the SOAP message from a script. See SOAPMessageV2 API for a list of available methods, or Scripting Outbound SOAP for detailed scripting examples.


Soap message sample script.png

You can manipulate the resulting XML response body with XMLDocument or with gs.getXMLText and gs.getXMLNodeList.

Demonstration Video

The following video shows examples of creating and sending SOAP messages. The script example in this video uses the version one SOAPMessage API.

{{#ev:youtube|tokwGftF0_0|800}}

Sending a SOAP Message Through a MID Server

When creating SOAP message functions, you can configure the function to be sent through a MID Server selected in the Use MID Server field. There must be a running MID Server associated with your ServiceNow instance to use this functionality. All SOAP messages sent through a MID Server are performed asynchronously.

Soap message mid.png

By specifying a MID Server, all SOAP requests that use this SOAP message are sent through that MID Server. You can override the selected MID Server by using the setMIDServer(mid server) API call in a script.

Connectivity Details

For the ServiceNow-initiated SOAP requests to successfully communicate with the web service provider inside a remote network, the ServiceNow instance must have HTTP or HTTPS access to the SOAP endpoint at the provider. Like any integration, such as LDAP, web services, or JDBC, the SOAP endpoint may reside behind a firewall that is blocking inbound communication from the ServiceNow instance. If this is the case, you need to make network changes to allow this connectivity into your network. You can either modify the firewall and ACL rules to allow the ServiceNow IP address, configure the SOAP message to use a MID Server, or implement a VPN tunnel to allow the ServiceNow communication into your network.

Note
Note: A common misconception is that because asynchronous SOAP requests are routed through the ECC queue, they are always sent through a MID Server. This is not the case. Asynchronous SOAP requests only use a MID Server when configured to do so.


Outbound SOAP Security

You can authenticate outbound SOAP messages using several different security protocols. The security protocol you should use depends on the requirements of the web service provider.

Basic Authentication

If the endpoint requires a user name and password, you can provide these credentials using basic authentication.

  1. Navigate to System Web Services > Outbound > SOAP Message.
  2. Select a SOAP message record.
  3. In the SOAP Message Functions related list, select a function.
  4. Select Use basic auth.
  5. Enter a user name in the Basic auth user ID field.
  6. Enter the password for that user in Basic auth user password.
  7. Click Update.

Web Service Security

You can sign outbound SOAP messages using a key store and trusted server certificate saved on the instance.

  1. Upload a key store certificate with a Type of Java Key Store or PKCS12 Key Store.
  2. Upload the trusted server certificate for the key store certificate.
  3. Navigate to System Web Services > Outbound > SOAP Message.
  4. Select a SOAP message record.
  5. In the SOAP Message Functions related list, select a function.
  6. Select Use WS-Security.
  7. In the Key store field, select the Java or PKCS12 key store you uploaded.
  8. In the Key store alias field, enter the alias that identifies the public and private key pair.
  9. In the Key store password field, enter the password you assigned the key store record.
  10. In the Certificate field, select the trusted certificate for the selected key store.
  11. Click Update.

Mutual Authentication

ServiceNow supports mutual authentication for outbound web services. Mutual authentication is not available for inbound web services.

Configuring SOAP with a Proxy

The following properties provide support for SOAP requests to use a web proxy server.

Property Description Examples
glide.http.proxy_host The proxy server hostname or IP address proxy.company.com, 192.168.34.54
glide.http.proxy_port The port number for the proxy server 8080, 9100
glide.http.proxy_username If the proxy server is authenticating using user name and password, enter a value for this property proxyuser
glide.http.proxy_password If the proxy server is authenticating using user name and password, enter a value for this property password


Enhancements

Fuji