{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1102,"path":"api-reference/server-api-reference/c_SOAPMessageV2API.md","title":"SOAPMessageV2 - Scoped, Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# SOAPMessageV2 - Scoped, Global\n\nThe SOAPMessageV2 API provides methods to send an outbound SOAP message using JavaScript.\n\nUse this API to manage the response returned by the SOAP provider.\n\nYou can use this API in scoped applications or within the global scope. This API runs in the `sn_ws` namespace.\n\nSee also:\n\n-   [Direct SOAPMessageV2 example](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_DirectSOAPMessageV2Example.md)\n-   [Recordless SOAPMessageV2 example](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_RecordlessSOAPMessageV2Example.md)\n-   [Asynchronous SOAPMessageV2 example](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_AsyncronousSOAPMessageV2Example.md)\n-   [SOAPMessageV2 MID server example](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/r_SOAPMessageV2MIDServerExample.md)\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## SOAPMessageV2 - SOAPMessageV2\\(\\)\n\nInstantiates an empty SOAPMessageV2 object.\n\nWhen using an object instantiated this way, you must manually specify a SOAP action and endpoint.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n```\nvar sm = new sn_ws.SOAPMessageV2();\n```\n\n## SOAPMessageV2 - SOAPMessageV2\\(String soapMessage, String soapFunction\\)\n\nInstantiates a SOAPMessageV2 object from a SOAP message record and a function associated with that record.\n\nValues such as the endpoint, authentication, or MID Server settings from the SOAP message record apply to this object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|soapMessage|String|SOAP message record you want to use as the base for this object.|\n|soapFunction|String|SOAP function you want to execute. Available SOAP functions depend on the WSDL supplied by the web service provider.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\n```\n\n## SOAPMessageV2 - execute\\(\\)\n\nSends the SOAP message to the endpoint.\n\nThis method calls synchronously, meaning that the script execution waits until the call completes before continuing.\n\nThings to consider when using this method:\n\n-   Only use this method for quick service calls. You shouldn't call this method in high volume no matter how quick the service.\n-   Only use this method when the timeout is very short, otherwise the instance can be brought to a standstill. There are two properties that control the timeout period, **glide.http.timeout** and **glide.http.connection\\_timeout**. By default, these timeouts are set to 175 seconds and 10 seconds respectively.\n-   Generally, if the request must go through the MID Server, you shouldn't use this method. MID Server requests must go through the External Communication Channel \\(ECC\\) queue which is an asynchronous queue. The thread isn't only held up by the request itself, but it's also held up waiting for the MID Server to respond back to the instance. If MID Servers are involved, use asynchronous calls with a sensor business rule.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|[SOAPResponseV2](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_SOAPResponseV2API.md)|Response returned by the SOAP provider.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar response = sm.execute(); //Might throw exception if http connection timed out or some issue with sending request itself because of encryption/decryption of password.\n```\n\n## SOAPMessageV2 - executeAsync\\(\\)\n\nSends the SOAP message to the External Communication Channel \\(ECC\\) queue.\n\nSOAP messages in the ECC queue are processed by the SOAPClient business rule.\n\nBy default, this business rule doesn't run asynchronously. To configure this business rule to run asynchronously, set the **When** value to `Async` and add `current.update()` to the end of the **Script**. The instance doesn't wait for a response from the web service provider when sending a message through the ECC queue.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_qpt_3f5_jq\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nSOAPResponseV2 - Scoped, Global\n\n</td><td>\n\nResponse returned by the SOAP provider.**Note:** Attempting to use the SOAP response object before the response has been processed may result in a timeout error.\n\n</td></tr></tbody>\n</table>```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar response = sm.executeAsync();\n```\n\n## SOAPMessageV2 - getEndpoint\\(\\)\n\nGets the endpoint for the SOAP message.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|URL of the SOAP web service provider.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar endpoint = sm.getEndpoint();\n```\n\n## SOAPMessageV2 - getRequestBody\\(\\)\n\nReturns the content of the SOAP message body.\n\n**Note:** Before calling the getRequestBody\\(\\) method, you must call the [execute\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_SOAPMessageV2API.md) method to obtain the response object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|SOAP message body.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"StockQuoteSoap.GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar response = sm.execute();\nvar requestBody = response.getRequestBody();\n```\n\n## SOAPMessageV2 - getRequestHeader\\(String headerName\\)\n\nGets the value for an HTTP header specified by the SOAP client.\n\nBy default, this method cannot return the value for a header set automatically by the system. To grant this method access to all headers, set the property glide.http.log\\_debug to true.\n\n|Name|Type|Description|\n|----|----|-----------|\n|headerName|String|Request header you want to get the value for.|\n\n|Type|Description|\n|----|-----------|\n|String|Value of the specified header.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar header = sm.getRequestHeader(\"Accept\");\n```\n\n## SOAPMessageV2 - getRequestHeaders\\(\\)\n\nGets HTTP headers that were set by the SOAP client and the associated values.\n\nThis method does not return headers set automatically by the system. To configure this method to return all headers, set the property glide.http.log\\_debug to true.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Object|Object that maps the name of each header to the associated value.|\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar requestHeaders = sm.getRequestHeaders();\n```\n\n## SOAPMessageV2 - setAllowedRedirectURIs\\(Array Uris\\)\n\nSets one or more URIs allowed to be redirected to. Controlling the allowed outbound URIs reduces security concerns and helps prevent URL redirect attacks that send users to malicious sites.\n\nFor a more comprehensive means of redirecting URIs, see [UriMatcher - Scoped](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/UriMatcherScopedAPI.md).\n\n|Name|Type|Description|\n|----|----|-----------|\n|Uris|Array|One or more URIs allowed for redirection. Each URI must be listed in \"string\" format.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example shows how to add a list of URLs allowed for redirection for a SOAP message function.\n\n```\n// Redirection URI Allow list\ntry {\n\tvar sm = new sn_ws.SOAPMessageV2('TemperatureConvert', 'TempConvertHttpPost.FahrenheitToCelsius');\n\tsm.setAllowedRedirectURIs(['https://www.w3schools.com/', 'https://www.google.com']);\n\n\tsm.execute();\n\n} catch(ex) {\n\tvar message = ex.getMessage();\n}\n```\n\n## SOAPMessageV2 - setBasicAuth\\(String userName, String userPass\\)\n\nSets basic authentication headers for the SOAP message.\n\nSetting basic authentication headers using this method overrides basic authentication values defined in the SOAP message record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|userName|String|Username to use when authenticating the SOAP message.|\n|userPass|String|Password for the specified user.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setBasicAuth(\"username\",\"password\");\n```\n\n## SOAPMessageV2 - setEccCorrelator\\(String correlator\\)\n\nAssociates outbound requests and the resulting response record in the ECC queue.\n\nThis method only applies to SOAP messages sent through a MID Server. The correlator provided populates the **Agent correlator** field on the ECC queue record for the response. Provide a unique correlator for each outbound request to associate the correct results in the ECC queue with the request when designing asynchronous automation through a MID Server.\n\n|Name|Type|Description|\n|----|----|-----------|\n|correlator|String|Unique identifier|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setEccCorrelator(\"unique_id\");\n```\n\n## SOAPMessageV2 - setEccParameter\\(String name, String value\\)\n\nOverrides a value from the database by writing to the SOAP message payload.\n\nThis method only applies to SOAP messages sent through a MID Server. Use this method when a value from the SOAP message in the database is invalid, such as when the endpoint URL is longer than the maximum **SOAP endpoint** field length.\n\nThese are valid values for the name parameter.\n\n-   **source**: The endpoint URL.\n-   **name**: The SOAP message function to run.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|Name of the ECC parameter.|\n|value|String|Value to assign to the specified ECC parameter.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setEccParameter(\"source\",\"http://very.long.endpoint\");\n```\n\n## SOAPMessageV2 - setEndpoint\\(String endpoint\\)\n\nSets the endpoint for the SOAP message.\n\nBy default, the SOAP message uses the endpoint specified in the SOAP message record. Use this method to override the default. You must call this method when using the [SOAPMessageV2\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_SOAPMessageV2API.md) constructor with no parameters.\n\n|Name|Type|Description|\n|----|----|-----------|\n|endpoint|String|URL of the SOAP web service provider you want to interface with.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2();\nsm.setEndpoint(\"http://web.service.endpoint\");\n```\n\n## SOAPMessageV2 - setFollowRedirect\\(Boolean followRedirect\\)\n\nSets the parameter in the API that controls automatic HTTP redirects. By default, automatic redirects are turned off.\n\nFor additional information on HTTP redirects, see [Redirections in HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections).\n\n<table id=\"table_nhg_cfb_vcc\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nfollowRedirect\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the API should automatically follow any redirects that arise when executing the SOAPMessageV2 call.Valid values:\n\n-   true: Automatically follow redirects.\n-   false: Don't automatically follow redirects. You must handle all redirect conditions within your code.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to set automatic redirects on and have the API handle the redirect.\n\n```\nvar sMessage = new sn_ws.SOAPMessageV2(); //Create an empty SOAP message\nsMessage.setBasicAuth('admin','admin');\nsMessage.setSOAPAction('http://www.service-now.com/incident/insert'); //set the SOAP action to perform\nsMessage.setEndpoint('http://<instance>.service-now.com/incident.do?SOAP'); //set the web service provider endpoint\nsMessage.setRequestBody('<soapenv:Envelope xmlns:soapenv=\\\"http://schemas.xmlsoap.org/soap/envelope/\\\" xmlns:inc=\\\"http://www.service-now.com/incident\\\"><soapenv:Header/><soapenv:Body><inc:insert><short_description>Test Dynamic SOAP</short_description></inc:insert></soapenv:Body></soapenv:Envelope>');\nsMessage.setFollowRedirect(true);\nvar response = sMessage.execute();\ngs.info(response.getStatusCode());\n\n```\n\nOutput:\n\n```\n200\n```\n\nThe following code example shows the automatic redirect set to false. The returned status code is a redirect code. In this case, you must handle the redirect within your code.\n\n```\nvar sMessage = new sn_ws.SOAPMessageV2(); //Create an empty SOAP message\nsMessage.setBasicAuth('admin','admin');\nsMessage.setSOAPAction('http://www.service-now.com/incident/insert'); //set the SOAP action to perform\nsMessage.setEndpoint('http://<instance>.service-now.com/incident.do?SOAP'); //set the web service provider endpoint\nsMessage.setRequestBody('<soapenv:Envelope xmlns:soapenv=\\\"http://schemas.xmlsoap.org/soap/envelope/\\\" xmlns:inc=\\\"http://www.service-now.com/incident\\\"><soapenv:Header/><soapenv:Body><inc:insert><short_description>Test Dynamic SOAP</short_description></inc:insert></soapenv:Body></soapenv:Envelope>');\nsMessage.setFollowRedirect(false);\nvar response = sMessage.execute();\ngs.info(response.getStatusCode());\n\n```\n\nOutput:\n\n```\n3xx  // Redirect status code\n```\n\n## SOAPMessageV2 - setHttpTimeout\\(Number timeoutMs\\)\n\nSets the amount of time the SOAP message waits for a response from the web service provider before the request times out.\n\n|Name|Type|Description|\n|----|----|-----------|\n|timeoutMs|Number|Amount of time to wait for a response from the web service provider, in milliseconds.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setHttpTimeout(6000);\n```\n\n## SOAPMessageV2 - setLogLevel\\(String level\\)\n\nSets the log level for this message and the corresponding response.\n\nSetting a log level using the SOAPMessageV2 API overrides the log level configured on the SOAP message record. This log level may not apply if the endpoint domain is excluded, or if the property **glide.outbound\\_http\\_log.override** is true. To view outbound web service logs, navigate to **System Logs** &gt; **Outbound HTTP Requests**.\n\n<table id=\"table_lxw_gnc_sw\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nlevel\n\n</td><td>\n\nString\n\n</td><td>\n\nLog level. Valid values:\n\n-   all\n-   basic\n-   elevated\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setLogLevel(\"all\");\n```\n\n## SOAPMessageV2 - setMIDServer\\(String midServerName\\)\n\nConfigures the SOAP message to be sent through a MID Server.\n\nBy default, the SOAP message uses the MID Server specified in the SOAP message function record. Use this method to override the default.\n\n|Name|Type|Description|\n|----|----|-----------|\n|midServerName|String|Name of the MID Server you want to send the SOAP message through. Your instance must have an active MID Server with the specified name.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## SOAPMessageV2 - setMutualAuth\\(String profileName\\)\n\nSets the mutual authentication protocol profile for the SOAP message.\n\nSetting a protocol profile using this method overrides the protocol profile selected for the SOAP message record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|profileName|String|Name of the protocol profile to use for mutual authentication.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setMutualAuth(\"auth_profile_name\");\n```\n\n## SOAPMessageV2 - setRequestBody\\(String requestBody\\)\n\nSets the body content to send to the web service provider.\n\nWhen you set the body content using this method, variables in the body are not substituted for parameters from the SOAP message function record. You must explicitly define all values within the SOAP message body.\n\n|Name|Type|Description|\n|----|----|-----------|\n|requestBody|String|Body of the SOAP message.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nvar body = \"<SOAP message body>\";\nsm.setRequestBody(body);\n```\n\n## SOAPMessageV2 - setRequestHeader\\(String headerName, String headerValue\\)\n\nSets an HTTP header in the SOAP message to the specified value.\n\n|Name|Type|Description|\n|----|----|-----------|\n|headerName|String|Name of the header.|\n|headerValue|String|Value to assign to the specified header.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setRequestHeader(\"Accept\",\"Application/json\");\n```\n\n## SOAPMessageV2 - setSOAPAction\\(String soapAction\\)\n\nDefines the SOAP action this SOAP message performs.\n\nThe WSDL for your web service provider lists SOAP actions you can perform. You must call this method when using the [SOAPMessageV2\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_SOAPMessageV2API.md) constructor with no parameters.\n\n|Name|Type|Description|\n|----|----|-----------|\n|soapAction|String|SOAP action this SOAP message performs.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2();\nsm.setSOAPAction(\"GetQuote\");\n//construct SOAP message by specifying endpoint and auth\nsm.execute();\n```\n\n## SOAPMessageV2 - setStringParameter\\(String name, String value\\)\n\nSets a variable with the specified name from the SOAP message record to the specified value.\n\nXML reserved characters in the value are converted to the equivalent escaped characters.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|Name of the SOAP message variable.|\n|value|String|Value to assign to the specified variable.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setStringParameter(\"symbol\",\"NOW\");\n```\n\n## SOAPMessageV2 - setStringParameterNoEscape\\(String name, String value\\)\n\nSets a variable with the specified name from the SOAP message record to the specified value.\n\nThis method is equivalent to setStringParameter but does not escape XML reserved characters.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|Name of the SOAP message variable.|\n|value|String|Value to assign to the specified variable.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setStringParameterNoEscape(\"symbol\",\"NOW\");\n```\n\n## SOAPMessageV2 - setWSSecurity\\(String keystoreId, String keystoreAlias, String keystorePassword, String certificateId\\)\n\nSets web service security values for the SOAP message.\n\nSetting security values using this method overwrites web service security values defined for the SOAP message record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|keystoreId|String|Sys\\_id of the Java or PKCS12 key store to use.|\n|keystoreAlias|String|Alias that identifies the public and private keys.|\n|keystorePassword|String|Password assigned to the key store record.|\n|certificateId|String|Sys\\_id of the trusted server certificate.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar sm = new sn_ws.SOAPMessageV2(\"StockQuote\",\"GetQuote\"); //Might throw exception if message doesn't exist or not visible due to scope.\nsm.setWSSecurity(\"70d65e074f3812001f6eac118110c71a\",\"Quote keys\",\"UXr82cqX75Z7MaSa+EyjGA==\",\"ba969a074f3812001f6eac118110c76d\");\n```\n\n"}}