Software AG Products 10.7 | Integrating On-Premises and Cloud Applications | Integration Server Built-In Services | SOAP Folder | Summary of Elements in this Folder | pub.soap.handler:addHeaderElement
 
pub.soap.handler:addHeaderElement
WmPublic. Deprecated - Replaced by pub.soap.handler:addHeaderBlock.
Inserts a document into a SOAP message as a new header element (block).
Input Parameters
messageContext
Object Message context containing the SOAP message to which to add a header element.
A message context contains properties for the SOAP message and provides access to the SOAP message. Integration Server creates the message context and passes it to the header handler. All handlers invoked by a given instance of a SOAP request or SOAP response use the same message context, which enables you to use the message context to pass information among handlers.
QName
Document Optional. Qualified name (namespace name and local name) of the header element to add.
The QName document references the pub.soap.utils:QName document type.
Note:
If you do not specify QName value, you must specify documentType.
headerDocument
Document Document to add as a header element. Integration Server converts the document to an XML node and inserts it as a child element of the header element specified in QName.
documentType
String Optional. Name of the IS document type that specifies the structure and namespaces of the document to use as a new header element. Integration Server uses the universal name assigned to the IS document type to determine the qualified name to use for the new header element. If you specify documentType, headerDocument must be a instance of this document type.
Note:
If you do not specify documentType, you must specify QName.
mustUnderstand
String Optional. Sets the value of the mustUnderstand attribute for the new header element (block). The mustUnderstand attribute specifies whether recipients (the actor or role at which the header is targeted) are required to process a header entry. Recipients that cannot process a mandatory header entry must reject the message and return a SOAP fault.
Set to:
*true to indicate that processing the header entry is optional.
*false to indicate that processing the header entry is mandatory.
There is no default value.
If you do not set mustUnderstand, Integration Server omits the mustUnderstand attribute from the header entry, which is equivalent to setting mustUnderstand to false.
Note:
In SOAP 1.2, the values of the mustUnderstand attribute changed from 0 and 1 to True and False; however, Integration Server processes both sets of values the same and performs any necessary conversions.
actor
String Optional. Target of the header entry. The value of actor determines the value of the actor or role attribute for the header entry. The actor or role attribute specifies a URI for the recipient of a header entry.
If you do not specify a value for actor, the actor or role attribute will be blank in the SOAP header. In SOAP 1.1, this indicates that the recipient is the ultimate destination of the SOAP message. In SOAP 1.2, this is equivalent to supplying that attribute with the value "http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver".
Note:
In SOAP 1.2, the actor attribute is named role; however, Integration Server processes both names the same and performs any necessary conversions.
Output Parameters
None.
Usage Notes
QName and documentType are mutually exclusive. Even though the parameters are optional, you must specify one or the other. If you do not specify either, Integration Server displays the following error:
[ISS.0088.9422] One of the mutually exclusive parameter QName or
documentType is missing or invalid.
If you specify values for QName and documentType, Integration Server uses the QName value and ignores documentType.
For more information about the mustUnderstand and actor attributes in SOAP 1.1, see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/.
For more information about the mustUnderstand and role attributes in SOAP 1.2, see the Simple Object Access Protocol (SOAP) 1.2 specification at http://www.w3.org/TR/SOAP12/.
Example
Suppose that messageContext contains a SOAP message with an empty SOAP header and you want to add a header element by passing the pub.soap:handler:addHeaderElement service the following input parameters:
Input Parameter
Provided Value
QName
namespaceName
userHandlerNamespaceName
localName
userHandlerLocalName
headerDocument
An instance of documentTypes:myNewHeader, which contains a single field of type String named myString. The value of myString is: Value of myString field.
documentType
Not provided.
mustUnderstand
true
actor
soapActor
Execution of the pub.soap.handler:addHeaderElement service results in this SOAP header for SOAP 1.1:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<HDR:userHandlerLocalName
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:HDR="userHandlerNamespaceName"
SOAP-ENV:actor="soapActor" SOAP-ENV:mustUnderstand="1">
<myString>Value of myString field.</myString>
</HDR:userHandlerLocalName>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Integration Server uses HDR as the namespace prefix for the namespace name of the header.
See Also
pub.soap.handler:getHeaderElement
pub.soap.handler:removeHeaderElement