WebSphere

SOAP Header Setter mediation primitive

Use the SOAP Header Setter mediation primitive to create, set, copy or delete SOAP message headers.

Introduction

The SOAP Header Setter mediation primitive provides a mechanism for managing SOAP headers in the message. You can change, copy, add, or delete SOAP headers by setting the mediation primitive properties.

If you want multiple header changes you can set multiple actions. Multiple actions are acted on sequentially, in the order you specify; this means that header changes can build on each other.

You can search for SOAP headers that already exist in the service message object (SMO) by specifying values to match on. If matching headers are found, they can then be deleted from the message, copied to another location in the SMO, or have fields set to specified values. If matching headers are not found, new headers can be created using specified header field values.

The SOAP Header Setter mediation primitive has one input terminal (in), one output terminal (out) and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message. If the mediation is successful, the out terminal propagates the modified message. If an exception occurs during the transformation, the fail terminal propagates the original message, together with any exception information contained in the failInfo element.

Details

You can create a new SOAP header and specify the values it contains. The new SOAP header element is added to the service message object (SMO) by appending it to the end of the SOAP header list.

You can also find specific SOAP headers, in the list of SOAP headers that a message contains, and set or update the header values.

Alternatively, you can copy the first SOAP header that matches your search criteria to another location in the SMO (either in the SMO context or body).

Finally, you can find specific SOAP headers in the list of SOAP headers that a message contains, and delete the headers.

You can set the SOAP header elements that you want to work with, using a wizard. Depending on whether you want to create, set, copy, or delete headers, the wizard presents different options. For example, to create a new header, the wizard would help you to set the following properties: Create > Name, Namespace, and Type > Set Values. Alternatively, to update values in existing headers the wizard would help you to set the following properties: Find and Set > Name, Namespace, and Type > Search Values > Set Values.
Note: Firstly, you set the values for the search, and then you set the values for the updates.

Defining the search criteria can be relatively complex, because a SOAP message can contain multiple SOAP headers with the same name. When you define the search criteria you can specify the SOAP header name, type, and namespace, as well as the values of certain fields. For example, you might want to search for all SOAP header of type WS-Addressing. Alternatively, you might want to search for a SOAP header that contains a field called name whose value is Smith.

Generally, you specify the field values of SOAP headers, using either a literal value or an XPath expression.

Usage

You can use the SOAP Header Setter mediation primitive to ensure that when a SOAP message is sent to another system, the headers that are sent with the message are correctly set.

Because the operations you define occur sequentially, a later operation can depend on an earlier operation. For example, you could create a new header, copy it to elsewhere in the SMO and then delete it from the list of headers it was initially appended to.

You can also use the SOAP Header Setter mediation primitive to help to filter messages, using the Message Filter mediation primitive. You might want to find a particular header and make it available to be used in the filtering. For example, you could copy a SOAP header to a more accessible place, and the Message Filter primitive could then use the details inside the header. You might need to use the Set Message Type mediation primitive between the SOAP Header Setter primitive and the Message Filter primitive, (in order to do type casting).

Properties

SOAP Header Elements
A table of actions that you want to perform on SOAP header elements, in the SMO. You can add to this table by clicking Add. Then follow the instructions of the wizard.
Note: You might need to add references to the header type schemas you want to use.
Header Action
The action you want to perform on SOAP headers.
  • If you want to create a new SOAP header, set the Header Action to Create.
  • If you want to search for SOAP headers and then either set the values in any headers that are found or create a new header if none are found, set the Header Action to Find and Set.
  • If you want to search for SOAP headers and then copy the first header that is found to another location in the SMO, set the Header Action to Find and Copy.
  • If you want to search for SOAP headers and then delete any headers that are found, set the Header Action to Find and Delete.

Header Element
Details of the SOAP header element that you want to create or search for. You can select header element details by clicking Browse.
Name
The name of the SOAP header element.
Namespace
The namespace of the SOAP header element.
Type
The type of the SOAP header element.
Search Values
The SOAP header values that you want to search for, in the message SOAP headers. You can set each value to be either a literal value or an XPath expression, which is resolved at run time to provide the value to search with.

Used only when the Header Action is Find and Set, Find and Copy or Find and Delete.

Set Values
The SOAP header values that you want to amend or create, in the message SOAP headers. You can set each value to be either a literal value or an XPath expression, which is resolved at run time to provide the value. The value provided must be compatible with the field where it is to be set. For example, if the field is of type int, the value could validly be 14, but not GoldAccount

Used only when the Header Action is Create or Find and Set.

If the Header Action is set to Find and Set, the wizard lets you use Search Values to define the search criteria, and then use Set Values to specify the values you want to set (when the search is satisfied).

Target Destination
If the Header Action is set to Find and Copy, the Search Values property should be an XPath 1.0 expression that identifies the target destination. The first SOAP header to be found is copied to the target destination.

Validate Input
If true, causes the input message to be validated before the mediation is performed.
Table 1. SOAP Header Setter mediation primitive properties
Property Valid Values Default
SOAP Header Elements Header Action String: Create, Find and Set, Find and Copy or Find and Delete Create
Header Element Name    
Namespace    
Type    
Search Values The values are dependent on the Type you select
Note: Used only when the Header Action is Find and Set, Find and Copy or Find and Delete
 
Set Values The values are dependent on the Type you select
Note: Used only when the Header Action is Create or Find and Set
 
Target Destination String: An XPath expression
Note: Used only when the Header Action is Find and Copy
 
Validate input Boolean: true or false false

Considerations

Consider the following when using the SOAP Header Setter mediation primitive:


reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:40:01 BST (DRAFT)


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.wbit.help.medprim620.doc/ref/rwesb_SOAPHeaderSettermediationprimitive.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).
iDoc on