{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1218,"path":"api-reference/web-services/c_SOAPWebService.md","title":"SOAP web service","bundle":null,"doc_type":null,"release":"australia","body":"\n# SOAP web service\n\nSimple Object Access Protocol \\(SOAP\\) is an XML-based protocol for accessing web services over HTTP.\n\nYou can use SOAP to access data on your instance. Available SOAP web services are WS-I compliant, as outlined in the WS-I Basic Profile 1.0.\n\n## Web service provider\n\nServiceNow publishes its underlying table structures and associated data using the following web service methods:\n\n-   [Direct web services](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_DirectWebServices.md): Use a URL query to request a table's WSDL.\n-   [SOAP web service import sets](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/soap-web-service-import-sets.md): Use import tables and transform maps to automate web service requests for tables.\n-   [Scripted SOAP web services](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_ScriptedWebServices.md): Use custom JavaScript to execute SOAP web services requests.\n\n**Note:** SOAP messages are sent with the assumption that the recipient is XML compliant. No encoding is applied to a SOAP message. SOAP always decodes responses as UTF-8, the XML encoding header is not used.\n\n## WSDL\n\nAll tables and import sets dynamically generate Web Service Definition Language \\(WSDL\\) XML documents that describe its table schema and available operations.\n\nYou can obtain a table's WSDL by issuing a URL call to your instance that contains the name of the table and the **WSDL** parameter. For example:\n\n```\nhttps://myinstance.service-now.com/incident.do?WSDL\n\n```\n\nAll dynamically generated and served ServiceNow WSDLs accessible via HTTP are available for use under the terms defined in the Open Source Initiative OSI - Apache License, Version 2.0 license agreement.\n\n## Long-running SOAP request support\n\nThe ServiceNow AI Platform supports long-running SOAP requests by preventing socket timeouts due to inactivity of the network connection while the requests are in process.\n\nThis functionality improves the efficiency of the ODBC driver when requesting large numbers of records, doing aggregate queries, or using order by expressions that require sorting.\n\nBy default, the system provides timeout protection for web services clients provided by ServiceNow such as the ODBC driver and the MID Server. You can add timeout protection to your custom web services with system properties.\n\n## Timeout protection\n\nWeb services clients receive a 307-Temporary Redirect to keep long sessions alive and prevent a timeout due to socket inactivity. A 307-Temporary Redirect causes web services clients which support the status code to repeat their last request to the location specified in the HTTP location header. The value of the location header is the same URL that the web services client originally specified. The use of 307-Temporary Redirects is WS-I compliant.\n\nA web service request that exceeds the timeout limit specified in **glide.soap.request\\_processing\\_timeout** can only receive a 307-Temporary Redirect when all of these conditions are met:\n\n-   The value of **glide.soapprocessor.allow\\_long\\_running\\_threads** is true.\n-   The request includes a **redirectSupported=true** URL parameter.\n-   The request is session-aware \\(supports HTTP cookies\\).\n-   The number of redirects has not exceeded the value set by **glide.soap.max\\_redirects**.\n\nIf any of these conditions is not met, the web service client receives a 408 Request Timeout error.\n\n**Note:** To ensure that applications experience a socket timeout rather than a 408 Request Timeout, set the **glide.soap.request\\_processing\\_timeout** property to a value larger than the shortest socket timeout setting in effect for the connection between the application and the instance \\(300 seconds for hosted instances\\).\n\n## SOAP web services security\n\nAn instance enforces web service security using a combination of basic authentication challenge/response over the HTTPS protocol and system-level access control lists \\(ACLs\\) using contextual security. Administrators can control what system resources web services users can access by granting them one of the SOAP roles.\n\n## SOAP roles\n\nTo use SOAP web services, you must have the appropriate role for the operation you want to perform. Also, you must have any other roles required to access the target tables.\n\n|Role|Description|\n|----|-----------|\n|soap|Can perform all SOAP operations.|\n|soap\\_create|Can insert new records.|\n|soap\\_delete|Can delete existing records.|\n|soap\\_ecc|Can query, insert, and delete records on the Queues `[ecc_queue]` table.|\n|soap\\_query|Can query record information.|\n|soap\\_query\\_update|Can query record information and update records.|\n|soap\\_script|Can run scripts that specify a .do endpoint. This role is required for running scripted web services.|\n|soap\\_update|Can update records.|\n|import\\_admin|Can manage all aspects of import sets and imports. Required for access to the Import Set Row \\[sys\\_import\\_set\\_row\\] table.|\n|import\\_transformer|Can manage import set transform maps and run transforms. Required for access to the Import Set Row \\[sys\\_import\\_set\\_row\\] table.|\n\n## Default web services role requirements\n\nBy default, a set of processor ACL rules require users to have the soap\\_query role to make WSDL, XSD, and XML schema requests.\n\nIf you want to change these role requirements, you can deactivate the ACL rules.\n\n\\[Omitted image \"WebServiceProcessorACLs.png\"\\] Alt text: Access controls table.\n\n## Basic authentication\n\nTo enforce basic authentication for the user associated with the instance for each WSDL or SOAP message request, administrators can set the property `glide.basicauth.required` to **true**.\n\nWhen enabled, each WSDL and SOAP request must contain an \"Authorization\" header as specified in the [Basic Authentication](http://www.w3.org/Protocols/HTTP/1.0/draft-ietf-http-spec.html#BasicAA) protocol.\n\nBecause web services requests are non-interactive, the **Authorization** header is always required during a request.\n\n**Note:** If configured, basic authentication refers to local credentials or LDAP authentication.\n\nSupplying basic authentication information with every request \\(whether or not it is required\\) has the added advantage that the user supplied in the basic authentication credentials can be associated web service invocation. For example, when creating an Incident record, the journal field lists the user ID contained in the basic authentication header instead of the default guest user.\n\n## SOAP security policies\n\nThe Enhanced Web Service Provider - Common plugin adds the SOAP Security Policies module to the System Web Services application. This module allows administrators to set the following security policies:\n\n-   Enable or disable signing SOAP requests when consuming an external web service\n-   Specify the authentication requirements SOAP requests must meet when communicating over WS-Security.\n\nTo know more about SOAP access policy, see [SOAP API access policies](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/soap-api-access-policies.md).\n\n\\[Omitted image \"SOAPSecurityPolicies.png\"\\] Alt text: The SOAP Security Policies module is selected in the All menu.\n\n## Certificates required for signed SOAP requests\n\nTo sign SOAP requests for WS-Security communications, the following certificates are required:\n\n-   X.509 certificate from the requester\n-   X.509 CA certificate of the certificate authority who signed the requester's certificate\n\n## SOAP default security policy\n\nAdministrators can specify the SOAP security policy an instance uses with the system property `glide.soap.default_security_policy`. The `glide.soap.default_security_policy` system property specifies the name of the SOAP security policy the instance uses when enforcing Web Services-Security \\(WSS\\) for inbound requests.\n\n|Field|Description|\n|-----|-----------|\n|Type|String|\n|Default value|Default Security Policy|\n|Location|[Add a system property](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/t_AddAPropertyUsingSysPropsList.md) to the System Properties \\[sys\\_properties\\] table|\n\n## WS-Security\n\nYou can validate signed web services requests using WS-security. Enable WS-Security to:\n\n-   Verify that SOAP messages originate from a known sender\n-   Verify that SOAP messages have not been altered in transit\n\nServiceNow supports [WS-Security 1.1](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss) to validate signed web services requests.\n\n**Note:** WS-Security is not used as an encryption mechanism, HTTPS protocol is used to encrypt all communications.\n\nWS-Security is intended to work with basic authentication. When an instance receives a SOAP message, it reviews the basic authentication header to determine if the SOAP user has rights to the instance. It reviews the WS-Security header to determine the validity of the incoming message. Requests affected by attacks, such as a man-in-the-middle attack, have an invalid WS-Security header and are blocked.\n\n## WS-Security profiles\n\nA WS-security profile determines how a web services message is authenticated when WS-security is enabled. The following mechanisms can be used to authenticate web services requests:\n\n|Authentication mechanism|Description|\n|------------------------|-----------|\n|Certificate verification|Verifies the certificate associated with the request. Verifying the request's certificate requires uploading the requester's certificate and certificate authority.|\n|User credentials|Authenticates the web services request by verifying the user credentials associated with the request. This type of authentication can either verify that the request's credentials match an existing user's credentials or that the request's credentials match a user name and password provided in the profile record.|\n\nSpecify the authentication mechanism you want to use when you [create a new WS-security profile](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_CreateANewWS-SecurityProfile.md).\n\nThe WS-Security Profiles module lists the WS-Security profiles that are currently in effect.\n\n\\[Omitted image \"WS-SecurityProfilesModule.png\"\\] Alt text: WS Security Profiles table is populated with X509 and Username record types.\n\n## WS-Security error logging\n\nThe `glide.processor.debug.SOAPProcessor` system property allows error messages about WS-security to be displayed in the transaction log.\n\nThe system property `glide.processor.debug.SOAPProcessor` enables \\(true\\) or disables \\(false\\) debugging messages for SOAP processing such as certificate and keystore checks.\n\n|Field|Description|\n|-----|-----------|\n|Type|true \\| false|\n|Default value|false|\n|Location|[Add a system property](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/t_AddAPropertyUsingSysPropsList.md) to the System Properties \\[sys\\_properties\\] table|\n\n## WSS X.509 Token Profile\n\nUse the X.509 framework for a WSS X.509 security profile. An X.509 certificate is used to validate a public key that is then used to sign the incoming SOAP message. It specifies a binding between a public key and a set of attributes that includes at least the following:\n\n-   subject name\n-   issuer name\n-   serial number\n-   validity interval\n\nUse the [X.509 authentication framework](https://www.oasis-open.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdf) as defined by the [Web Services Security: SOAP Message Security specification](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss).\n\nUpload the certificate and reference it in the **X509 Certificate** field. If a bound session, select the user to impersonate when the WS-Security authentication succeeds.\n\n\\[Omitted image \"WSSX509SecurityProfile.png\"\\] Alt text: WS Security Profile form is populated with a user type, order, and certificate.\n\n## WSS UsernameToken Profile\n\nWhen specifying the X.509 Token Profile, you can also supply a UsernameToken in the SOAP request.\n\nA UsernameToken is used as a means of identifying the requester by \"user name\", and optionally using a password, shared secret, or password equivalent, to authenticate that identity.\n\nThere are two ways to authenticate a UsernameToken.\n\n1.  Authenticate with existing user credentials.\n\n    \\[Omitted image \"AuthenticateWithExistingServiceNowUserCredentials.png\"\\] Alt text: WS Security Profile form is populated with Username type and the profile action set to 'authenticate with user'.\n\n    Use the user name of the incoming SOAP request to look up a user by the specified **User** field to match the **UserName** value. The system uses the password value in the incoming UsernameToken to authenticate the request. When the **Bind session** option is selected, the user that authenticates successfully is used for the session.\n\n2.  Authenticate with specified user credentials.\n\n    \\[Omitted image \"AuthenticateWithSpecifiedUserCredentials.png\"\\] Alt text: WS Security Profile form is populated with the username type, user, and profile information.\n\n    Authenticate using login credentials unrelated to users in the User table. When the **Bind session** option is selected, the user that is specified in the **Run as user** field is used for the session.\n\n\n**Note:** The [UsernameToken Profile](https://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-UsernameTokenProfile.pdf) cannot be used independent of the X.509 Token Profile.\n\n## Strict security for web services\n\nBy default, basic authentication for web services only determines whether a user is authorized to access the instance with a SOAP connection. Once authorized, any user can access any table published as a web service.\n\nThe system property **Enforce strict security on incoming SOAP requests** changes this behavior and requires that users meet [Contextual Security Manager](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_ContextualSecurity.md) requirements to access instance resources from web services.\n\nWith this property enabled, only users that have the proper SOAP role and also meet the ACL conditions the table and operation can perform that operation from a SOAP connection.\n\n## Mutual authentication for web services\n\nMutual authentication is supported for outbound web services.\n\n## SOAP session management and reporting\n\nA SOAP session is a Glide session established with an instance by any external SOAP client, such as a web services client application, a ServiceNow MID Server, or the ServiceNow ODBC driver. SOAP sessions are included in the list of user sessions at **User Administration** &gt; **Logged in users**. The `?SOAP` URLs identify SOAP sessions.\n\n## SOAP session properties\n\nCertain properties control how SOAP sessions are maintained.\n\n<table id=\"table_bdx_vly_25\"><thead><tr><th>\n\nProperty\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nglide.soap.invalidate\\_session\\_timeout\n\n</td><td>\n\nDuration, in seconds, that an active session remains open. After this duration is reached, the instance deactivates the session and reclaims any system resources. If the client sends another request after the timeout duration is reached, the instance establishes a new session.This property accepts values from 5 to 1200 seconds \\(20 minutes\\).\n\n -   Type: integer\n-   Default value: 60\n-   Location: Add to the System Properties `[sys_properties]` table\n\n</td></tr></tbody>\n</table>**Note:** To learn more about properties that affect SOAP web services processing, see the following topics in Instance Security Hardening Settings:\n\n-   [Access control \\(instance security hardening\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/sc-access-control.md)\n-   [Basic auth: SOAP requests](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/sc-soap-request-authorization.md)\n\n-   **[Scripted SOAP web services](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_ScriptedWebServices.md)**  \nScripted SOAP web services allow a ServiceNow administrator to create custom SOAP web services.\n-   **[Direct web services](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_DirectWebServices.md)**  \nA direct web service is available for any table in the system if the correct access control list is configured.\n-   **[SOAP web service import sets](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/soap-web-service-import-sets.md)**  \nWeb service import sets complement direct web services and scripted SOAP web services by providing a web service interface to import sets tables.\n-   **[AttachmentCreator SOAP web service](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_AttachmentCreatorSOAPWebService.md)**  \nAttach documents to records in ServiceNow by sending a SOAP message targeting the ecc\\_queue table.\n-   **[Override a SOAP endpoint](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_OverridingTheSOAPEndpoint.md)**  \nThe SOAP endpoint address where the SOAP message is posted is consistent with the endpoint of the WSDL.\n-   **[Enable HTTP compression](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_EnablingHTTPCompression.md)**  \nBy default, the SOAP request is accepted un-compressed and the result of the request is returned un-compressed.\n-   **[Prevent empty elements in SOAP messages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_PreventEmptyElementSOAPMsgs.md)**  \nBy default, an instance does not omit empty elements, elements with NULL or NIL values, from SOAP messages.\n-   **[Insert related records using SOAP](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_InsertRelatedRecordsUsingSOAP.md)**  \nSupport is available for inserting hierarchical data into tables or web service import set tables. The hierarchical data in the Insert API is automatically mapped to related records of the targeted table.\n-   **[Specify requirement for signed SOAP requests](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_SpecifyReqForSignedSOAPRequests.md)**  \nUse a SOAP security policy to specify whether the instance requires signed SOAP requests for all inbound SOAP traffic.\n-   **[Activate the Enhanced Web Service Provider - Common plugin](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_ActivateEnhancedWSPPlugin.md)**  \nAdministrators can activate the Enhanced Web Service Provider - Common plugin to enable unsigned WS-Security requests and specify what authentication requirements SOAP requests have.\n-   **[Configure SOAP security](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_ConfigureSOAPSecurity.md)**  \nAdministrators can configure web service security for inbound SOAP requests made to the ServiceNow instance.\n-   **[Set the SOAP default security policy](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_SetTheSOAPDefaultSecurityPolicy.md)**  \nSet the SOAP default security policy.\n-   **[Create a new security policy](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_CreateANewSecurityPolicy.md)**  \nAdministrators can specify which security profiles WS-Security communications must meet by creating a new security policy.\n-   **[Create a new WS-Security profile](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_CreateANewWS-SecurityProfile.md)**  \nCreate a new WS Security profile to define how to authenticate a web services message when WS-Security is enabled.\n-   **[Enforce strict security for inbound SOAP](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_EnforceStrictSecurityWebSvcConns.md)**  \nStrict security for web services requires that users meet Contextual Security requirements to access instance resources.\n-   **[Enable WS-Security verification](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_EnableWS-SecurityVerification.md)**  \nAdministrators can enable Web Services Security \\(WSS\\) verification from the Web Services system properties.\n-   **[Debug incoming SOAP envelope](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_DebuggingIncomingSOAPEnvelope.md)**  \nTo capture incoming SOAP envelope XML in the system log, add the property **glide.processor.debug.SOAPProcessor** with a value of **true**.\n-   **[View a SOAP session log](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/t_ViewingASOAPSessionReport.md)**  \nYou can view a user's log from a SOAP session.\n-   **[Basic authentication code samples](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_BasicAuthenticationExamples.md)**  \nSamples of basic authentication code for several programming languages and versions.\n-   **[Example: WS-Security SOAP envelope header](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_SmplWSSecSOAPEnvHeader.md)**  \nAn example of a valid WS-Security SOAP envelope header.\n-   **[WS-Security properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/ws-security-properties.md)**  \nThese properties control the behavior of WS-Security X.509 tokens.\n-   **[WS-Security error messages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_WS-SecurityErrorMessages.md)**  \nAn instances produces one of the following error messages when it encounters an issue with a WS-security SOAP message.\n-   **[WS-Security reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/ws-security-reference.md)**  \nSupport for WS-Security 1.1 in the form of WSS X.509 Token Profile and WSS Username Token Profile is available for incoming SOAP requests.\n-   **[Long-running SOAP request properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/LongRunningSOAPRequestProps.md)**  \nThe following properties are available for long-running SOAP requests.\n-   **[Retrieve a large number of records using SOAP](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_RtvLrgNmbrRcrdSOAP.md)**  \nBy default, a single SOAP request can retrieve a maximum of 250 records.\n\n**Parent Topic:**[Inbound web services](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/inbound-web-services.md)\n\n"}}