How InterSystems IRIS Represents SOAP Headers

InterSystems IRIS® data platform represents each header element as an instance of %SOAP.HeaderOpens in a new tab or one of its subclasses. %SOAP.HeaderOpens in a new tab is an XML-enabled class with properties that correspond to the standard header element attributes (mustUnderstand, actor, and encodingStyle).

InterSystems IRIS provides specialized subclasses of %SOAP.HeaderOpens in a new tab for use with WS-Addressing and WS-Security. To represent custom header elements, you create your own subclasses of %SOAP.HeaderOpens in a new tab.

When an InterSystems IRIS web service or client receives a SOAP message, it imports and processes the message. During this step, if the message contains a header with custom header elements, InterSystems IRIS compares the header elements to the list of supported header elements (discussed in the next subsection).

Then the service or client creates an instance of each applicable header element class, inserts those into an array, and places that array in its own HeadersIn property:

SOAP Header elements El1 and El2 are placed in an array of headers by InterSystems IRIS

To use these header elements, your InterSystems IRIS web service or client can access the HeadersIn property. If the SOAP message did not include a <Header> element, the Count() of the HeadersIn property is 0.

Similarly, before your InterSystems IRIS web service or client sends a SOAP message, it must update the HeadersOut property so that it contains any custom elements you want to include in the outbound message. If the HeadersOut Count() is 0, the outbound SOAP message does not include a <Header> element.

The headers El1 and El2 that are in an InterSystems IRIS array are placed in the header of the SOAP message

For custom header elements, you always use the HeadersIn and HeadersOut properties.

The details are different for other (non-custom) header elements:

For WS-Addressing, use the AddressingIn and AddressingOut properties rather than the HeadersIn and HeadersOut properties. See Adding and Using WS-Addressing Header Elements.
For WS-Security header elements, use the WS-Policy features, described in Securing Web Services.
Or directly use the SecurityIn and SecurityOut properties, discussed in Securing Web Services. This is generally more work.
(Note that the WS-Security header elements are also contained in the HeadersIn and HeadersOut properties, b´ut it is not recommended to access them or to set them via those properties.)
InterSystems IRIS SOAP session support uses the HeadersIn and HeadersOut properties. See SOAP Session Management.

Supported Header Elements