WebSphere Message Brokers
File: ac60020_
Writer: Kevin Safford

Reference topic

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

SOAPEnvelope node

This topic describes the SOAPEnvelope 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, which is designed to be used with the SOAPExtract node, adds a SOAP envelope onto an existing message. The default behavior is to attach the SOAP envelope from a standard location ($LocalEnvironment/SOAP/Envelope) in the LocalEnvironment tree; you can specify an explicit location by using an XPath expression.

You can also use the node in a flow without a corresponding SOAPExtract node; the node has an option to create a default SOAP envelope.

The SOAPEnvelope node is represented in the workbench by the following icon:

Filter node icon

Using the SOAPEnvelope 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 SOAPEnvelope node

When you have put an instance of the SOAPEnvelope 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. In Create New Envelope, specify whether the node should create a SOAP envelope, or use an existing one. The default value is to use an existing one.
    2. In Existing Envelope Location, specify an XPath expression that represents the location from which the node will copy the SOAP envelope. By default the node copies the envelope from the LocalEnvironment ($LocalEnvironment/SOAP/Envelope).

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 SOAPEnvelope 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 that was constructed from the SOAP message body and a SOAP envelope.
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 SOAPEnvelope 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 SOAPEnvelope node are described in the following table.

Draft comment:
What are the M and C settings for each of these options?

Property M C Default Description
Create New Envelope     Cleared This property controls whether the node creates a SOAP envelope, or gets an existing one from the message tree. If you select the check box, the node creates a new envelope. If you clear the check box, the node copies the envelope from the value entered in the Existing Envelope Location property.
Existing Envelope Location    

$LocalEnvironment/
SOAP/
Envelope

An XPath expression that represents the location from 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.

Example SOAP messages

Incoming SOAP 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>

Incoming SOAP message body

<?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>

Outgoing 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>
Related reference
SOAPExtract node
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

ac60020_ This topic's URL is: