Manipulate SOAP Headers in BPEL

Background

BPEL's communication activities (invoke, receive, reply and onMessage) provide means of receiving or sending messages via specified message variables. These default activities allows one vairable each way. For example: the invoke activity has inputVariable and outputVariable attributes. You can specify one variable for each of the two attributes. This is enough if the particular operation involved ueses only one payload message each way.

However, WSDL supports more than one message in an operation. In the case of SOAP, multiple messages care be sent along the main payload message as SOAP headers. BPEL's default communication activities fall short in this case as they cannot accomodated the additional header messages.

OraBPEL solves this problem by extending the default BPEL communication activities with the bpelx:headerVariable. The syntax of the extension are:

<invoke bpelx:inputHeaderVariable="inHeader1 inHeader2 ..."
  bpelx:outputHeaderVariable="outHeader1 outHeader2 ..."

  .../>


<receive bpelx:headerVariable="inHeader1 inHeader2 ..." .../>


<onMessage bpelx:headerVariable="inHeader1 inHeader2 ..." .../>

<reply bpelx:headerVariable="inHeader1 inHeader2 ..." .../>

Here are the samples.

The samples also currently in BPEL cvs repository under /collaxa/qa/src/bpel/headers/. These samples are used here to illustrate the usage of the extended attributes. To check out the sample, please refer to this page.

Implentation status

This feature is built for some POC customers. It's not fully QAed and is not advertised for the 10.1.2 release.

Usage

Receiving SOAP Headers in BPEL

Take HeaderTest BPEL process under /collaxa/qa/src/bpel/headers/. Here are the steps.

1. Author the WSDL to declare header messages and the SOAP binding that binds them to the SOAP request.

  <message name="MessageIDHeader">
    <part name="MessageID" element="wsa:MessageID"/>
  </message>
  <message name="ReplyToHeader">
    <part name="ReplyTo" element="wsa:ReplyTo"/>
  </message>

  <!-- custom header -->
  <message name="CustomHeaderMessage">
    <part name="header1" element="tns:header1"/>
    <part name="header2" element="tns:header2"/>
  </message>

  <binding name="HeaderServiceBinding" type="tns:HeaderService">
    <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="initiate">
      <soap:operation style="document" soapAction="initiate"/>
        <input>
          <soap:header message="tns:ReplyToHeader" part="ReplyTo"
            use="literal"/>
          <soap:header message="tns:MessageIDHeader" part="MessageID"
            use="literal"/>
          <soap:header message="tns:CustomHeaderMessage"
            part="header1" use="literal"/>
          <soap:header message="tns:CustomHeaderMessage"
            part="header2" use="literal"/>
          <soap:body use="literal"/>
        </input>
    </operation>
  </binding>

2. Author the bpel source to declare the header message variables. And use bpelx:headerVariable to receive the headers.

<variables>
  <variable name="input"
             messageType="tns:HeaderServiceRequestMessage"/>
  <variable name="event"
             messageType="tns:HeaderServiceEventMessage"/>
  <variable name="output"
             messageType="tns:HeaderServiceResultMessage"/>
  <variable name="customHeader"
             messageType="tns:CustomHeaderMessage"/>
  <variable name="messageID"
             messageType="tns:MessageIDHeader"/>
  <variable name="replyTo"
             messageType="tns:ReplyToHeader"/>
</variables>

<sequence>
  <!-- receive input from requestor -->
  <receive name="receiveInput" partnerLink="client" 
    portType="tns:HeaderService" operation="initiate" 
    variable="input"
    bpelx:headerVariable="customHeader messageID replyTo" createInstance="yes"/>

Sending SOAP Headers in BPEL

Take HeaderTest process under /collaxa/qa/src/bpel/headers/ as an example.

1. Define the partnerLinkBinding definition in bpel.xml as you normal to refer to the HeaderService WSDL.

2. Define the custom header variable, manipuate it, and send it using bpelx:inputHeaderVariable.

<variables>
  <variable name="input" messageType="tns:HeaderTestRequestMessage"/>
  <variable name="output" messageType="tns:HeaderTestResultMessage"/>
  <variable name="request" messageType="services:HeaderServiceRequestMessage"/>
  <variable name="response" messageType="services:HeaderServiceResultMessage"/>
  <variable name="customHeader" messageType="services:CustomHeaderMessage"/>
</variables>

...
<!-- initiate the remote process -->
  <invoke name="invokeAsyncService" partnerLink="HeaderService"
    portType="services:HeaderService"
    bpelx:inputHeaderVariable="customHeader"
    operation="initiate" inputVariable="request"/>