Basic tutorial for the bpel-g engine


The most well-known open source BPEL engine is Apache ODE. Nevertheless, there are several other engines available that also deserve some attention. One of them I recently started using is bpel-g. This engine is based on the final release of the former ActiveBPEL engine by Active Endpoints. This engine was quite well-known at its time (and used in quite some scientific papers), but the direct support by Active Endpoints for the open source version seems to have discontinued (although I could not find an announcement confirming this). I assume the engine has made it into their BPM suite, but again, this is just guesswork. Today, the engine is still under active development, but with a new name, bpel-g. One of its recent new features is integration with Apache Camel. Bpel-g still falls somewhat short on tutorials which is why I am writing this post.

The engine is quite light-weight and you can run it on tomcat. Here, I provide a simple example for installing the engine and deploying a simple BPEL process, an echo process that replies an int value. I assume that you are familiar with the basics of BPEL and WSDL.

INSTALLATION

To install the engine on tomcat, you need to get two things:

  1. The engine itself, available here
  2. Tomcat, for example available here (Any Tomcat 7 or 8 should do)

The bpel-g.war goes in tomcats webapps directory, located at $TOMCAT_HOME/webapps and that’s it. You can start tomcat (the startup script is located in $TOMCAT_HOME/bin) and the engine gets installed and is ready for use. It creates a directory named bpr in $TOMCAT_HOME where the deployment artifacts ought to go, but first you need to build such an artifact.

BUILDING DEPLOYMENT ARCHIVE AND DEPLOYING A PROCESS
Basically, you need a BPEL process, a WSDL definition serving as interface for the process, and a deployment descriptor. All the files described here are available in a github repository. If you package the files in the repository as a zip archive, you can directly deploy this archive on bpel-g. Here is the interface for the echo process defined in the WSDL file (named EchoInterface.wsdl):

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:plink="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
             xmlns:vprop="http://docs.oasis-open.org/wsbpel/2.0/varprop"
             xmlns:tns="http://dsg.wiai.uniba.de/wsdl/echointerface"
             name="EchoInterface"
             targetNamespace="http://dsg.wiai.uniba.de/wsdl/echointerface">

    <plink:partnerLinkType name="EchoInterfacePartnerLinkType">
        <plink:role name="echoInterfaceRole" portType="tns:EchoInterfacePortType"/>
    </plink:partnerLinkType>

    <types>
        <xsd:schema targetNamespace="http://dsg.wiai.uniba.de/wsdl/echointerface">
            <xsd:element name="echoRequest" type="xsd:int"/>
            <xsd:element name="echoResponse" type="xsd:int"/>
        </xsd:schema>
    </types>

    <message name="echoRequestMessage">
        <part name="inputPart" element="tns:echoRequest"/>
    </message>
    <message name="echoResponseMessage">
        <part name="outputPart" element="tns:echoResponse"/>
    </message>

    <portType name="EchoInterfacePortType">
        <operation name="echo">
            <input name="echoInput" message="tns:echoRequestMessage"/>
            <output name="echoOutput" message="tns:echoResponseMessage"/>
        </operation>
    </portType>

    <binding name="EchoInterfacePortTypeBinding" type="tns:EchoInterfacePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

        <operation name="echo">
            <soap:operation/>
            <input name="echoInput">
                <soap:body use="literal"/>
            </input>
            <output name="echoOutput">
                <soap:body use="literal"/>
            </output>
        </operation>
    </binding>

</definitions>

Its structure is pretty simple: A partnerLinkType which we need for the BPEL process. Further, type and message definitions for two messages that consist of a single message part, being an int value. A portType definition with a single synchronous operation and a simple document/literal style binding for this operation. You might notice that there is no service and endpoint address definition in this WSDL. From what I have experienced so far, bpel-g is a little bit special here. You can put service definitions in the WSDL and the package will deploy, but the definitions are ignored. For bpel-g, endpoint information needs to go into the deployment descriptor and more on that later.

