How to access the SOAP/Custom Headers in BPEL/ESB or pass the SOAP/Custom Headers from BPEL/ESB?

SOAP headers is a way to pass the data to and from an XML Web service method if the data is not directly related to the XML Web service method's primary functionality. They are primarily used to pass authentication details or any non-functional data. Since BPEL specification also forces to have a interface definition and communication via SOAP, these headers can be leveraged for various non-functional requirements.

How to access the SOAP Headers in BPEL Process or pass the SOAP Headers from BPEL Process?

You need to make some simple modifications to some of the files for accessing the information passed in the SOAP Headers and the steps are as under,

1. Add the definition of the header variable expected in the soap:Header in [process_name].xsd or add the XSD to the BPEL project as under,
   <element name="Header">
   <complexType>
   <sequence>
   <element name="Data" type="string"/>
   </sequence>
   </complexType>
   </element>
   
   
2. Add the namespace, if absent to the [process].wsdl
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   
   
3. Add the message type of the header variable (passed in the soap:Header) in the [process].wsdl
   <message name="Header">
   <part name="Header" element="ns1:Header"/>
   </message>
   Note: ns1 is the namespace of the header variable as mentioned in step1
   
   
4. Add the Header variable under the variable element in the [process].bpel as under,
   <variable name="Header" messageType="ns1:Header"/>
   
   
5. Add the attribute bpelx:headerVariable to the recieve activity element as under,
   <receive name="receiveInput" partnerLink="client"
   portType="client:SyncBPELProcess" operation="initiate"
   variable="inputVariable" createInstance="yes"
   bpelx:headerVariable="Header"/>

Make sure that the namespace declaration of the Header Variable is available in .bpel and .wsdl file.

After making the above mentioned modification to the BPEL Process, you need to manually create the soap:Header if you are using a UI tool for testing the process or develop another BPEL Process that shall call the modified BPEL Process and populate the SOAP Header. Both the ways are simple and steps are as under,

• Manual: Add/Modify the <soap:Header> element to include the Header variable as under,
  <soapenv:Header
  xmlns:soapenv="http://schemas.xmlsoap.org/
  soap/envelope/"
  xmlns:asy="http://xmlns.oracle.com/SyncBPELProcess">
  <asy:Header>
  <asy:Data>HEADER DATA</asy:Data>
  </asy:Header>
  </soapenv:Header>
  
  
• Pass SOAP Header from BPEL Process: Create a new BPEL project (CallBPELProj) and import the definition of the Header Variable in the project. Create a variable(HeaderVariable) of type Header variable in the BPEL project and invoke the Header BPEL project (modified above) and add the attribute bpelx:inputHeaderVariable to the invoke element as under,
  <invoke name="Invoke_1" partnerLink="AsyncBPELProcess"
  portType="ns1:AsyncBPELProcess" operation="initiate"
  inputVariable="Invoke_1_initiate_InputVariable"
  bpelx:inputHeaderVariable="HeaderVariable"/>
  

With all these changes, you shall be able to access the information passed in the SOAP Headers.

There are some pre-defined Header variable, as mentioned in WS-Addressing specification that are passed as SOAP Header for implementing the callback and setting the message destinations in case of Asynchronous invocations. The above modification will work fine in all the cases,

• WS-Client passing the Custom Header variable to BPEL Process(interface may be synchronous or asynchronous)
  
• BPEL Process passing the Custom Header variable to another BPEL Process, invoked synchronously.
• BPEL Process passing the Custom Header variable to another BPEL Process, invoked asynchronously.

If you would like to send the parameters in the SOAP Header as per WS-Addressing specifications, you would need to modify the SOAP envelope and include these parameters, passed to the BPEL Process.

How to access the SOAP Headers in ESB or pass the SOAP Headers from ESB?

The steps for setting or passing the custom header in ESB is well documented over here. The only challenging piece of information that I could not find in the document was how to access the custom header variable when the ESB routing service is called directly using SOAP. You need to access the header variable as under,

<xsl:value-of select=
"ehdr:getRequestHeader('/soap:Header/ns2:
HeaderVariable/ns2:Data',
'soap=http://schemas.xmlsoap.org/soap/envelope/; ns2=http://xmlns.oracle.com/ESBProcess;')"/>

The function getRequestHeader() requires all the namespaces used in the Custom Header Variable along with soap namespace to be specified as the second parameter seperated by ';'