SOAP Execute
In this article
Breaking change for Pipelines using the SOAP Execute Snap
Before the 4.25 release, the SOAP Execute Snap was used to preserve the empty XML elements in the envelope irrespective of selecting the Preserve input empty elements checkbox. After upgrading to 4.25 GA, the Snap might fail due to missing empty XML elements. In such cases, select the Preserve input empty elements checkbox to resolve the issue. If the failure persists then contact the support team.
Snap type: | Write | |||||||
---|---|---|---|---|---|---|---|---|
Description: | This Snap calls the SOAP endpoint using the incoming data and writes out a SOAP response.
Clicking Customize Envelope will attempt to generate a SOAP envelope based on the information defined in the properties and the selected WSDL. The action will launch the XML Editor.
In general, you will most likely always use Customize Envelope. All files referred to in WSDLs hosted in SLDB must be either explicit URLs or relative in the same project. For example, if the WSDL refers to an XSD "Projects/SomeSchema.xsd", this must be changed (in the WSDL) to refer to the file in the same project "SomeSchema.xsd", and the XSD should be put in that same folder. The envelope will be stored in the Snap after clicking OK. Further, the envelope can be exported to SnapLogic's file system using the export action or be imported from there using the import action. The Generate template action will regenerate the template, but the content of the editor must be removed prior to that. The envelope can be customized to meet specific endpoint needs. The Snap is fully configured and executable once the envelope is finalized. The generated envelope will have velocity references in it. These references (here, $session_id) will be exposed to the Target Schema column of the upstream Mapper or Structure Snap. However, any changes made by the user in the generated envelope won't be reflected to this Target Schema column. In this case, the user has to remember the references added/modified in the generated envelope to map them in the upstream Snap. Template generation only works with document-style WSDLs. RPC-style WSDL template generation is currently not supported. To execute a create request through an NTLM account in the SOAP Execute Snap, use the generic envelope similar to the following sample. This ensures the output is rendered as excepted. See the example for a demo on how this works. Only a sample envelope This sample is meant only for reference purposes and must not be replicated. In the upstream Mapper or Structure Snap, these references can be mapped to static values (such as 1234) or to the references exposed in the Input Schema column. We map the reference session_id in the upstream Mapper (Data) Snap in the example below. Note that the content of the editor must be saved prior to selecting the schema upstream.
The SOAP Execute Snap is a writing Snap. The Snap can be executed during preview to allow executing the defined request and to retrieve data and schema from the response. The SOAP Snap can be executed during the save operation by enabling the Snap Execution option. If you receive the following error: "reach the innerElementCountThreshold:50000", perform one of the following tasks:
These properties are available only in a Groundplex. How to use the default value for substitutionTo use the Default value for substitution property of the Snap:
ExampleIncoming document: Here, the session_id element doesn't exist in the incoming document. In this case, using Default value for substitution will give us the following envelope: <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0="http://api.clickatell.com/soap/webservice"> <SOAP-ENV:Header /> <SOAP-ENV:Body> <ns0:ping> <session_id>NO VALUE</session_id> </ns0:ping> </SOAP-ENV:Body> </SOAP-ENV:Envelope> If you don't specify the Default value for substitution and don't select the Use default value for substitution property, the elements will be removed from the envelope recursively. | |||||||
Prerequisites: | None | |||||||
Support and limitations: |
Breaking Change The HTTP header field's behavior in the SOAP Execute Snap is changed. Specifying only a key is not sufficient. Both key and value must be provided when invoking a task. | |||||||
Account: | This Snap uses account references created on the Accounts page of SnapLogic Manager to handle access to this endpoint. See Configuring SOAP Accounts for information on setting up this type of account. | |||||||
Views: |
| |||||||
Snap Settings | ||||||||
Field Name | Description | |||||||
Label* | Specify the name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline. | |||||||
WSDL Url* | Specify the URL for the WSDL. WSDL File URL is case sensitive. Example: http://www.webservicex.net/stockquote.asmx?WSDL | |||||||
Service Name* | Specify the system function that has been exposed to Web-based protocols. Example: http://www.webserviceX.NET/}StockQuote | |||||||
Endpoint* | Specify the endpoint (in WSDL 2.0 terminology)/Port name (in WSDL 1.1 terminology). Whenever presented with multiple port versions, always select the latest one. Example: {http://www.webserviceX.NET/}StockQuote | |||||||
Operation* | Specify the operation to invoke Example: GetQuote | |||||||
Timeout* | Specify the timeout for the web service call (in seconds). 0 indicates no timeout. Default value: 0 | |||||||
Encode Attribute | Select this checkbox to differentiate the attributes from XSD with an '@' prefix in the input schema and "at-" prefix in the template. Default value: Deselected | |||||||
Default value for substitution | This value will be used for substitution for the leaf elements which are not objects and/or not enclosed in an array. If nothing is specified and Use default value for substitution is selected, an empty string will be used for substitution. | |||||||
Use default value for substitution | If you select this checkbox:
| |||||||
Preserve input empty values | Select this checkbox to preserve any empty value within the input data in the SOAP request. If you select Use default value for substitution checkbox, then this field is ignored. | |||||||
Include root element | Select this checkbox to include root element in the body or header in the keys generated in the envelope template. Default value: Not selected | |||||||
Trust all certificates | Select this checkbox to trust all certificates, such as self-signed certificates. Default value: Not selected | |||||||
Remove illegal characters | Select this checkbox to remove illegal UTF characters based on XML 1.0 standard. | |||||||
Escape special characters | Select this checkbox to enable the Snap replace the XML special characters in XML template variable values with the respective character entity references ( The special characters that the Snap escapes are: >, <, &, ', " Default value: Selected. | |||||||
Enable MTOM | Select this checkbox to enable content processing to multipart, application/xop+xml type. When Message Transmission Optimization Mechanism (MTOM) processing is enabled, binary files will be transmitted outside the SOAP request envelope as a MIME attachment. XML-binary Optimized Packaging (XOP) should then be used to reference the attachment within the SOAP request envelope. The following example shows how contents of the file, salesforce_sample.csv, are inserted into the SOAP response and what updates are required to the Snap. After selecting the Enable MTOM Processing field, the following updates to the Snap are required for successful execution:
Default value: Not selected | |||||||
Output SOAP envelope | Select this checkbox to output the whole SOAP envelope instead of just the SOAP body | |||||||
WS Addressing | Creates and configures an addressing feature with the use of addressing requirements. It enables WS-Addressing, that is it supports WS-Addressing but does not require its use. It also configures to accept all the response types. Default value: Not selected | |||||||
Output HTTP response headers | Select this checkbox to output the HTTP headers in the response. Default value: Not selected | |||||||
SSL Protocol | Advance setting, leave blank to allow Java default. | |||||||
Response to null SOAP call return value* | Specify an action to be taken when a SOAP call returns an empty response. The default action is Output no documents. You can handle SOAP call with an empty response in the following ways:
Default value: Output no documents | |||||||
Maximum request attempts | Specify the maximum number of attempts to be made to receive a SOAP response. The SOAP request is terminated if the attempts do not result in a SOAP response. If no value specified, only 1 attempt is made before terminating a SOAP request. Default value: 3 | |||||||
Retry interval | Specify the interval between two successive SOAP requests. A retry happens only when the previous attempt resulted in an exception. Default value: 2 | |||||||
Success condition | An expression to match success criteria in the SOAP response. Example: (with expression toggle on) $['SOAP-ENV:Body']['ns2:orderResponse']['ns2:result'] == "success" This would match the success criteria in this SOAP response: [ { "SOAP-ENV:Body": { "@xmlns:SOAP-ENV": "http://schemas.xmlsoap.org/soap/envelope/", "ns2:orderResponse": { "@xmlns:ns2": "http://www.Snaplogic.com/Snapbox/order", "ns2:result": "success", "ns2:transactionId": "533822" } } } ] You can see that the user can find the SOAP output by setting Snap Execution on the SOAP Execute Snap, then seeing what comes out. You can also hook up a Mapper Snap and see the schema there. You can do that on the input view, but not the output view. | |||||||
Customize envelope | Launches the XML editor which will generate a SOAP envelope based on the defined properties, WSDL URL, Service name, Port name and Operation. The editor will load an envelope if it was defined previously. The editor allows you to save SOAP envelopes in SnapLogic's file system or import existing SOAP envelopes from it. The /wiki/spaces/AP/pages/1438085 template can be used to pass dynamic values from upstream Snaps.
See https://velocity.apache.org/engine/1.7/vtl-reference.html#unparsed-content for more information. | |||||||
HTTP header | Use this field set to define HTTP header key-value pairs. You must provide both key and value when invoking a task. | |||||||
Attachments | Use this field set to add attachments. | |||||||
Allow duplicate headers | Select this checkbox to allow duplicate headers value. If not selected, then the last value of the duplicate header key is used. Default Value: Not selected | |||||||
Standardize error output | Select this checkbox to view the document in error view (a standardized error document will show up in the error view)—error, reason, resolution, stack trace and original. Default value: Not selected | |||||||
Route all exceptions to error view | Select this checkbox to route the Snap exceptions generated by WSDL Url, Service Name, Endpoint and Operation properties to the error view and successfully execute the pipeline execution. Default value: Not selected | |||||||
Import WSDL documents | Select this checkbox to import the external documents while reading the WSDL file. The files that are declared with tag name wsdl:import & xs:import are retrieved and processed. If this checkbox is not selected, then the external documents that are required for WSDL are ignored. Default value: Selected | |||||||
Transfer type | The Snap uses each input document as a body of one SOAP request. There are two ways of transferring the request body to the endpoint: 'Chunked transfer encoding' or 'Calculate content length'. If 'Chunked transfer encoding' is selected and when the message size is greater than 4KB, the SOAP request will be sent using chunked transfer encoding. Otherwise, the request will not be chunked and the Content-Length header will be included in the request. If a SOAP endpoint does not support 'Chunked transfer encoding', this property should be set to 'Calculate content length'. If the endpoint responds with an error of HTTP status code "411 Length Required", the Snap automatically retries the request with 'Calculate content length' mode. Default value: Chunked transfer encoding | |||||||
Library API | This property enables Snap execution over HTTP. Use the appropriate library to utilize the latest SOAP capabilities. The available options are:
Default value: Apache CXF We recommend using HttpComponents, because Apache no longer maintains CXF v2. | |||||||
Snap execution | Select one of the three modes in which the Snap executes. Available options are:
Default value: Execute only |
Managing Data Cache Duration
Whenever you provide resources, such as WSDLs and XSDs, in SOAP-based Snaps, SnapLogic caches the data for some time. The default cache duration is four hours. You can modify this to any positive number by updating the global properties for the Snaplex. See Configuration Options for information on defining the cache duration.
This is not applicable when the SOAP Snaps call a third-party SaaS, such as NetSuite, since the cache duration is determined by the SaaS.
See it in Action
Example
Create a new record in MS Dynamics AX using SOAP Execute Snap
This example demonstrates how you can use the SOAP Execute Snap to create records in MS Dynamics AX.
The Mapper Snap creates the input JSON for the SOAP Execute Snap through a series of mappings.
The SOAP Execute Snap uses the JSON input to create a new record in the MS Dynamics AX through a SOAP POST request. It uses the generic envelope to populate the fields in the endpoint.
The image below shows a preview of the output:
This output shows the result of the create operation and also populates the original dataset under original key.
Mapping of Variables from Target Schema to SOAP Execute Envelope Template
This example will help you in understanding about the working of envelope template variable substitution using Include root element check box.
Let us take an example where we are making a call to the login operation for Salesforce's SOAP API (WSDL).
Here is the pipeline consisting a Mapper Snap and SOAP Execute Snap with credentials defined as Pipeline parameters.
Upon validating the pipeline, Target Schema will be defined for the Mapper. Once this is available, we can define the Target path variables from the Target Schema.
Here, in the SOAP Execute Snap, we are checking the Include root element checkbox which ideally is not checked by default.
Upon regenerating the template we can observe the expected and correct variable substitution being performed.
Also, as we have included the Debugging output, we can see the correct substitution.
For more info, see Using the debug Output View
Using the debug Output View
You can add a second output view named debug (all lower-case) to view the details of the SOAP request. For every SOAP call, the Snap writes two separate output documents to the debug view. The first document contains the request headers and envelope. The second document contains the response data.
For example, consider the following SOAP Execute Snap with two output views:
Below is a snapshot of the output from both output views:
output0 (default output) | debug |
---|---|
See Also
Snap Pack History
Have feedback? Email documentation@snaplogic.com | Ask a question in the SnapLogic Community
© 2017-2024 SnapLogic, Inc.