SOAPAsyncResponse node

Use the SOAPAsyncResponse node in conjunction with the SOAPAsyncRequest node to construct a pair of message flows that call a web service asynchronously.

The SOAPAsyncResponse node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale

For more information, see Operation modes.

This topic contains the following sections:

Purpose
Using this node in a message flow
Terminals and properties
LocalEnvironment overrides

Purpose

The SOAPAsyncRequest node sends a web service request, but the node does not wait for the associated web service response to be received. However, the SOAPAsyncRequest node does wait for the HTTP 202 acknowledgment before continuing with the message flow, and the SOAPAsyncRequest node blocks if the acknowledgment is not received. The web service response is received by the SOAPAsyncResponse node, which can be in a separate message flow. The nodes are used as a pair, and correlate responses against the original requests.

Diagram showing the relationship between the SOAPAsyncRequest node and the SOAPAsyncResponse node.

The SOAP parser invokes the XMLNSC parser to parse the XML content of the SOAP web service, and to validate the XML body of the SOAP web service. The SOAP parser options are passed through to the XMLNSC parser. For more information, see Manipulating messages in the XMLNSC domain.

The SOAPAsyncResponse node is contained in the Web Services drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

SOAPAsyncResponse node icon

Using this node in a message flow

Configuration of the SOAPAsyncResponse node is not WSDL-driven, although the 'must understand headers' list configured on the corresponding SOAPAsyncRequest node is applicable to the SOAPAsyncResponse node.

Most configuration options for this node are set on its paired SOAPAsyncRequest node, including the Backout destination and Backout threshold properties. No SOAP fault is sent when the backout threshold is reached.

You can retrieve context data that has been stored by the SOAPAsyncRequest node from the following location in the local environment:

LocalEnvironment.SOAP.Response.UserContext

If either of the local environment properties LocalEnvironment.Destination.SOAP.Response.ReplyIdentifier or LocalEnvironment.Destination.HTTP.RequestIdentifier were provided to the paired SOAPAsyncRequest node, these are passed to the local environment for the SOAPAsyncResponse node.

The SOAPAsyncResponse node can receive a response that has a Content-Encoding of gzip or deflate. When such a response is received, the content is decoded and the Content-Encoding header is removed.

Terminals and properties

When you have put an instance of the SOAPAsyncResponse node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The SOAPAsyncResponse node terminals are described in the following table.

Terminal	Description
Failure	The output terminal to which an asynchronous SOAP response message is routed if a failure is detected when the message received is propagated to the Out flow (such as a message validation failure).
Out	The output terminal to which the asynchronous SOAP response message is routed if it has been successfully received, and if further processing is required in this message flow. If no errors occur in the node, a valid none fault SOAP response message received from an external resource is always sent to the Out terminal first.
Fault	The output terminal to which an asynchronous SOAP fault response is routed if it has been successfully received, and if further processing of the fault is required in this message flow.
Catch	The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The SOAPAsyncResponse node Description properties are described in the following table.

Property	M	C	Default	Description
Node name	No	No	The node type: SOAPAsyncResponse	The name of the node.
Short description	No	No	None	A brief description of the node.
Long description	No	No	None	Text that describes the purpose of the node in the message flow.

The SOAPAsyncResponse node Basic properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Unique identifier	Yes	No		Specify the unique URL fragment that is common to your pair of SOAPAsyncRequest and SOAPAsyncResponse nodes.	asyncRequestCorrelator

The SOAPAsyncResponse node Transactions property is described in the following table. This setting does not apply when the node uses HTTP transport.

Property	M	C	Default	Description
Transaction mode	Yes	No	No	This property controls whether the message is received under a JMS transaction. Valid values are Yes and No. Select No to receive the message using a non-transactional JMS session. Select Yes to receive the message using a transactional JMS session. The JMS transaction can be either local or XA coordinated. To use an XA coordinated transaction, using an XA JMS session, you must also select the message flow property Coordinated Transaction in the BAR file properties. See Configuring JMS and SOAP nodes for local transactions.

Property

Default

Description

Transaction mode

Yes

This property controls whether the message is received under a JMS transaction. Valid values are Yes and No.

Select No to receive the message using a non-transactional JMS session.

Select Yes to receive the message using a transactional JMS session. The JMS transaction can be either local or XA coordinated. To use an XA coordinated transaction, using an XA JMS session, you must also select the message flow property Coordinated Transaction in the BAR file properties.

