SOAPExtract node

Use the SOAPExtract node to remove SOAP envelopes, allowing just the body of a SOAP message to be processed. It can also route a SOAP message based on its operation name. Both functions are optional; they are contained in one node because they are often used together.

The SOAPExtract 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

The SOAPExtract node can perform two functions:

Extract function: The default behavior is to detach the SOAP envelope to a standard location ($LocalEnvironment/SOAP/Envelope) in the LocalEnvironment tree. Alternatively, you can specify an explicit location using an XPath expression. Any existing SOAP envelope at the chosen location is replaced.
Routing function: The SOAP message is routed to a Label node in the message flow as identified by the SOAP operation in the message. The SOAP Operation is identified in the SOAP body tag.

Ensure that the message parser options in the properties folder of the outgoing message are correctly set up to parse the message, by copying the message set and message format from the incoming message. The message type is derived from the SOAP envelope message body first child.

Only a single child of the SOAP message body is supported.

The SOAPExtract node is contained in the Web Services drawer of the palette, and is represented in the workbench by the following icon:

Filter node icon

Supported parsers

This node is designed to work with SOAP messages. Use one of the following parsers:

SOAP
XMLNSC
XMLNS
MRM

Other XML parsers are not supported because they do not support namespaces. An exception is thrown if a message is received which is not using the correct parser or does not conform to the basic structure of a SOAP message.

Full validation is not done on the SOAP message, which just needs to contain a body element.

Terminals and properties

The terminals of the SOAPExtract node are described in the following table:

Terminal	Description
In	The input terminal that accepts a SOAP message for processing by the node.
Out	The output terminal that outputs the SOAP message body (without the envelope if the Remove envelope check box is selected on the node properties).
Failure	The output terminal to which the message is routed if a failure is detected during processing.

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 Description properties of the SOAPExtract node are described in the following table.

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

The Basic properties of the SOAPExtract node are described in the following table.

Property	M	C	Default	Description
Remove envelope	No	No	Selected	If you select the check box, the node removes the SOAP header from the message. For a SOAP tree, the node outputs to the Out terminal the first child of SOAP.body from the SOAP tree. It outputs to Envelope Destination the full SOAP tree minus the first child of SOAP.body. If you clear the check box, the node leaves the envelope on the message. In the case of a SOAP tree, the full tree is propagated to the Out terminal.
Envelope Destination	No	No	$LocalEnvironment/SOAP/Envelope	An XPath expression that represents the destination to which the node will copy the SOAP envelope. The following correlation names are available: $Root The root of the message tree. $Body The last child of the root of the message tree (equivalent to /). $LocalEnvironment The root of the LocalEnvironment tree. $Environment The root of the Global Environment tree.
Destination path mode	No	No	Create path	This determines the behavior of the Envelope Destination property. Set this property: Create path The default. The tree is created if the path specifies a location that does not exist. Only simple expressions of the form `aaa/bbb/ccc` are supported. XPath location of existing element If you know that the destination element exists, you can enter any valid XPath 1.0 expression.
Route to 'operation' label	No	No	Cleared	This property determines whether the node must route the message to the SOAP operation given in the message. If you select the check box, the message is routed to a Label node that matches the SOAP operation. An exception is thrown if no Label node matches. The name of the first child element of the SOAP body is used to determine the RouteToLabel name. For the ‘RPC literal' and ‘wrapped doc literal' WSDL types, this is the ‘operation' name. For a SOAP tree, the first child of SOAP.Body supplies the operation name. If you clear the check box, the node sends the message to the Out terminal.
Label Prefix	No	No		The value to prefix to the label that the node uses for routing. Entering a prefix allows for name spacing between subflows.

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.

Example SOAP messages

Incoming SOAP message

<?xml version="1.0"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://ws3.st.mqsi.ibm.com/App/DocLiteral1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
    <tns:requestHeader>
        <tns:assessorUrl>header1</tns:assessorUrl>
    </tns:requestHeader>
    </soapenv:Header>
    <soapenv:Body>
        <tns:requestAvailability>
            <tns:carDetails>body1</tns:carDetails>
            <tns:claimID>body2</tns:claimID>
            <tns:location>body3</tns:location>
            <tns:reqDate>body4</tns:reqDate>
        </tns:requestAvailability>
    </soapenv:Body>
</soapenv:Envelope>

De-enveloped message

The operation name is requestAvailability. Note that the namespacing is removed from the operation.

<?xml version="1.0"?>
<tns:requestAvailability
xmlns:tns="http://ws3.st.mqsi.ibm.com/App/DocLiteral1"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tns:carDetails>body1</tns:carDetails>
    <tns:claimID>body2</tns:claimID>
    <tns:location>body3</tns:location>
    <tns:reqDate>body4</tns:reqDate>
</tns:requestAvailability>

Removed envelope

<?xml version="1.0"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://ws3.st.mqsi.ibm.com/App/DocLiteral1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
        <tns:requestHeader>
            <tns:assessorUrl>header1</tns:assessorUrl>
        </tns:requestHeader>
    </soapenv:Header>
</soapenv:Envelope>