Transport map for a web service (SOAP) transport

The Transport Map panel allows you to define the content of the HTTP based SOAP request to an enterprise business application published as a web service. With this panel you will be able to:

Query the web service metadata from a Web Services Definition Language (WSDL) file from the file system or a URL
Select the operation that will be invoked
Specify input and output logical variables and how they map to the SOAP message
Specify array dimensions for the data sent to the web service and the response data returned from the web service
Specify elements that need to be skipped
Specify the content of an optional WSDL specification 1.1 SOAP Header parameter

SOAP adapter in Transaction Server supports only Document Style of WSDL. The advantage of using a Document style model is that you can structure the SOAP body any way you want it as long as the content of the SOAP message body is any arbitrary XML instance. The Document style model use literal as encoding, When using a literal use model, the body contents should conform to a user-defined XML-schema (XSD) structure. The advantage is two-fold. For one, you can validate the message body with the user-defined XML-schema, moreover, you can also transform the message using a transformation language like XSLT. Bellow you'll find examples of Document Style of WSDL.

Assumptions

The following is assumed:

You are familiar with the structure of a WSDL file
You are dealing with a WSDL specification version 1.1 WSDL file
You have a good understanding of the application level aspects of the web service you are integrating with.

Defining a web service (SOAP) transport map

Using the Workbench, access the node and navigate to the Transport Map definition panel. Click New to display a Transport Map definition panel
Click the Transport Type drop-down and select WS_SOAP
Click the Transport Name drop-down and select a previously defined web service transport
Enter the location of the WSDL in the WSDL Address parameter as shown and then select the Query button. This action will prompt the Workbench to connect to the URL specified and parse the various sections (types, messages, portType, binding, service) of the WSDL. The Workbench will use the connection timeout specified in the web service (SOAP) transport to determine how long to wait for a successful response from the web services server. It will also supply credentials (User and Password ) that are specified in the web service (SOAP) transport in the request to the server.
For information on defining the web service (SOAP) transport and specifying these credentials, see Defining a web service (SOAP) transport.
Alternatively if you are unable to access the WSDL from a web services server you can work with a local copy of the WSDL file.
To do so, select the Browse button to bring up a select file dialog and select the WSDL file from your local file system.
Once the WSDL has been queried the Endpoint URL parameter is automatically populated from the service section of the WSDL.
This is the URL that the Transaction Server will send the SOAP request to when a Transaction action (that references this transport map) is executed.
This field remains editable and can be manually changed to the actual location of the web service. You also have the ability to override this URL when referencing this transport map (transaction action) in a trigger by specifying it in the overrideEndpointURL input field of the action.
The Operations list is automatically populated from the operation names parsed from the portType section of the WSDL.
When defining a web service (SOAP) transport map the first operation is automatically selected. The Workbench will populate the 'To Enterprise' section of the panel with message fields that are parsed from the message and types section of the WSDL, including:
- Fields that are part of the input message will be listed with a Parm Type of IN
- Fields that are part of the output message will be listed with a Parm Type of OUT
- Attributes are displayed in italics.
- Fields that are required are marked with an asterisk.
  - This flag can be cleared by right clicking on the field and selecting "Clear Required Flag". This is only recommended for advanced users and may result in indeterminate results.
- For example:
The Transport Map panel will automatically provide dimension specification parameters to specify the depth of structures. They are represented as Rows In for data being sent to the web service and Rows Out for the response data returned by the web service. You can override the default value of one with an appropriate value based on the needs of your application.
The example below shows the Rows In value specified as 5.

This example shows a Rows Out parameter.
The Workbench can assist in automatically creating Input and Output map variables by selecting the Map Parms button. Once this is done your panel will look similar to the example shown below. The dimensions of map variables associated with structured fields will be set based on the Rows In or Rows Out value.

Specify optional SOAP Header parameters by selecting the Parameters... button in the To Enterprise section. This will bring up an WSDL Parameters panel.

The values entered on this panel will typically be specified by the web service implementation.

Extended Attributes

