Run-Time Extension Developer Guide

Developer Guide - org.eclipse.bpel.runtimes

This guide is intended for developers who wish to learn how to integrate a BPEL enactment environment into the Eclipse BPEL Designer using org.eclipse.bpel.runtimes.

If you are a computational scientist interested in using BPEL Designer to model your workflows, go here instead.

This guide gives a quick overview of how users can use the ActiveBPEL server integration in ActiveBPEL, provides an overview of the steps required to integrate any other third-party BPEL runtime and provides downloads of source code and other components.


We suggest you use version 1.5.1 of WTP instead of the official prerequisite (1.5M6) as 1.5.1 resolves a bug affecting starting a server from within BPEL Designer.

The relevant source code is contained in two plugins: org.eclipse.bpel.runtimes (which you can get from Eclipse CVS) and

If you want to try out how the integration of ActiveBPEL works from a user's perspective you also need to install the following components.

Once Eclipse and its prerequisites have been installed, unzip the plug-ins source code and import the plug-ins as projects into your workspace. Select a class (e.g., RuntimesPlugin) and select Run As. Configure it as an Eclipse application and make sure you select clearing the config area of the runtime workbench.

Quick User Guide

If you want to see how the runtime framework works from a user's perspective, read or give the following steps a try.

  • Create a New BPEL Project

File->New->Project. Don't forget to select the BPEL 2.0 Facet before exiting the wizard.

Similarly create a new BPEL process.

  • Set up ActiveBPEL Server and Runtime


In the Servers view, right-click and select New->Server.

To create a new server runtime, select ActiveBPEL 2.0 runtime, click Next and select a JRE and the Tomcat home directory (currently only works with Tomcat-5.0.25).

Next, select the ActiveEndpoints->ActiveBPEL 2.1 Server and click Next. Specify the host (e.g., localhost) and port number (i.e. the port number of Tomcat on which ActiveBPEL is installed). Click Next and you will be presented with the "Add/Remove Projects..." wizard. The "Add/Remove Projects..." wizard should display a list of all BPEL processes found in the workspace. Due to an unresolved bug, it may be necessary to restart your Eclipse workbench in order to allow the list to update itself. To get to this wizard later, simply right-click on the ActiveBPEL server in the Servers view and select "Add and Remove Projects...".

  • Start ActiveBPEL Server

To start and stop the server, right-click the server in the Servers view and select "Start" ("Stop"). The console view will be automatically opened displaying the current server log. When a message “ActiveBPEL In-Memory Configuration Started” appears at the end of the log, it means ActiveBPEL has completed starting up.

  • Deploy BPEL Processes

All BPEL processes that have been added to the server instance via the "Add/Remove Projects..." wizard should appear in the Servers view (expand the ActiveBPEL server entry).

To actually deploy the processes, right-click on the ActiveBPEL server and select "Publish" from the context menu. BPEL Designer will now generate a deployment archive in the form of a bpr file. Once the progress window has disappeared without any warning messages, select the corresponding projects in the workspace and press F5 to refresh them. You should now find files of the form <process_name>.bpr. To actually deploy to the server it is currently still necessary to manually copy these files from a project into the bpr/ folder of you ActiveBPEL installation. You can then view further deployment information via the ActiveBPEL management console [automated transfer and in-editor viewing of deployment messages will be added in the near future].

Integrating Your BPEL Engine

In order to integrate your BPEL engine into BPEL Designer, just create a new plug-in for your runtime and let it define the following items.

  • Defining Your Server Definition

We need to supply a server definition to WTP's generic server framework in the form of a .serverdef file. This file contains information such as the name of the server, properties for the user to configure during setup, how to start and stop the server and libraries required on the classpath (e.g., Bootstrap.jar).

The ActiveBPEL engine runs as a web application inside Tomcat and so we can simply modify exisiting server definitions for Tomcat.

The activebpel2.serverdef file (in abr plug-in) serves as an example. Here we will just briefly discuss the one common element needed in order to integrate your server with the runtime framework. For information on how to complete the remainder of your serverdef file, please consult this article on the WTP documentation pages.

You need to specify the kinds of modules that can be published to it as well as the class reponsible for publishing:


2 <type>bpel.module</type>

3 <publishDir>${abHome}\bpr</publishDir>

4 <publisherReference></publisherReference>



