How to write a BPEL extension for WSO2 BPS 1.1.0 and Apache ODE

You may always wanted to write your own BPEL activity to handle your scenario. This article will go through step by step process to implement a simple BPEL extension activity for WSO2 BPS and Apache ODE.

WSO2 Business Process Server (BPS) is an easy-to-use open source business process server that executes business processes written using the WS-BPEL standard. It is powered by Apache ODE (open source BPEL engine) and provides a complete Web-based graphical console to deploy, manage and view processes in addition to managing and viewing process instances.

Implementation of Extension Bundle

Create a class by implementing one of the ExtensionOperation interfaces which are available at [1]. The run* method of this class should contain the implementation of the extension activity. You can find a sample implementation of this class at [2].

Then You have to create a class by implementing AbstractExtensionBundle interface. Within this class, the above implemented ExtensionOperation class should be registered. A sample implementation can be found at [3].

Configure WSO2 BPS

There are two methods to expose the extension classes to BPS.

• Creating a jar.
  
  Copy the jar to BPS_HOME/repository/components/lib directory.
  
• Creating an OSGI bundle
  
  Copy the bundle to BPS_HOME/repository/components/dropins directory.
  

Add the following configuration entry to the bps.xml file in BPS_HOME/conf directory. Repalce org.wso2.bps.samples.extension by your extension class name.

Note: By default, the sample extension bundles shipped with WSO2 BPS are copied to BPS_HOME/repository/components/lib. You have to add the following configuration to get them registered in BPS.

<bps xmlns="http://wso2.org/bps/config">
...
<extensionBundles>
<runtimes>
<runtime>org.wso2.bps.samples.extension</runtime>
</runtimes>
</extensionBundles>
...
</bps>

Now, restart WSO2 BPS sever, and you are ready to use the new extension in your BPEL.

The process is almost the same for Apache ODE. But there is a separate configuration file to register the extension. Please refer ODE extensions documentation for more details.

Using the Extension activity in your BPEL

The extension must be declared before, it is used.

<bpel:process...>

<bpel:extensions>
<bpel:extension namespace="#extension-namespace#" 
                        mustUnderstand="yes|no"/>
</bpel:extensions>

...
</bpel:process>

If the mustUnderstand attribute is set to yes, then the extension should be registered in BPS server in order to deploy the BPEL process. Otherwise, it will throws an error at the compilation stage of the process. If the mustUnderstand attribute is set to no, then the BPEL process will be deployed without checking whether there is an extension registered in the server.

Using the activity. According to the sample anyElementQName should be equal to b4ptest

<extensionActivity>
<anyElementQName standard-attributes>
standard-elements
</anyElementQName>
</extensionActivity>

You can find a sample BPEL process at TestExtensionActivity.zip

References:

[1] - extension

[2] - B4PExtensionOperation.java

[3] - B4PExtensionBundle.java

Building Apache ODE

I found it little bit hard to build Apache ODE for the first time. I followed the steps in the Building ODE guide as it is. But I was not able to build the ODE source. The appeared error was

Permission denied - Permission denied - /tmp/axis2-adb-1.4.1.jar.16179.53314 or /home/.../.m2/repository/org/apache/axis2/axis2-adb/1.4.1/axis2-adb-1.4.1.jar
Buildr aborted!
Failed to download org.apache.axis2:axis2-adb:jar:1.4.1, tried the following repositories:
http://pxe.intalio.org/public/maven2/
http://people.apache.org/repo/m2-incubating-repository/
http://repo1.maven.org/maven2/
http://people.apache.org/repo/m2-snapshot-repository/
http://download.java.net/maven/2/
http://ws.zones.apache.org/repository2/

(Note well, this error only appears, if you build the ODE for the first time or build it with a cleaned repository.)

Therefore, I tried my best to grant the permission to the relevant directories, but, it did not help. I tried to build it as a super user, then it worked. But, it will not help because all the dependencies are copied to the root's .m2 repository.

Actually there was not a single clue to find the fault. After trying out several tests, I was able to figure out that the root cause is the version of the Apache Buildr. Let me explain in detail, how I installed Buildr.

Installing Apache Buildr in jRuby
First of all I downloaded the jRuby 1.2.0. After following the steps in the Guide, I use the following command to install Apache Buildr in jRuby.

jruby -S gem install buildr

The above command installed the Buildr version 1.3.4 which caused me immense trouble. To solve the problem, I uninstalled the Buildr version 1.3.4 using the command:

jruby -S gem uninstall buildr -v 1.3.4

Then re-installed the older version 1.3.2 again, which relieved me a lot. I still could not figure out the exact wrong with the Buildr version 1.3.4, even though, I posted about the problem in the Buildr dev mailing list. Finally I made my mind by assuming it was a bug in Buildr version 1.3.4. This is a serious because the Buildr version 1.3.4 is not backword compatible :(

There is another important fact about installing Buildr in jRuby instead of Ruby. Quoting Apache ODE Building Guide,

Note that for now, even though ODE can run on JDK 1.6.x, building ODE only works with JDK 1.5.x. So before building, make sure you JAVA_HOME points to a JDK 1.5.x installation

The above statement valid only when using Buildr which installed in Ruby. If You installed the Buildr in jRuby, JDK 1.6.x can be used to build ODE.

Happy ODEing...