Setting Up Tools to Build Applications Using jBPM: Part 1

Background about the jBPM project

In this section, we will talk about where the jBPM framework is located inside the JBoss projects. As we know, JBoss jBPM was created and maintained for JBoss. JBoss is in charge of developing middleware "enterprise" software in Java. It is middleware because it is a type of software to make or run software, and "enterprise", as it is focused on big scenarios. This enterprise does not necessarily mean Java EE. It is also interesting to know that JBoss was bought from a company called Red Hat (famous for the Linux distribution with the same name, and also in charge of the Fedora community distribution).

In order to get the right first impression about the framework, you will need to know a little about other products that JBoss has developed and where this framework is located and focused inside the company projects. At this moment, the only entry point that we have is the JBoss community page, This page contains the information about all the middleware projects that JBoss is developing (all open source). If we click on the Projects link in the top menu, we are going to be redirected to a page that shows us the following image:

jBPM Developer Guide

This image shows us one important major central block for the JBoss Application Server, which contains a lot of projects intended to run inside this application server. The most representative modules are:

  • JBoss Web: The web container based on Tomcat Web Server
  • JBoss EJB3: EJB3 container that is standard EJB3 compliance for Java EE 5
  • Hibernate: The world-renowned Object Relational Mapping (ORM) framework
  • Seam: The new web framework to build rich Internet applications
  • JBoss Messaging: The default JMS provider that enables high performance, scalable, clustered messaging for Java

On top of that, we can see two frameworks for Web Interface design (RichFaces/Ajax4jsf and Gravel) based on the components, which can be used in any web application that you code.

And then, on top of it all, we can see three important blocks—Portal, Integration, and Telecom. As you can imagine, we are focused on the Integration block that contains three projects inside it.

As you can see, this Integration block is also outside the JBoss Application Server boundaries. Therefore, we might suppose that these three products will run without any dependency from JBoss or any other application server.

Now we are going to talk about these three frameworks, which have different focuses inside the integration field.

JBoss Drools

Drools is, of late, focused on business knowledge, and because it was born as an inference engine, it will be in charge of using all that business knowledge in order to take business actions based on this knowledge for a specific situation. You can find out more information about this framework (now redefined as Business Logic integration Platform) at


It is a product focused on supplying an Enterprise Service Bus (ESB), which allows us to use different connectors to communicate with heterogeneous systems that were created in different languages. These use different protocols for communication. You can find out more information about this project at

JBoss jBPM

jBPM has a process-centric philosophy. This involves all the APIs and tools that are related to the processes and how to manage them. The framework perspective is always centered on the business process that we describe. Also, the services available inside the framework are only for manipulating the processes. All the other things that we want or need for integration with our processes will be delegated to third-party frameworks or tools.

