See information about the latest product version
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.
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:
Using the SOAPExtract node in a message flow
You can view information about samples only when you use the information center that is integrated with the WebSphere® Message Broker Toolkit or the online information center. You can run samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit.
Configuring the SOAPExtract node
When you have put an instance of the SOAPExtract 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.
- Optional: On the Description tab, enter a Short description, a Long description, or both. You can also rename the node on this tab.
- On the Basic tab:
- Specify in Remove envelope whether the node must remove the soap envelope and place it in the location given in Envelope Destination, or leave it on the message. The default value is that the node removes the envelope.
- In Envelope Destination, enter an XPath expression that represents the destination to which the node will copy the envelope. By default, the node copies the envelope to the LocalEnvironment ($LocalEnvironment/SOAP/Envelope).
- In Destination path mode,
specify the behavior of the Envelope Destination property.
- Create path: The node creates the tree if the path specifies a location that does not already exist. Only simple expressions of the form aaa/bbb/ccc in Envelope Destination are supported. The default.
- XPath location of existing element: If you know that the destination element exists, you can use any valid XPath 1.0 expression in Envelope Destination.
- In Route to 'operation' label, specify whether the node must route the message to the SOAP operation given in the message. The default setting is for the node to send the message to the Out terminal.
- In Label Prefix, enter the value to prefix to the label used for routing by the node. Entering a prefix allows for name spacing between subflows. By default, no value is prefixed to the label name used for routing the message.
Supported parsers
- SOAP
- XMLNSC
- MRM
- XMLNS
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:
|
Destination path mode | No | No | Create path | This determines the behavior of the Envelope Destination property. Set
this property:
|
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. |
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 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>