IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Gateway operation mode for SOAP nodes

The SOAPInput, SOAPRequest, and SOAPAsyncRequest nodes have two operation modes: WSDL mode, and Gateway mode.

If the node is configured to be in WSDL mode, which is the default, the web service operations performed by the node are specified by a WSDL that configures the node. In Gateway mode, SOAP nodes in a message flow handle generic SOAP request messages in the following scenarios.

Provider scenario: In a provider scenario, IBM® Integration Bus receives generic SOAP/HTTP or SOAP/JMS requests by using a SOAPInput node, and sends a reply to the originating client by using a SOAPReply node. A single SOAPInput node can receive any SOAP request message, and is not configured with a WSDL.
Consumer scenario: In a consumer scenario, IBM Integration Bus can route a SOAP request to any external web service provider by using the SOAPRequest node or a pair of SOAPAsyncRequest and SOAPAsyncResponse nodes. Endpoint information can be specified in the local environment, which is used dynamically at run time to send the outbound request message.
Façade scenario: In a façade scenario, IBM Integration Bus can receive SOAP requests from multiple different clients, and route them to any one of multiple back end web service providers, or existing systems. Endpoint information for the back-end web service provider can be specified dynamically at run time by setting values in the local environment.

The SOAP nodes act and are configured differently in the two different operation modes.

If you configure a node in Gateway mode, some node properties are disabled because they are not applicable in Gateway mode.
- The WSDL-specific properties are disabled when the node is switched to Gateway mode. The values are not cleared, and can be used if the node is switched back to WSDL mode.
- The Response Message Parsing properties on the SOAPRequest node are disabled in Gateway mode.
- Validation of the operation according to the WSDL does not take place because no WSDL exists against which to validate in Gateway mode. If a SOAPAsyncRequest and SOAPAsyncResponse node pair is used in Gateway mode, the validation properties on the SOAPAsyncResponse node are disabled at run time, regardless of the validation settings in the BAR file.
- No message set is associated with the node, and no schema is used. Therefore, no message validation takes place in Gateway mode. You can configure the flow downstream to enable validation.
- Outbound MTOM is not supported in Gateway mode because validation cannot take place. However, you can enable validation, and therefore enable MTOM, by setting the Message Set in the local environment. For example:
```
SET OutputRoot.Properties.MessageSet = 'myMessageSet';
```
  You might need to also enable validation on the Compute node or the SOAPReply node.
- In the User-defined SOAP headers table on the SOAPInput node, all operations are set to *. The WSDL-defined SOAP headers table is cleared.
Transport properties must be configured. The transport-specific properties are mandatory depending on the Transport property; for example, the JMS transport properties are mandatory if the selected transport is JMS.
A SOAPInput node can only be configured to receive messages of a single specified transport, for example, HTTP. Use separate input nodes to send or receive messages with different transports.
A SOAPRequest node can only be configured to send messages of a single specified transport, for example, JMS. However, you can change the transport for any message using the local environment.
A SOAPAsyncRequest node can only be configured to send and receive messages over a single transport, for example, JMS, and this transport is always used for the paired SOAPAsyncResponse node to receive the response message. However, you can change the outbound request transport for any message by using the local environment. For example, if a SOAPAsyncRequest node is configured to use JMS transport, its paired SOAPAsyncResponse node always expects to receive responses over JMS, and this cannot be changed. At run time, the SOAPAsyncRequest node also then assumes JMS as the default transport. However, you can instruct it to instead send the request over HTTP by using the local environment. This request includes the WSA:ReplyTo JMS address for the SOAPAsyncResponse node.
If a SOAPInput node receives a one-way SOAP request, the node attempts to detect that it is a one-way message. However, the node cannot detect all cases, and therefore it is sometimes necessary to instruct the SOAPReply node that it is a one-way message, by using the local environment. For example:
```
SET OutputLocalEnvironment.Destination.SOAP.Reply.Gateway.OneWay = True;
```
For more information, see One-way messages in Gateway mode.
If you use the SOAPAsyncRequest node in Gateway mode, you must set the WS-Addressing Action property in the local environment in the message flow before the SOAPAsyncRequest node. Set this property by using OutputLocalEnvironment.Destination.SOAP.Request.WSA.Action.
If you use the SOAPRequest node in Gateway mode and the remote service provider expects a SOAPAction, set the SOAPAction in the flow. In Gateway mode the SOAPAction from a WSDL is not available to the node. For example, to set the SOAPAction using ESQL:
```
SET OutputRoot.HTTPRequestHeader.SOAPAction = 'mySoapAction';
```
By default the SOAPRequest node sends an empty SOAPAction of "".
If you use the SOAPRequest node in Gateway mode and are using WS-Addressing, you must set the WS-Addressing Action property in the local environment in the message flow before the SOAPRequest node. Set this property by using OutputLocalEnvironment.Destination.SOAP.Request.WSA.Action.
In Gateway mode, you can add inbound "must understand" headers to the SOAPInput node or to the SOAPRequest and SOAPAsyncRequest nodes by specifying the details on the node property. However, if you will be adding services dynamically, where all the "must understand" headers cannot be known in advance, you can add these headers with a wildcard (*) for name, namespace, operation, or any combination of the three. This removes the need to redeploy your message flow when new services are added. However, consider that if you add a wildcard for the name, namespace, and also operation, this means that all headers with a "must understand" flag are allowed into the flow.
If you use the SOAPReply node as part of a façade message flow, with the SOAPInput node set to Gateway mode, and the SOAPRequest node acting in WSDL mode, disable validation on the SOAPReply node or add an explicit Message Set in the Properties folder as documented above. If you do not disable validation or reference a Message Set in the Properties folder, parsing errors occur when the message is serialized.
In Gateway mode, the SOAP nodes send SOAP 1.1 messages by default, although they also accept inbound SOAP 1.2 messages. To send an outbound SOAP 1.2 message, set the SOAP.Context field to indicate that SOAP 1.2 is required. For example, to set this field using ESQL:
```
SET OutputRoot.SOAP.Context.SOAP_Version = '1.2';
```
The outbound message then uses a SOAP 1.2 SOAP Envelope. You can also set the namespace prefix used by the SOAP Envelope. For example, by using ESQL:
```
DECLARE soapenc NAMESPACE 'http://www.w3.org/2003/05/soap-envelope';
SET OutputRoot.SOAP.Context.Namespace.(SOAP.NamespaceDecl)xmlns:soap12 = soapenc;
SET OutputRoot.SOAP.Context.SOAP_Version = '1.2';
```
In this example, soap12 is the prefix used in the outbound message.

bc19040_.htm |

Last updated Friday, 21 July 2017