Loading

SOAP Web Service

From ServiceNow Wiki
Home > Integrate > Web Services > SOAP Web Services > SOAP Web Service
Jump to: navigation, search
Web Services

Contents

1 Overview

The SOAP Web Services provided by ServiceNow are WS-I compliant, as outlined in the WS-I Basic Profile 1.0.

2 Concepts and Terminology

  • Provider - publishes web service for clients to invoke (consume)
  • Consumer - invokes / consumes published web service
  • Standards
    • WSDL
      • Web Service Description Language
      • XML document describing functions, arguments, data schema, and endpoint (where / how to invoke the service, URL)
      • WSDL only necessary when generating SOAP envelope programmatically
    • SOAP
      • Simple Object Access Protocol
      • XML document usually HTTP posted to web service endpoint described in WSDL
      • SOAP:Envelope / SOAP:Header / SOAP:Body
    • HTTP
      • Hyper-Text Transfer Protocol
      • POST vs GET - Web Service is POSTed
      • XML vs. Form POST - Web Service is XML

2.1 Web Service Provider

ServiceNow publishes its underlying table structures and associated data with the following Web Service methods:

Note
Note: SOAP messages are sent with the assumption that the recipient is XML compliant. No encoding is applied to the SOAP message.


2.2 Web Service Consumer

Consuming external web services is achieved using Javascript objects that represent the web service SOAP envelope and the subsequent SOAP HTTP request that submits the request. Web Service Consumer documents these programmatic constructs as well as examples of how to invoke web services.

3 WSDL

All ServiceNow tables and import sets dynamically generate WSDL XML documents that describe its table schema and available operations. You can get a WSDL format by issuing a URL targeting a ServiceNow table with the WSDL parameter, for example:

https://myinstance.service-now.com/incident.do?WSDL

All dynamically generated and served ServiceNow WSDL accessible via HTTP is available for use under the terms defined in the Open Source Initiative OSI - Apache License, Version 2.0 license agreement.

4 Direct Web Services

A direct web service is available for any table in the system provided the correct access control is setup. The supported format of the incoming message is document style literal XML SOAP documents (Document/Literal). To retrieve the direct web service WSDL description and XML schema, point to the relative URL of <tablename>.do?WSDL. For example, to retrieve the WSDL for the Incident table on the online demo system, use the following URL:

https://<instance name>.service-now.com/incident.do?WSDL

5 Web Service Import Sets

Web Service Import Sets compliment Direct Web Services and Scripted Web Services to provide a web service interface to Import Sets tables. This type of web service will transform the incoming data synchronously based on the associated Transform Maps by default.


6 SOAP Roles

To use SOAP web services, you must have the appropriate role for the operation you want to perform. Additionally, you must have any other roles required to access the target tables.

Role Description
soap Can perform all SOAP operations.
soap_create Can insert new records.
soap_delete Can delete existing records.
soap_ecc Can query, insert, and delete records on the Queues [ecc_queue] table.
soap_query Can query record information.
soap_query_update Can query record information and update records.
soap_script Can run scripts that specify a .do endpoint. This role is required for running Scripted Web Services.
soap_update Can update records.

7 Overriding the SOAP Endpoint

The SOAP End-point address (where the SOAP message is posted) is consistent with the endpoint of the WSDL. In some cases, however, the WSDL may reference an incorrect endpoint URL. If this happens, it is necessary to over-ride the generated URL by creating the property com.glide.soap_address_base_url to contain the new URL. You may have to add the property manually as this is not an out-of-box property.

For instance, a generated SOAP Endpoint may look like this:

https://instance.service-now.com/incident.do?SOAP

You can specify a property to define the endpoint such that it goes through a proxy by setting the property:

com.glide.soap_address_base_url = "https://myproxy.mycompany.com/service-now/"

This will result in the endpoint being generated to appear as:

https://myproxy.mycompany.com/service-now/incident.do?SOAP

8 Enabling HTTP Compression

By default, the SOAP request is accepted un-compressed and the result of the request is returned un-compressed. To enable HTTP compression using [gzip] when sending in your SOAP request, set the following HTTP header:

Content-Encoding: gzip

To receive the SOAP response compressed using [gzip] send in your SOAP request with the following HTTP header:

Accept-Encoding: gzip

9 Debugging Incoming SOAP Envelope

To capture incoming SOAP envelope XML in the system log, add the property glide.processor.debug.SOAPProcessor with a value of true.

When enabled, this property adds the incoming SOAP envelope in the Message field of the system log. Disable this debugging feature as soon as you are finished so that the log is not overwhelmed with excessive and unnecessary debugging information.

10 Preventing Empty Elements in SOAP Messages

By default, ServiceNow does not omit empty elements, elements with NULL or NIL values, from SOAP messages.

To prevent SOAP responses from containing empty elements, an administrator can create a system property called glide.soap.omit_null_values and set the value to true. This behavior is compliant with the WSDL as all elements in a SOAP message have a minOccurs=0 attribute and are therefore optional. In addition, this behavior prevents the instance from creating inefficient SOAP messages containing a large number of empty elements.

Set this property to false to allow SOAP messages to search for existing fields with empty values. For example, if an administrator wants to search for incidents with an empty Assigned to field from a SOAP message, then the SOAP message must be able to send an empty value for this field.

Note
Note: Changing the value of this property may cause unintended actions in existing web service integrations. Administrators are strongly encouraged to carefully test the new behavior to ensure that existing integrations process empty elements as expected.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Views
Personal tools