In line 2 we specify that our server accepts modules of type bpel.module. Line 3 denotes the directory used by our server to deploy modules. In line 4 we specify the GenericPublisher we wish to use for actually deploying modules to our server. This id will be defined and linked to a specific class in your runtime's plugin.xml (will look at later).

  • Defining Your Plugin.xml

A quick walkthrough of what you need to define in your plugin.xml. We use plugin.xml in as our example and you can consult the WTP documentation pages for more info.

Define org.eclipse.wst.server.core.runtimeTypes supplying your runtime with an id and some descriptive strings. We want to use GenericServerRuntime as the class and make sure you replicate the moduleType element as it is in the example plugin.xml.

Next, define org.eclipse.wst.server.core.serverTypes to specify the actual server linked to the runtime type. The attributes should be self-explanatory.

Define org.eclipse.wst.server.ui.wizardFragments to plug into the runtime and server setup wizards of the Generic Server Framework. GenericRuntime/ServerWizardFragment will take care of displaying the properties from your serverdef.

We use org.eclipse.wst.server.ui.serverImages to specify some icons for server and runtime.

Next, org.eclipse.jst.server.core.runtimeClasspathProviders to specify a classpath provider for the runtime (to provide any jar files engine might need).

org.eclipse.jst.server.generic.core.serverdefinition allows us to state where the serverdef file is to be found.

In org.eclipse.jst.server.generic.core.genericpublisher we specify the id of the publisher (the one we use in serverdef in the publisherReference element) and the class actually responsible for publishing. In the example, ActiveBPELPublisher sub-classes GenericBPELPublisher.

Next, org.eclipse.wst.common.project.facet.core.runtimes. Make sure that you associate the runtime-component you define here to version 2.0 of bpel.facet.core as shown in the example plugin.xml. This associates your runtime with projects that have the BPEL 2.0 facet installed.

The final three extension points we need to use are org.eclipse.wst.common.project.facet.ui.images, org.eclipse.wst.common.project.facet.core.runtimes, org.eclipse.jst.server.core.runtimeFacetMappings, which should be self-explanatory from consulting the example plugin.xml.

  • Implementing GenericBPELPublisher

The last step is to implement GenericBPELPublisher. The idea behind GenericBPELPublisher is to i) denote a particular type of publisher and ii) over time evolve it into a nice abstract base class that provides value to runtime providers (you). For now, it just provides subclasses with access to the default or user-configured host name and port number.

The example provided in is called ActiveBPELPublisher. This class is responsible for driving the deployment process by generating deployment descriptors and archives, etc. Your implementation should implement the publish() and unpublish() methods, but other than that you are free to implement the behaviour needed by your engine (each BPEL engine may have its own requirements on how to deploy a BPEL process). However, there is one noteworthy item in the implementation of the publish method; to get hold of the modules a user has selected for deployment, we cannot rely on the publish's arguments, but rather resort to the following as a fix:


1IModule[] modules = super.getModule();

2 resources = new IModuleArtifact[modules.length];

3for (int i=0; i<modules.length; i++) {

4 IModule module = modules[i];

5 String moduleId = module.getId();

6 String bpelFileRelativePathString = moduleId.split(">>")[1];

7 IPath path = new Path(bpelFileRelativePathString);

8 IFile bpelFile = module.getProject().getFile(path);

9 BPELModuleArtifact moduleArtifact = new BPELModuleArtifact(module, bpelFile);

10 resources[i] = moduleArtifact;



In line 1 we get all BPEL modules that have been added to the server. From that we generate BPELModuleArtifacts in the for-loop by first getting the unique id of each module (line 5) and then extracting the project relative path of the corresponding BPEL file (line 6). This provides us with the data required to construct a bunch of BPELModuleArtifacts which can then be further processed (i.e. deploy) in the publish method.

It is also the responsibility of your publisher code to actually copy any required files (e.g., deployment archive) onto the server using whatever means are employed by your engine. The example code, in its current form, simply stores a copy of the generated archive in its corresponding BPEL project. In addition, you may want to make any engine-specific deployment messages available to a user (let me know if that's the case... we should display such messages in the Problems view).

This concludes the overview on how to integrate your BPEL engine into BPEL Designer. Please don't be shy with any feedback you may have that could help make this guide more useful.

This page was last modified on 18 Oct 2013.