Start of change

Specifying customized SOAP headers with DFSCSHEADERS and DFSCSHEADER elements

You can specify a DFSCSHEADERS XML element (tag) and one or more DFSCSHEADER elements that contain the XML-format data to include in the SOAP header.

The DFSCSHEADERS element is a container to identify a set of information to include in the SOAP header. Within the DFSCSHEADERS element, one or more DFSCSHEADER child elements contain the elements for SOAP Gateway to place in the SOAP header in the envelope that will be sent to the external server.

The following generic example shows how to specify these elements in the control data area of an ICAL call. 


<DFSCSHEADERS>
  <DFSCSHEADER>
    <customHeader1> ... </customHeader1>
  </DFSCSHEADER>
  <DFSCSHEADER>
    <customHeader2> ... </customHeader2>
  </DFSCSHEADER>
</DFSCSHEADERS>

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

<soapenv:Envelope>
  <soapenv:Header>
    <customHeader1> ... </customHeader1>
    <customHeader2> ... </customHeader2>
  </soapenv:Header>
  <soapenv:Body> 
    <bodyElements> ... </bodyElements>
  </soapenv:Body> 
</soapenv:Envelope>
If you specify DFSCSHEADERS and DFSCSHEADER elements within the control data area of the ICAL call, observe the following guidelines:
Usage guidelines Error scenarios
Specify only one DFSCSHEADERS element in the ICAL control data area.

You can specify the DFSCSHEADERS element before or after any element in the ICAL control data area, but do not specify the DFSCSHEADERS element within another element in the area.

 If the area contains multiple DFSCSHEADERS elements, SOAP Gateway takes the following actions:
  • Processes the first DFSCSHEADERS element
  • Ignores the other DFSCSHEADERS elements (and their contents)
  • Issues a warning message
  • Continues processing the SOAP header
Within the DFSCSHEADERS element, do not specify any elements other than DFSCSHEADER elements. If an element other than DFSCSHEADER element is specified within the DFSCSHEADERS element, SOAP Gateway takes the following actions:
  • Ignores the non-DFSCSHEADERS element
  • Issues a warning message
  • Continues processing the SOAP header
Within the DFSCSHEADERS element, specify at least one DFSCSHEADER element.

You can specify as many DFSCSHEADER elements as you need.

 If no DFSCSHEADER element is specified, SOAP Gateway takes the following actions:
  • Does not add a SOAP header element to the envelope
  • Issues a warning message
  • Continues processing the control data area
Specify the contents of each DFSCSHEADER element as one or more well-formed XML documents, with self-contained names, namespaces, attributes, prefixes, and so on. If any XML format errors are present in any DFSCSHEADER element, SOAP Gateway takes the following actions:
  • Ignores all DFSCSHEADER elements
  • Issues a warning message
  • Continues processing the control data area

The following example shows a typical definition of the DFSCSHEADERS element in a COBOL program:

05 HEADERS.
      10  HEADERS-LLLL  PIC 9(9) USAGE BINARY.
      10  HEADERS-BGN   PIC X(14) VALUE '<DFSCSHEADERS>'.
      10  HEADERS-DAT   PIC X(4800) VALUE SPACES .
      10  HEADERS-END   PIC X(15) VALUE '</DFSCSHEADERS>'.

The following example shows a typical specification of DFSCSHEADER and DFSCSHEADER elements and their contents in the control data area of an ICAL call:

<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>

Given this specification, SOAP Gateway sends the following SOAP header information in the envelope to the external server: 

<?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>
  </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>
End of change