Specifying customized SOAP headers with non-DFS-prefixed elements

You can specify user-defined, "non-DFS-prefixed" elements that SOAP Gateway collects and places into the SOAPHEADERFORUSERDATA container element in the SOAP header.

These elements must have names that do not start with the reserved DFS prefix. During SOAP header processing, SOAP Gateway collects and places these non-DFS-prefixed elements into the SOAP envelope within a placeholder element. This element has a predefined header name (SOAPHEADERFORUSERDATA), prefix (icalcdextras), and namespace (”http://www.ibm.com/ims/soapgateway/icalcd/extras”).

The following generic example shows how non-DFS-prefixed elements might be specified in the control data area of an ICAL call. This example includes DFS-prefixed elements, in addition to DFSCSHEADERS and DFSCSHEADER elements, to show that the elements can be specified in any order.

<DFSPORTNAME>content</DFSPORTNAME>
<non-DFS-prefixed-element1> ... </non-DFS-prefixed-element1>
<DFSCSHEADERS>
  <DFSCSHEADER>
    <customHeader1> ... </customHeader1>
  </DFSCSHEADER>
  <DFSCSHEADER>
    <customHeader2> ... </customHeader2>
  </DFSCSHEADER>
</DFSCSHEADERS>
<DFSCVTNR>content</DFSCVTNR>
<non-DFS-prefixed-element2> ... </non-DFS-prefixed-element2>
<DFSENDPOINTURL>content</DFSENDPOINTURL>

From these elements, SOAP Gateway would create a corresponding SOAP message as follows:

<soapenv:Envelope>
  <soapenv:Header>
    <customHeader1> ... </customHeader1>
    <customHeader2> ... </customHeader2>
    <SOAPHEADERFORUSERDATA xmlns:icalcdextras=”http://www.ibm.com/ims/soapgateway/icalcd/extras”>
      <non-DFS-prefixed-element1> ... </non-DFS-prefixed-element1>
      <non-DFS-prefixed-element2> ... </non-DFS-prefixed-element2>
    </SOAPHEADERFORUSERDATA>
  </soapenv:Header>
  <soapenv:Body> 
    <bodyElements> ... </bodyElements>
  </soapenv:Body> 
</soapenv:Envelope>

If you specify non-DFS-prefixed elements in the control data area of the ICAL call, observe the following guidelines:

Usage guidelines	Error scenarios
You can specify non-DFS-prefixed elements before or after DFS-prefixed elements and before or after other non-DFS-prefixed elements. Do not specify non-DFS-prefixed elements directly within the DFSCSHEADERS element. You can specify as many non-DFS-prefixed elements as you need.	If an element other than DFSCSHEADER element is specified within the DFSCSHEADERS element, SOAP Gateway takes the following actions: Ignores the non-DFSCSHEADER element Issues a warning message Continues processing the SOAP header
Specify the contents of all non-DFS-prefixed elements as well-formed XML documents, with self-contained names, namespaces, attributes, and prefixes.	If any XML format errors are present, SOAP Gateway takes the following actions: Ignores the element and its contents Issues a warning message Continues processing the SOAP header If multiple non-DFS-prefixed elements are specified and one contains an error but the others do not, SOAP Gateway takes the following actions: Ignores the erroneous element Continues to process the other elements

The following example shows a typical definition of non-DFS-prefixed element in a COBOL program:

05 USERS1. 
     10  USERS1-LLLL  PIC 9(9) USAGE BINARY.
     10  USERS1-BGN   PIC X(12) VALUE '<TESTUSERS1>'.
     10  USERS1-DAT   PIC X(600) VALUE SPACES .
     10  USERS1-END   PIC X(13) VALUE '</TESTUSERS1>'.
 
  05 USERS2.
     10  USERS2-LLLL  PIC 9(9) USAGE BINARY.
     10  USERS2-BGN   PIC X(12) VALUE '<TESTUSERS2>'.
     10  USERS2-DAT   PIC X(600) VALUE SPACES .
     10  USERS2-END   PIC X(13) VALUE '</TESTUSERS2>'.

The following example shows a typical specification of non-DFS-prefixed elements and their contents (in a bold typeface) in the control data area of an ICAL call:


<TESTUSERS1>
  <cc:maxRelayTime xmlns:cc="http://ibm.com" value="10000" 
  role="http://www.w3.org/2003/05/soap-envelope/role/next" 
  relay="true" />
</TESTUSERS1>
<DFSCSHEADERS>
  <DFSCSHEADER>
    <hns:header soapenv:mustUnderstand="0" 
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hns="http://ws.apache.org/axis2" 
      name1="value1" name2="val2"> 
      <From><item><key>PartyId</key><value>www.example.com@example.com</value></item></From>
      <To><item><key>PartyId</key><value>webservices.sabre.com</value></item></To>
      <CPAId>XXX</CPAId>
      <ConversationId>12345@example.com</ConversationId>
      <Service>Session</Service>
      <Action>SessionCreateRQ</Action>
      <MessageData>
        <item><key>MessageId</key><value>mid:12345@www.example.com</value></item>
        <item><key>Timestamp</key><value>2010-11-26T08:19:00Z</value></item>
      </MessageData>
    </hns:header>
  </DFSCSHEADER>
  <DFSCSHEADER>
    <hns2:header2 soapenv:mustUnderstand="0" 
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hns2="http://ws.my.org/axis2" 
      name1="value1" name2="val2"> 
      <From><item><key>PartyId</key><value>www.example.com@example.com</value></item></From>
      <To><item><key>PartyId</key><value>webservices.sabre.com</value></item></To>
      <CPAId>XXX</CPAId>
      <ConversationId>12345@example.com</ConversationId>
      <Service>Session</Service>
      <Action>SessionCreateRQ</Action>
      <MessageData>
        <item><key>MessageId</key><value>mid:12345@www.example.com</value></item>
        <item><key>Timestamp</key><value>2014-09-27T08:19:00Z</value></item>
      </MessageData>
    </hns2:header2>
  </DFSCSHEADER> 
</DFSCSHEADERS>
<TESTUSERS2>
  <cc:Account_spcService_Account_spcServiceQueryPage_Input 
    xmlns:cc="http://ibm.com/CustomUI">accountA  
  </cc:Account_spcService_Account_spcServiceQueryPage_Input> 
</TESTUSERS2>

Given this specification, SOAP Gateway creates the SOAPHEADERFORUSERDATA element to contain the non-DFS-prefixed elements in the SOAP header as follows:

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soapenv:Header> 
    <hns:header xmlns:hns="http://ws.apache.org/axis2" soapenv:mustUnderstand="0" 
      name1="value1" name2="val2"> 
      <From><item><key>PartyId</key><value>www.example.com@example.com</value></item></From>
      <To><item><key>PartyId</key><value>webservices.sabre.com</value></item></To>
      <CPAId>XXX</CPAId>
      <ConversationId>12345@example.com</ConversationId>
      <Service>Session</Service>
      <Action>SessionCreateRQ</Action>
      <MessageData>
        <item><key>MessageId</key><value>mid:12345@www.example.com</value></item>
        <item><key>Timestamp</key><value>2010-11-26T08:19:00Z</value></item>
      </MessageData>
    </hns:header>
    <hns2:header2 xmlns:hns2="http://ws.my.org/axis2" soapenv:mustUnderstand="0" 
      name1="value1" name2="val2"> 
      <From><item><key>PartyId</key><value>www.example.com@example.com</value></item></From>
      <To><item><key>PartyId</key><value>webservices.sabre.com</value></item></To>
      <CPAId>XXX</CPAId>
      <ConversationId>12345@example.com</ConversationId>
      <Service>Session</Service>
      <Action>SessionCreateRQ</Action>
      <MessageData>
        <item><key>MessageId</key><value>mid:12345@www.example.com</value></item>
        <item><key>Timestamp</key><value>2014-09-27T08:19:00Z</value></item>
      </MessageData>
    </hns2:header2>
  <SOAPHEADERFORUSERDATA 
    xmlns:icalcdextras="http://www.ibm.com/ims/soapgateway/icalcd/extras">
      <TESTUSERS1>
        <cc:maxRelayTime xmlns:cc="http://ibm.com" value="10000" 
        role="http://www.w3.org/2003/05/soap-envelope/role/next" 
        relay="true" />
      </TESTUSERS1>
      <TESTUSERS2>
        <cc:Account_spcService_Account_spcServiceQueryPage_Input 
          xmlns:cc="http://ibm.com/CustomUI">accountA
        </cc:Account_spcService_Account_spcServiceQueryPage_Input> 
      </TESTUSERS2>
    </SOAPHEADERFORUSERDATA>
  </soapenv:Header>
  <soapenv:Body>
    <p1:Hello xmlns:p1="http://www.example.org/HELLO/">
      <CALLOUT-REQUEST-STR>A message from IMS  </CALLOUT-REQUEST-STR>
    </p1:Hello>
  </soapenv:Body>
</soapenv:Envelope>