Now, here comes a BPEL process that provides an implementation for this interface (named Echo.bpel):

<?xml version="1.0" encoding="UTF-8"?>
<process
    name="Echo"
    targetNamespace="http://dsg.wiai.uniba.de/bpel/echo"
    xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
    xmlns:ec="http://dsg.wiai.uniba.de/wsdl/echointerface">
    <import namespace="http://dsg.wiai.uniba.de/wsdl/echointerface" location="EchoInterface.wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>
    <partnerLinks>
        <partnerLink name="MyRoleLink" partnerLinkType="ec:EchoInterfacePartnerLinkType" myRole="echoInterfaceRole"/>
    </partnerLinks>
    <variables>
        <variable name="ReplyData" messageType="ec:echoResponseMessage"/>
        <variable name="InitData" messageType="ec:echoRequestMessage"/>
    </variables>
    <sequence>
        <receive name="InitialReceive" createInstance="yes" partnerLink="MyRoleLink" operation="echo" portType="ec:EchoInterfacePortType" variable="InitData"/>
        <assign name="AssignReplyData">
            <copy>
                <from variable="InitData" part="inputPart"/>
                <to variable="ReplyData" part="outputPart"/>
            </copy>
        </assign>
        <reply name="ReplyToInitialReceive" partnerLink="MyRoleLink" operation="echo" portType="ec:EchoInterfacePortType" variable="ReplyData"/>
    </sequence>
</process>

The process imports the WSDL file and defines a partnerLink set to myRole referencing the partnerLinkType from the WSDL file. Furthermore, it defines two variables of the messageTypes from in the WSDL and starts the process with a receive activity that references the appropriate variable and the operation defined in the WSDL porttype. An assign activity copies the input value to the second variable and this variable is used in the final reply activity that replies to the synchronous invocation and ends the process.

There is only one more file required, the deployment descriptor (named deploy.xml):

<?xml version="1.0" encoding="UTF-8"?>
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
        xmlns:bpel="http://docs.oasis-open.org/wsbpel/2.0/process/executable">
   <process xmlns:tns="http://dsg.wiai.uniba.de/bpel/echo"
            name="tns:Echo">
      <provide xmlns:tns="http://dsg.wiai.uniba.de/wsdl/echointerface"
               partnerLink="MyRoleLink">
         <service name="tns:EchoInterfaceService" port="EchoInterfacePort"/>
      </provide>
   </process>
</deploy>

The structure of this descriptor is actually identical to the structure of the deployment descriptors used by Apache ODE. From version 5.2 on, bpel-g supports the ODE structure. Basically, for every process to be deployed, the services provided and invoked need to be listed here. As said before: If you want to set endpoint addresses, this information needs to go here, in the form of a WS-Addressing EndpointReference. If you do not set it explicitly, a default address is set for your service, in my case this is http://localhost:9080/bpel-g/services/EchoInterfaceService. As a side note: The BPEL process at hand does not invoke a service, but if so, an EndpointReference for that service needs to be put into the deployment descriptor as well.

Now, all you need to do is to build a zip archive of these files (named echo.zip) and put it into bpel-g’s working directory, located at $TOMCAT_HOME/bpr for hot deployment. Eventually (pretty quickly, from what I have seen), the bpel-g deployment scanner will find the new archive, unpack it into $TOMCAT_HOME/bpr/work and thus deploy the process. You can fire up your browser at localhost:8080/bpel-g/ for the bpel-g management pages, where you can see the process deployed and ready for invocation.

INVOKING THE DEPLOYED PROCESS
You can now send SOAP messages to the address http://localhost:8080/bpel-g/services/EchoInterfaceService using the tool of your choice. Mine is soapUI. A sample SOAP request looks like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ech="http://dsg.wiai.uniba.de/wsdl/echointerface">
   <soapenv:Header/>
   <soapenv:Body>
      <ech:echoRequest>1</ech:echoRequest>
   </soapenv:Body>
</soapenv:Envelope>

