Start of change
WebSphere Message Brokers
File: ac60010_
Writer: Kevin Safford

Reference topic

This build: July 31, 2007 21:21:30

SOAPExtract node

This topic describes the SOAPExtract node.

Draft comment:
Which category in the workbench contains this node (for example, WebSphere MQ, JMS, HTTP, ...) I need to add this information to page ac04550_ in the infocenter.

This topic contains the following sections:

Purpose

This node can 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 within one node because they are often used together.

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 within the message flow as identified by the SOAP operation within the message. This is the tag under the SOAP body tag representing the message payload.

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 across 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 represented in the workbench by the following icon:

Filter node icon

Using the SOAPExtract node in a message flow

Look at the following sample to see how to use this node:

Draft comment:
How do I get the reference of the sample?
You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

Configuring the SOAPExtract node

When you have put an instance of the SOAPExtract node into a message flow, you can configure it. The properties of the node are displayed in the Properties view.

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Basic tab:
    1. Specify in Remove Envelope whether the node should 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.
    2. 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).
    3. 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. This is the default setting.
      • 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.
    4. In Route to ‘Operation’ Label, specify whether the node should 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.
    5. In Label Prefix, enter the value to prefix to the label used for routing by the node. This is to allow for name spacing between subflows. By default, no value is prefixed to the label name used for routing the message.

Supported parsers

This node is designed to work with SOAP messages. Use one of the following parsers:
  • SOAP
  • MRM using XML: using a message definition generated by the WSDL importer.
  • XMLNS: using self-describing XML.
  • XMLNSC: using self-describing XML.
Non-XML and 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 Yes   Selected
Draft comment:
What are the M and C settings for each of these options?

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    

$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     Create Path This determines the behavior of the Envelope Destination property. Set it as follows:
Create Path
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     Cleared This determines whether the node should 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’ WDSL 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       The value to prefix to the label that the node uses for routing. This is to allow for name spacing between subflows.
Related reference
SOAPEnvelope node

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>
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:30

ac60010_ This topic's URL is:
End of change