See Configuring JMS and SOAP nodes for local transactions.

The SOAPAsyncResponse node Advanced property is described in the following table.

Property	M	C	Default	Description
Set destination list	No	No	Selected	This property indicates whether to add the incoming SOAP operation to the route to label destination list.
Label prefix	No	No		Use this property to add a prefix to the SOAP Operation name in the destination list. You must add a Label prefix if you want to use multiple SOAPAsyncResponse nodes in the same message flow without causing their corresponding Label nodes to clash. By default, the prefix is an empty string so that the operation name and the label name are identical. This property is not available if the Set destination list property is cleared.
Place WS-Addressing headers into LocalEnvironment	No	No	Cleared	This property specifies whether the node puts WS-Addressing headers from the response message into the local environment tree. WS-Addressing headers are not accessible to the flow if this check box is cleared because by default, all headers are processed and removed.

The SOAPAsyncResponse node Instances properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Additional instances pool	No	Yes	Use Pool Associated with Message Flow	The pool from which additional instances are obtained. If you select Use Pool Associated with Message Flow, additional instances are obtained from the message flow value. If you select Use Pool Associated with Node, additional instances are allocated from the node's additional instances based on the number specified in the Additional instances property.	componentLevel
Additional instances	No	Yes	0	The number of additional instances that the node can start if the Additional instances pool property is set to Use Pool Associated with Node. By default, no additional instances are given to the node.	additionalInstances

The SOAPAsyncResponse node Response Message Parsing properties are described in the following table. The SOAPAsyncResponse node sets these properties automatically; you cannot set them yourself.

Property	M	C	Default	Description
Message domain	No	No	SOAP	The domain that is used to parse the response message. By default, the message that is propagated from the SOAPAsyncResponse node is in the SOAP domain. You cannot specify a different domain. For more information, see SOAP parser and domain. The Response Message Parsing properties are ignored when the paired SOAPAsyncRequest node is configured to act in gateway mode.
Message model	Yes	No	Set automatically from the WSDL file name property that is provided by the SOAPAsyncRequest node.	The name or location of the message model schema file in which the response message is defined. Message model is set automatically to the project that contains the WSDL file that is configured on the corresponding SOAPAsyncRequest node. If you set this property, and then subsequently update the project dependencies to remove this message model reference, a warning is issued. Either update the Message model property, or restore the reference to this message models. The Response Message Parsing properties are ignored when the paired SOAPAsyncRequest node is configured to act in gateway mode.
Message	No	No		The name of the response message. The node detects the message type automatically. You cannot set this property.
Physical format	No	No		The name of the physical format of the response message. You cannot set this property.

The SOAPAsyncResponse node Parser Options properties are described in the following table. The properties are passed through to the XMLNSC parser.

Property	M	C	Default	Description
Parse timing	No	No	On Demand	This property controls when a response message is parsed. Valid values are On Demand, Immediate, and Complete. By default, parse timing is set to On demand, which causes parsing of the input message to be delayed. For a full description of this property, see Parsing on demand.
Build tree using XML schema data types	No	No	Selected	This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML Schema. This property is ignored when the paired SOAPAsyncRequest node is configured to act in gateway mode.
Retain mixed content	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a response message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain comments	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an response message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain processing instructions	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a response message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements	No	No	Blank	This property is used to specify a list of elements in the response message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled.

The SOAPAsyncResponse node Validation properties are described in the following table. By default, validation is enabled.

If a message is propagated to the Failure terminal of the node, it is not validated. For more details, see Validating messages and Validation properties.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	No	Yes	Content and value	This property controls whether validation takes place. Valid values are None, Content and value, and Content. Validation properties are ignored when the paired SOAPAsyncRequest node is configured to act in gateway mode.	validateMaster
Failure action	No	No	Exception	This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and value. Valid values are User trace, Exception list, Local error log, and Exception. Validation properties are ignored when the paired SOAPAsyncRequest node is configured to act in gateway mode.

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.

LocalEnvironment overrides

You can retrieve information that was set by the paired SOAPAsyncRequest node from the following property under LocalEnvironment.Destination.SOAP.Response :

Setting	Description
UserContext	You can retrieve context data that was stored by the SOAPAsyncRequest node from the following location in the local environment: `SET myVar = InputLocalEnvironment.Destination.SOAP.Response.UserContext;`