Parameter	Description
Namespace	Specify the namespace associated with the SOAP header element
Header Element	Specify the element name of the SOAP header parameter
Input Variable	Specify the input variable whose content will appear in the body of the the SOAP header element when the request is sent
Must Understand	Specify the value to be used for the SOAP header mustUnderstand attribute. The options are: false - for mustUnderstand="0" true - for mustUnderstand="1"
Actor	Specify the value to be used for the the SOAP Header actor attribute
Encoding Style	Specify the value to be used for the the SOAP Header encodingStyle attribute
Missing Numerics	If set, numeric elements missing from a reply will be set to zero. Normally, such missing values would be flagged as an error. This can be helpful when getting an arrayed response where previously the entire array of values would not be returned and flagged as an error if at least one element were missing. Setting this will make missing data indistinguishable from valid values of zero, so be certain you're aware of what values of data would be valid in scenarios where this is used.

Request/Response Headers

Header request and response parameters may be specified when submitting a WSDL request

Request Parameters

Parameter	Description
Name	The options are: A constant header parameter value by selecting $CONSTANT A header parameter value obtained from an input variable when the map is used to send a request. To do so select a String input variable from the pick list.
Property	The options are: Enter the key name of the header parameter if you are only specifying the value portion of the header parameter either as a $CONSTANT or a input variable Leave the property value blank or unspecified if you are providing the entire header parameter in a "key=value" format either as a $CONSTANT or an input variable. This allows you to dynamically specify a header property in "key=value" format from a trigger.
Default Value	If you specified $CONSTANT in the Name parameter then enter a constant text. This parameter can also be used to specify the value of the query parameter if the input variable is not specified in the Transaction action in the trigger.

Parameter

Description

Name

The options are:

A constant header parameter value by selecting $CONSTANT
A header parameter value obtained from an input variable when the map is used to send a request. To do so select a String input variable from the pick list.

Property

The options are:

Enter the key name of the header parameter if you are only specifying the value portion of the header parameter either as a $CONSTANT or a input variable

Leave the property value blank or unspecified if you are providing the entire header parameter in a "key=value" format either as a $CONSTANT or an input variable. This allows you to dynamically specify a header property in "key=value" format from a trigger.

Default Value

If you specified $CONSTANT in the Name parameter then enter a constant text. This parameter can also be used to specify the value of the query parameter if the input variable is not specified in the Transaction action in the trigger.

The following keys cannot be used within request parameters as they are reserved keywords:

Connection
Keep-Alive
Content-Type
Accept-Encoding
User-Agent

Response Parameters

Parameter	Description
Name	Use the pick list to select an output variable that the response header value will be mapped to.
Property	Specify the key name of the response header property that will be used to identify the specific response property to be mapped. If multiple response header values that correspond to the same key are to be mapped, you will need to define the output variable as an array with a count greater than 1. An example would be multiple cookie values returned with the 'Set-Cookie' response header key name.
Default Value	An optional value that will be mapped to the output variable if the corresponding response header key name is not found in the response header.

Select the Validate button if you want to view a sample SOAP request message that would be generated by this transport map and a sample SOAP response message expected to be returned to this transport map.
A request is not made to the web service when you select the Validate button.
One Transport Map Output window is displayed. The Sample Request is at the top of the data, the Sample Response is viewed by scrolling down towards the bottom of the data.
For example:
Select the Save button to save the definition to the node.

Referencing a web service (SOAP) transport map from a Transaction action

After a web service (SOAP) transport map is defined and saved (its referenced web service (SOAP) transport was also previously defined and saved), you can define a trigger that uses the Transaction action and references the web service (SOAP) transport map.

The Transaction action Input tab has the parameters that are sent to the web service. These parameters can be any valid device variables or trigger variables.

You also have the ability to change the URL that the web service request is sent to by specifying it in the overrideEndpointURL input field. This value will override the URL specified in the Endpoint URL: field of the transport map.
The Transaction action Output tab has the parameters that are received as a response from the web service. These parameters can be any valid device variables or trigger variables.

For more information on triggers and the Transaction action, see Projects and triggers and Transaction.

An example Transaction action Input tab is shown below. The dimension fields are used to specify the depth of the input arrays that are sent to the web service.

An example Transaction action Output tab is shown below. The output parameter highlighted contains the size of the response data array. This value could be used in the trigger to iterate through the response array (for example, use as a counter in a For loop).