The SOAP header is an optional element of a soap request or response. In the header section, meta information on the actual soap message can be set. These meta information can hold additional information about routing of the message, information on encryption or affiliation to a transaction.
The SOAP header can only exist once within a message and has to be the first element within the SOAP envelope. The header though can consist of multiple SOAP header elements. These header blocks are identified via a unique URI and, through that, can be assigned to specific nodes within the message structure. Through this mechanism, the SOAP message stays flexible and can be extended by specifying additional header blocks. The communicating partners do not need any specifications on these header blocks.
The content of these headers can be of any information. A typical usage in practice would be the transfer of security information or setting a transaction ID as the following example shows:
<?xml version="1.0" ?> <env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> <env:Header> <login:security xmlns:login="http://example.com" env:role="http://example.com/Login" env:mustUnderstand="true"> <login:username>Simon Sample</login:username> <login:password>aPassword</login:password> </login:security> <bridge:TransactionID xmlns:bridge="http://e2e.ch/bridge">dkdme44546kkjdkcvdfldkjvopinmoisf</bridge:TransactionID> </env:Header> <env:Body > ... ... </env:Body> </env:Envelope>
SOAP Headers in the E2E Bridge
Within the E2E Bridge, it is important to differentiate between the following scenarios:
- SOAP headers going into a SOAP call via an adapter within a service (activity setSOAPHeaderClient in above mentioned example)
- SOAP headers of the called SOAP service itself (activity returnSOAPHeaderServer in above mentioned example)
Setting the Headers before calling a SOAP adapter
The following screenshot shows a SOAP adapter call with the SOAP headers being set beforehand.
<?xml version="1.0" ?> <env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> <env:Header> <login:security xmlns:login="http://example.com" env:role="http://example.com/Login" env:mustUnderstand="true"> <login:username>Simon Sample</login:username> <login:password>aPassword</login:password> </login:security> <bridge:TransactionID xmlns:bridge="http://e2e.ch/bridge">dkdme44546kkjdkcvdfldkjvopinmoisf</bridge:TransactionID> </env:Header> <env:Body > ... ... </env:Body> </env:Envelope>
Class | Attribute | Type | SOAP Attribute | Description | Example XML Fragment |
---|---|---|---|---|---|
SOAPHeaderElement | encoding | String | encodingStyle | Specifies the encoding style used to construct the message. | env:encodingStyle="http://www.w3.org/2003/05/soap-encoding" |
header | Blob | - | The header holds the actual header data of base type Blob. | ||
mustunderstand | Boolean | mustUnderstand | This attribute says whether or not the recipient (indicated by the role attribute) is required to process a header entry. | env:mustUnderstand="true" | |
name | String | - | Holds the name of a header block. | ||
namespace | String | - | Defines the namespace to be assigned to the header element serialized with use="encoded". | ||
relay | Boolean | relay | If relay is set to true, it indicates that the SOAP header block must not be processed by any node that is targeted by the header block, but must only be passed on to the next targeted node. | env:relay="true" | |
role | String | role | The role is optional and defines the recipient of the header message. | env:role="http://example.com/Login" |