Now, if we enter into the official page of jBPM (, we are going to see all the official information and updates about the framework. It is important to notice the home page, which shows us the following image:

jBPM Developer Guide

This is the first image that developers see when they get interested in jBPM. This image shows us the component distribution inside the jBPM framework project. Understanding these building blocks (components) will help us to understand the code of the framework and each part's functionality. Most of the time, this image is not clearly understood, so let's analyze it!

Supported languages

One of the important things that the image shows is the multi-language support for modeling processes in different scenarios. We can see that three languages are currently supported/proposed by the framework with the possibility to plug in new languages that we need, in order to represent our business processes with extra technology requirements.

These supported languages are selected according to our business scenario and the technology that this scenario requires.

The most general and commonly used language is jBPM Process Definition Language (jPDL). This language can be used in  situations where we are defining the project architecture and the technology that the project will use. In most of the cases, jPDL will be the correct choice, because it brings the flexibility to model any kind of situation, the extensibility to expand our process language with new words to add extra functionality to the base implementation, and no technology pluggability limitation, thereby allowing us to interact with any kind of external services and systems. That is why jPDL can be used in almost all situations. If you don't have any technology restriction in your requirements, this language is recommended.

jBPM also implements the Business Process Execution Language (BPEL), which is broadly used to orchestrate Web Services classes between different systems.

To support business scenarios where all the interactions are between web services, I recommend that you make use of this language, only if you are restricted to using a standard like BPEL, in order to model your business process.

PageFlow is the last one shown in the image. This language will be used when you use the JBoss Seam framework and want to describe how your web pages are synchronized to fulfill some requirements. These kind of flows are commonly used to describe navigation flow possibilities that a user will have in a website.

Web applications will benefit enormously from this, because the flow of the web application will be decoupled from the web application code, letting us introduce changes without modifying the web pages themselves.

At last, the language pluggability feature is represented with the ellipse (...). This will be required in situations wherein the available languages are not enough to represent our business scenarios. This could happen when a new standard like BPEL or  BPMN arises, or if our company has its own language to represent business processes. In these kind of situations, we will need to implement our custom language on top of the process' virtual machine. This is not an easy task and it is important for you to know that it is not a trivial thing to implement an entire language. So, here we will be focused on learning jPDL in depth, to understand all of its features and how to extend it in order to fulfill our requirements. Remember that jPDL is a generic language that allows us to express almost every situation. In other words, the only situation where jPDL doesn't fit is where the process definition syntax doesn't allow us to represent our business process or where the syntax needs to follow a standard format like BPMN or BPEL.

Also, it is important to notice that all these languages are separate from the Process Virtual Machine (PVM), the block on the bottom-left of the image, which will execute our defined process. PVM is like the core of the framework and understands all the languages that are defined. This virtual machine will know how to execute them and how to behave for each activity in different business scenarios. When we begin to understand the jPDL language in depth, we will see how PVM behaves for each activity described in our process definitions.

Other modules

Besides the PVM and all the languages, we can also see some other modules that implement extra functionality, which will help us with different requirements. The following list contains a brief description of each module:

  • Graphical Process Designer (GPD) module: It is the graphical process designer module implemented as an Eclipse plugin.
  • Identity module: This module is a proof of concept, out-of-the-box working module used to integrate business roles for our processes. This module is focused on letting us represent people/users inside the process definition and execution. This module shows us a simple structure for users and groups that can be used inside our processes. For real scenarios, this module will help us to understand how we will map our users' structures with the jBPM framework.
  • Task ManaGeMenT (TaskMGMT) module: This module's functionality involves dealing with all the integration that the people/employees/business roles have with the processes. This module will help us to manage all the necessary data to create application clients, which the business roles will use in their everyday work.
  • Enterprise module: This module brings us extra functionality for enterprise environments.

Now that we know how the components are distributed inside the framework, we can jump to the jPDL section of jBPM's official web page. Here we will find the third image that all the developers will see when they get started with jBPM.

jBPM Developer Guide

Let's analyze this image to understand why and how the framework can be used in different platforms. This image tries to give us an example of how jBPM could be deployed on a web server or an application server. Please, keep in mind that this is not the only way that jBPM could be deployed on, or embedded in, an application, because jBPM can also be used in a standalone application. In addition, this image shows us some of the BPM stages that are implemented. For example, we can see how the designed processes will be formalized in the jPDL XML syntax in Graphical Process Designer (GPD)— here called the Eclipse jPDL Editor. On the other side of the image, we can see the execution stage implemented inside a container that could be an Enterprise Container (such as JBoss Application Server) or just a web server (such as Tomcat or Jetty). This distinction is made with the extensions of the deployed files (war, for Web Archives, and ear, for Enterprise Archives). In this container, it is important to note the jpdl-jbpm.jar archive that contains the PVM and the language definition, which lets us understand the process defined in jPDL. Also, we have the jbpm-identity.jar as a result of the Identity Module that we have seen in the other image. Besides, we have the hibernate.jar dependency. This fact is very important to note, because our processes will be persisted with Hibernate and we need to know how to adapt this to our needs.

The last thing that we need to see is the Firefox/Internet Explorer logo on top of the image, which tries to show us how our clients (users), all the people who interact and make activities in our processes will talk (communicate) with the framework. Once again, HTTP interaction is not the only way to interact with the processes, we can implement any kind of interactions (such as JMS for enterprise messaging, Web Services to communicate with heterogeneous systems, mails for some kind of flexibility, SMS, and so on).

Here we get a first impression about the framework, now we are ready to go ahead and install all the tools that we need, in order to start building applications.

Tools and software

For common tools such as Java Development Kit, IDE installation, database installation, and so on, only the key points will be discussed. In jBPM tooling, a detailed explanation will follow the download and installation process. We will be going into the structure detail and specification in depth; about how and why we are doing this installation.

If you are an experienced developer, you can skip this section and go directly to the jBPM installation section. In order to go to the jBPM installation section straightaway, you will need to have the following software installed correctly:

  • Java Development Kit 1.5 or higher (This is the first thing that Java developers learn. If you don't know how to install it, please take a look at the following link:
  • Maven 2.0.9 or higher
  • A Hibernate supported database, here we will use MySQL
  • You will need to have downloaded the Java Connector for your selected database
  • JBoss 5.0.1.GA installed (If you are thinking about creating Enterprise Applications, you will need JBoss AS installed. If you only want to create web applications with Tomcat or Jetty installed, this will be fine.)
  • Eclipse IDE 3.4 Ganymede (Eclipse IDE 3.4 Ganymede is the suggested version. You can try it with other versions, but this is the one tested in the article.)
  • An SVN client, here we will use Tortoise SVN (Available for Windows only, you can also use a subversion plugin for Eclipse or for your favorite IDE.)

If you have all this software up and running, you can jump to the next section. If not, here we will see a brief introduction of each one of them with some reasons that explain why we need each of these tools.

Maven—why do I need it?

Maven is an Apache project that helps us to build, maintain, and manage our Java Application projects. One of the main ideas behind Maven is to solve all the dependency problems between our applications and all the framework libraries that we use. If you read the What is Maven? page (, you will find the key point behind this project.

The important things that we will use here and in your diary work will be:

  • A standard structure for all your projects
  • Centralized project and dependencies description

Standard structure for all your projects

Maven proposes a set of standard structures to build our Java projects. The project descriptor that we need to write/create depends on the Java project type that we want to build. The main idea behind it is to minimize the configuration files to build our applications. A standard is proposed to build each type of application.

You can see all the suggested standard structure on the official Maven page:

Centralized project and dependencies description

When we are using Maven, our way of building applications and managing the dependencies needed by these applications changes a lot. In Maven, the concept of Project Object Model (POM) is introduced. This POM will define our project structure, dependencies, and outcome(s) in XML syntax. This means that we will have just one file where we will define the type of project we are building, the first order dependencies that the project will have, and the kind of outcome(s) that we are expecting after we build our project.

Take a look at the following pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="" xmlns:xsi="http://" xsi:schemaLocation="http://maven.">

We are basically defining all the mentioned characteristics of our project. All this information is deduced from the packaging attribute, which in this case is:


The standard structure of directories will be used in order to know where the source code is located and where the compiled outcome will be placed.

Maven installation

Getting maven installed is a very simple task. You should download the Maven binaries from the official page( This will be a .zip file, or a .tar.gz file, which you will only need to uncompress in the programs directory. You will also add the bin directory to the system Path variable. With that, you will be able to call the mvn command from the console.

To test whether Maven is working properly, you can open the Windows console and type mvn. You should get something like this:

jBPM Developer Guide

This output shows us that Maven is correctly installed. However, as it is installed in C:Documents and Settingssalaboy21 (the installation directory) where there is no project descriptor, the build failed.

I strongly recommend that you read and understand the Getting Started section in the official Maven documentation at

Installing MySQL

In most situations, we will need to store the current state of our processes and all the information that is being handled inside it. For these situations, we will need some persistence solution. The most common one is a relational database. In this case, I chose MySQL, as it's free and easy to install in most of the operating systems. Feel free to try and test jBPM with any of the other Hibernate-supported databases.

Installing MySQL is very easy, you just need to download the binaries provided on the official page (, then run it and follow the instructions that appear in the wizard window. The only things that I chose, but are defaults, are the type of installation Developer Machine and MySQL as a Windows service.

This will help us to always have a running database for our process and it will not be necessary to start it or stop it at the beginning or the end of our sessions.

Downloading MySQL JConnector

In order to connect every Java application to a relational database, we will need a particular connector for each database. This connector, in this case, will be used by Hibernate to create a JDBC connection to the database when it needs to store our processes' data.

Almost all vendors provide this connector in the official page. Therefore, for MySQL, you can look for it on the MySQL official page.

You will need to download it and then put it in your application class path, probably right next to Hibernate.

Remember that this MySQL JConnector (JConnector is the name of the MySQL JDBC Driver) is only a Java library that contains classes— it knows how to create and handle connections between our Java programs and the MySQL database server. For this reason, like any other dependency, you can use JConnector with Maven, as it's only a JAR file. Depending on your database and its version, you will need to add the correct dependency to your project descriptor (in the pom.xml file).

In this case, because I'm using MySQL 5, I will need to add the following dependency to my project in the dependency section:


Eclipse IDE

In these scenarios where we will handle a lot of different types of information—for example Java code, XML files, business processes, configuration files, and so on—it's very handy to have a unique tool that handles all of these kind of files and lets us build/compile, run, and debug all our applications. For this, we have the Eclipse IDE that provides us a lot of tools for our development work. Of course, we can install other IDEs such as Netbeans or IntelliJ, but in this case, the jBPM plugins are only for Eclipse. This could be a very interesting contribution if you want write a plugin for the Netbeans IDE (another open source IDE) and the community will be very happy. This doesn't mean that you can't use any other IDE, but probably, you will need to write your processes in XML format from scratch.

Installing Eclipse IDE is also very easy, you just need to download the IDE binary from the official page ( Then uncompress the zip file inside the programs directory and when it's done, you will find the eclipse.exe executable that you could run inside the bin directory. The only thing that you need here is to have your JAVA_HOME variable set and the Java JDK binaries inside your PATH variable.

Install Maven support for Eclipse

This is an optional plugin that can make our life easier. This plugin will allow us to invoke and use Maven inside the IDE. This means that now our IDE will know about Maven and give us different options to handle and manage our Maven projects.

This plugin, like any other plugin for Eclipse, needs to be installed with the Software Update Manager. You will find instructions about how to do that in each plugin's official page ( In this case, the quick way will be to add the update site (you need to go to Help | Software Update inside Eclipse IDE). In the Available Software tab, click on the Add Site button and enter Then choose the site and wait for Eclipse to get all the information about this site and choose the plugin for the list. This will install all the components in the list and all this functionality will be turned on by the IDE.

SVN client

It's very important for you and your projects to have a right source version system. In this case, we will not version our projects, but we will download the source code of the framework for the official JBoss SVN repositories. For this task, you could add an SVN plugin or an external tool to do the same with the Eclipse IDE.

I chose Tortoise SVN, which is a much-used SVN client and will let us manage all our versioned projects by integrating with the Windows environment.

For this, you only need to download the binaries from the official Tortoise Page, run it, and then restart your machine. This is because some major changes will be needed for integrating the SVN client with the Windows explorer.

Starting with jBPM

At this point, we are ready to download and install the jBPM framework into our machine to start building up applications, which will use the framework.

jBPM is a framework like Hibernate. Why do I need to install it? Hibernate doesn't need an installation. "Install jBPM" doesn't sound good at all. Like every other framework, jBPM is only a JAR file that we need to include in our application classpath in order to use it.

So, the idea in this section is to find out why we download a jBPM installer from the jBPM official page as well as what things are included in this installer and in which situations we need to install all these tools.

Getting jBPM

Basically, as developers, we have two ways to get the framework up and working. We can download the installer from the official site of jBPM or we can download the source and build it with our hands. None of these two ways are complex, but always getting the source code of our frameworks will help us to debug our applications by looking at how the framework behaves at runtime. We will analyze these two ways in order to show which is the quickest way to have the framework ready for production, and also what we need to do in order to extend the framework functionality.

From binary

Just download the framework binaries from the jBPM official page and install it, you will see that the installer asks you for some other installed software, such as JBoss Application Server and the database which you will use.

This binary file (the installer) contains the framework library archives, a graphical process designer (Eclipse Plugin), and a JBoss profile that contains everything you will need to start up a JBoss Application Server instance and start using jBPM deployed inside it. Also, it contains the framework sources that will help us to have the framework code that we need in order to debug our applications and see our processes in action.

Here we will see the results of this installation and the directory structure that contains jBPM files.

jBPM Developer Guide

As you can see in the image, we will have the directories as described in the following sections:

config directory

This directory will contain XML files with the configuration needed for the database that we choose. We will use the file called hibernate.cfg.mysql.xml. You will need to choose the file for your corresponding installed database. If you open this file, you will find something like this:

jBPM Developer Guide

This file, by default, configures a JDBC connector to use for jBPM persistence. I know that the persistence usage has not been introduced yet, but then when I talk about that, you will know where the configuration is.

In the first section of the file, you will find a tag called <session-factory>. With this information, jBPM can create two types of database connections—JDBC or Datasource connections.

These two types of connection will be used depending on the environment that we use. If we are building an application that will run outside a container, we will need to configure the JDBC connector as shown in the image, where we specify the dialect that Hibernate will use and the driver corresponding to the database we choose. Pay close attention to the com.mysql.jdbc.Driver class, because this class will be inside the JConnector in MySQL. So, it will be necessary that this jar is in the application classpath. The other properties used here are the common ones to set up a connection to a database.

For a DataSource connection, meaning that our application will run inside a container like JBoss (an Enterprise Application container) or any other application server, we will need to uncomment the line that specifies the DataSource connection and comment the lines that specify the JDBC connection. With this DataSource connection, all the access to the database will be handled by a connection pool that will be inside the container that we will use—this is the reason why we only need to specify the name of the DataSource, and then the container will handle all the connection details for us.

database directory

This directory is very useful, because inside it, we will find the schema definition that jBPM will use. The idea is to have the generation script for each database to create each of them. If you open the file called jbpm.jpdl.mysql.sql, you will find all the tables used by jBPM. The important thing to know here is that all these scripts will need to be reviewed by your Database Administrator, because these tables are not optimized for a production environment. What does this mean exactly? This is only a recommendation, because jBPM generates a lot of data, and if you are in a production environment where 1,000 users have access to your defined process, this structure will generate and log a lot of information by default. So, take a look at this file; you could also execute it inside a MySQL database to see the tables that are created.

designer directory

This directory will contain just one ZIP file that has the structure of an Update Site for Eclipse and contains only the plugin that will turn our IDE into a Business Process Designer. If you want to install this plugin in your current Eclipse installation, you only need to go to Help | Software Updates. When the Software Updates and Add-ons window opens, you should switch to the Available Software tab, click on the Add Site… button followed by the Archive button, and locate the ZIP file placed in this directory.

jBPM Developer Guide

Then you should select the newly added feature, jBPM jPDL GPD, and click on the Install... button. This will install all the software needed to start using the jBPM plug-in inside Eclipse, but you will need to restart Eclipse before you can use it.

docs directory

This directory contains all the Javadoc for all the code of the jBPM different modules. It also contains the HTML user guide. This is very important documentation that will also help you to understand the framework.

examples directory

This directory contains a Maven project that includes a lot of tests that show us how to use the jBPM APIs. If you are starting with jBPM, this example project will help you to see the most common ways to use the jBPM APIs.

lib directory

This contains all the jars needed by the framework. You will need to add these jars to every application that use jBPM. These libs will be necessary if we don't use Maven. If you choose to build your applications with Maven, these dependencies will be resolved automatically. These jars will be needed in our application classpath to compile and run our project that is using the jBPM framework.

src directory

This directory contains jar files that include the source code of the framework, which is very useful for debugging our projects. You should notice that all of the code cannot be modified or rebuilt. These libs with source code are only helpful to see what the current executed code is. To build the framework from scratch, you will need to download the code from the official JBoss SVN repositories, which will also contain all the projects' descriptors needed to build the sources. This topic will be described in the following section.

From source code

This section is focused on introducing the "common way of doing things" of the community members. You could take this way of building the source code that is downloaded from an SVN server, as one step towards being a part of the community. Remember that jBPM, as all the projects hosted on the official community page of JBoss, is an open source project. So take advantage of that—as an open source developer, you can get involved with the projects that you use and help the community to improve them. This is not as difficult as you assume it to be.

That is why, you always have the chance to get all the source code from the official JBoss SVN repository. With these sources, you will be able to build the binaries that you can download from the jBPM official page from scratch.

You can take advantage of this when you need to modify some or extend the base code of the framework. This is not recommended for first time users, modifications and extensions will need to be extremely justified.

This is just a quick way to do it. First of all, we need to get the framework sources from the official JBoss SVN repository server. We do that with the SVN client (Tortoise SVN that we have downloaded and installed earlier). We just need to check out the source code from our framework version.

The official JBoss SVN repository can be found at

You can see three directories in this repository: branches, tags, and trunk.

In branches directory, you will find different sub-directories that contain code for testing new functionalities that will be added to future framework releases. Also, branches are used to patch existing versions that are in the maintenance mode.

In tags directory, you will find all the released versions from jBPM, to which you will need to point, in order to perform the framework sources checkout. In this case, you will need to check out the sources located at

These sources were used to build all the binaries of the 3.2.6.SP1 version that is uploaded to the official page.

Finally, in the trunk directory, you will find all the code, which is used by the community members that continuously add and improve the code of the framework.

In order to get the code from the official repository, you only need to do a check-out with your SVN client as shown in the following screenshot:

jBPM Developer Guide

By right-clicking on every directory, you will see the Tortoise SVN options. You just have to click on SVN Checkout. This will pop up a window like the following one:

jBPM Developer Guide

You should set the repository URL to the JBoss Official SVN repository and the Checkout directory to where your working copy will be located. I created a new directory inside software directory called projects. Here we will locate all our projects from now on, because jBPM framework is just another project we will put in there. When you click on OK, the check out of the source code will begin. When the check out command finishes in order to get all the repository code, you will have all the sources of a major Maven project in the directory that you specify.

Now you can build this project by running the following command from the console:

mvn clean install -Dmaven.test.skip

The -Dmaven.test.skip flag is only used here to make the build faster. Supposing that if the code downloaded is a stable release, all the tests in the project will be passed. But, probably, running all the tests for the whole project could take a long time. You can try without this fl ag if you want.

These Maven goals will build the framework by skipping all the tests and then move/install the resulting jars to the local Maven repository. The local Maven repository will contain all the compiled artifacts that you build. This will mean that we will have a local directory in our machine that will contain all the jars that we compile and all the jars needed by our applications (dependencies). The default location of this repository is <UserHome>/.m2/respository/.

jBPM Developer Guide

>> Continue Reading Setting Up Tools to Build Applications Using jBPM: Part 2


You've been reading an excerpt of:

jBPM Developer Guide

Explore Title