And the response I got is this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:echoResponse xmlns:aetgt="http://dsg.wiai.uniba.de/wsdl/echointerface" xmlns:ns1="http://dsg.wiai.uniba.de/wsdl/echointerface">1</ns1:echoResponse>
   </soapenv:Body>
</soapenv:Envelope>

SUMMARY
The engine is pretty simple to install and use, especially if you compare it to certain commercial products. I suggest you give it a try!

UPDATE 05.02.2014

– Fixed broken link to Tomcat download
– Added link to github repository
– Removed installtion of H2 which is already included in bpel-g

Advertisements

11 thoughts on “Basic tutorial for the bpel-g engine

      1. Yes it looks promising, but I read on its code.google page that it was build uppon axis stack and the newest version on cxf. Does it mean that bpel proceses running on this engine could invoke only web services based on this stack? I am asking only because I tried it with generated services with Metro, and its not working. Thanks in advance for your reply

      2. Theoretically the WS-stack shouldn’t matter. Web services are designed for interoperable communication. Practically, there are problems here and there. I have used bpel-g to invoke web services running on the jax-ws reference implementation and this was working fine. I would expected it to work with metro, too.

  1. Thanks for the nice tutorial.
    However, I followed your steps (copied the code from your examples) using the current bpel-g 5.3 snapshot, and the process is not even deployed. What did I miss?

    1. You’re welcome.

      I just tested the installation with the bpel-g 5.3 snapshot (btw., the 5.3 release version from December 2012 works as well), a 64-bit Windows version of Tomcat 8 (just to be precise. Basically any Tomcat 7/8 version should do), and the h2 database linked above. I also added the code to a github repo (https://github.com/lenhard/bpel-g-tutorial) from which you can download the whole thing. Everything worked fine. Do you get an error message from Tomcat? If yes, then what is the error? If no, maybe you put the engine or the process archive in a wrong directory?

      Regards, Jörg

      1. Thanks for your help. I used the zip file from your github repo and put it into the bpr folder of my tomcat installation. A new directory appears under bpr/work, but still: bpel-g says 0 processes are deployed. I use the bpel-g 5.3 snapshot, 64Bit OS X 10.8.5 and Apache Tomcat/8.0.1

        btw: your link to h2-1.2.122.jar is broken, and the current bpel-g version already includes a h1-1.2.122.jar

  2. In addition, I checked the log files: logs/catalina.out contains
    “05-Feb-2014 15:35:01.444 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 11778 ms
    2014-02-05 15:35:05,259 INFO [net.sf.ehcache.CacheManager@26b68b12]: New update(s) found: 2.4.7 [http://www.terracotta.org/confluence/display/release/Release+Notes+Ehcache+Core+2.4]. Please check http://ehcache.org for the latest version.
    2014-02-05 15:36:10,509 DEBUG [AeDeploymentScanner-Thread]: Deploying processes and wsdl in ae_temp_bpel-g-tutorial-master_zip
    2014-02-05 15:36:11,008 INFO [AeDeploymentScanner-Thread]: [EchoInterface.wsdl] Added resource mapped to location hint: project:/ae_temp_bpel-g-tutorial-master_zip/bpel-g-tutorial-master/EchoInterface.wsdl
    2014-02-05 15:42:21,091 INFO [AeDeploymentScanner-Thread]: Removing ActiveBPEL deployment: file:/Users/richardmueller/Downloads/apache-tomcat-8.0.1/bpr/bpel-g-tutorial-master.zip”

    It states that your zip file was deployed. Still bpel-g says no process was deployed. Then, after six minutes, I deleted to zip from the bpr directory.

    I found no other log traces related to deployment.

    1. Hi,
      it seems that this was my fault. If you just download the repository as a zip, Github puts all files in an additional folder and zips that folder. If you try to deploy this, the behavior you experience is the result. If you instead just package the files in a zip yourself directly at root level, deployment should work. At least it does for me…
      Hope this helps

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s