How to Manipulate SOAP Headers in BPEL

Now Web Services are the De facto standard to implement SOA for any organization. Web Services are self contained, self descriptive and open standard based. Everyone who is implementing web services needs to follow the same standards. W3C, OASIS, and WS-I standardizes these open standards. These standard can be applied to a new service as well as an existing service and it is the beauty of these standards. WS-* standards are based on the SOAP headers so you don't need to touch the web service implementation. To support these standards the BPEL specification implementation should have inbuilt capabilities to manipulate SOAP headers.

If we talk about Oracle BPEL Process Manager (Oracle's implementation of BPEL specification) it is having SOAP header manipulation capabilities through BPEL extensions. You can send or receive SOAP headers from a BPEL process using bpelx:inputHeaderVariable, bpelx:headerVariable extensions.

To send SOAP headers from the BPEL process you need to use bpelx:inputHeaderVariable extension in the invoke activity, just give a comma separated list of all the variables you want to send in the SOAP header. To receive SOAP headers you need to use bpelx:headerVariable extension in the receive activity. Once you add these extensions in the receive or invoke activity your part is over and the BPEL Process Manager will add your variables to SOAP header if you are invoking a web service or extract SOAP headers if you are using receive activity and assign SOAP headers to the specified variables.

Sending or receiving SOAP headers from Oracle BPEL is very simple, you need to create messages inside WSDL, variables in BPEL process and then need to use bpelx:inputHeaderVariable and bpelx:headerVariable extensions. See the following to understand how to add bpelx:inputHeaderVariable and bpelx:headerVariable into the invoke, receive, onMessage and reply activities respectively:

<receive name="receiveInput" partnerLink="client" portType="client:TestProcess"
operation="process" variable="inputVariable" createInstance="yes" bpelx:headerVariable="yourVariable1, yourVariable2"/>

<invoke name="Invoke_1" partnerLink="NestedSchemaTest"
portType="ns1:NestedSchemaTest" operation="process"
inputVariable="Invoke_1_process_InputVariable" outputVariable="Invoke_1_process_OutputVariable" bpelx:inputHeaderVariable="yourVariable1, yourVariable2 .." bpelx:outputHeaderVariable="yourVariable1, yourVariable2 ..."/>

If you are invoking an asynchronous process then don't use bpelx:outputHeaderVariable extension.

<onMessage bpelx:headerVariable="variable_1 variable_2 ..." />
<reply bpelx:headerVariable="variable_1 variable_2..." />

Deploy your BPEL process and use TCP protocol monitor or obtunnel to see the SOAP headers in the SOAP envelop. Don't forget to set the "optSoapShortcut" property to "false" otherwise you wont be able to see the SOAP headers in obtunnel or TCP monitor. From oracle 10.1.3.1 this property is not available on the BPEL control so you need to add it in the <BPEL Home>/domains/<domain>/config/domain.xml as given below:

<property id="optSoapShortcut">
   <name>Optimize SOAP invocations.</name>
   <value>false</value>
   <comment></comment>
</property>

How to Make Libraries Available to BPEL Process

I have seen many integration developers struggling with the classpath settings in Oracle SOA Suite. If you don't know the right place to store libraries or the configuration files where you can add required libraries, you can easily waste hours or even days to make libraries available to your BPEL process.

While developing Oracle BPEL Process you need to add the required libraries in Jdeveloper. To add a library in Jdeveloper right click on the BPEL Process project and select “Project Properties” from the context menu. Click on Libraries in the Project Properties tree. From Libraries page you can add a predefined library or you can add jars or folders in the classpath.

If you want to use standalone ant scripts to compile and build your BPEL process flow you need to set classpath in ant build scripts. You need to add libraries in the bpelc task. Add your libraries as given below, add a pathelement for each library:

<classpath>
 <pathelement location="Library you want to add into classpath"/>
</classpath>

If you want to use common jars in multiple projects, add the files into classpath of obsetenv.bat or obsetenv.sh based on the platform you are using to run ant build scripts. Edit the obsetenv file and add the libraries in the MY_CLASSPATH variable. e.g.

set MY_CLASSPATH=%Existing Libraries%;<new libraries>

If you are using Java embedding activity in your BPEL process and this activity is referring classes and jars those are not part of the BPEL suite case , you need to add those libraries in the classpath of BPEL Process compiler. BPEL Process Manager generates Java files and compile them at the deployment time so it is required to set all the referenced libraries in BPEL compilers classpath.

You can add the referenced libraries in BPEL Process compiler's classpath by modifying the domain.xml or from the BPEL Process Manager's Console. I am mentioning both procedures, you can use any of them.

• Edit Domain Configuration file-

  • Edit <Oracle SOA Home>/bpel/domains/<Domain Name>/config/domain.xml

• Add referenced libraries the file as given below:
  <property id="bpelcClasspath">
  <name>BPEL process compiler classpath</name>
  <value>list of jars separated by ; or : based on the platform you are using</value>
  </property>

• Restart Oracle BPEL Server.

• Use BPEL Process Manager Console

  • Open BPEL Process Manager Console and click on “Manage BPEL Domain”. Go to Configuration tab.

  • Enter all the referenced libraries(including path of the libraries); in the value field of bpelcClasspath property..

  • Click on Apply button.

  • Restart Oracle BPEL Process Manager..
    

  After deployment you will definitely want to test the BPEL process. You need to add the required libraries into Oracle Application Server's classpath, so the referenced libraries would be available for your BPEL process at runtime. Follow the steps given below to add libraries into Oracle Application Server's classpath:

• Open <Oracle Home>/j2ee/home/config/application.xml and find a shared library named oracle.bpel.common.

• Add <code-source path="Your library path"/> for each required jar file. You can create a separate library and import it inside the oracle.bpel.common shared library.

Insert New Line Character in BPEL Payload

Today my colleague has an interesting requirement. He need to interact with a legacy application which accepts input in CSV format. In the input first row should contain operation name, second row should contain all the column names and the next row is the data row. He was using Oracle BPEL to integrate legacy application with new application infrastructure. He was having data in a canonical business object and want to generate the required input CSV format.

The major challenge for him was to transform the business object into the input CSV which is having three rows. As he was a Java developer in the past, he tried using \n to insert new line character with no luck. Then he tried &#13; which is the correct one to insert a new line character in an XML payload but when he executed the BPEL flow, &amp;#13; was inserted rather than the line break.

The trick to insert the new line character in XML payload from Oracle BPEL is to append &#13; in the from expression of assign activity, then check your .bpel file it would have &amp;#13; rather than &#13; because Jdeveloper replaces & with its equivalent escape character &amp;. You need to replace &amp; with & so it would become the correct new line character &#13;.