13 min read

jBPM structure

It is an important task to understand the jBPM framework structure. We will find out how the framework sources are divided.

Also, this section is very important for those programmers who want to be active community developers, fixing issues and adding new functionalities.

As we have already discussed, jBPM was built and managed with Maven. For this reason, we will find a file called pom.xml inside our working copy of the official JBoss SVN repository that represents the project as a whole. If we run Maven goals to this project, all the framework will be built. As we have seen in the previous section, all the project modules were built. Look at the previous screenshot that informs us that, by default, the modules Core, Identity, Enterprise, Examples, and Simulation are built when we run the clean install goals to the main project. With the install goal too, the generated jar files are copied to our local Maven repository, so we can use it in our applications by only referencing the local Maven repository.

So, the idea here is to see in detail what exactly these modules include. If you open the modules directory that is located inside your working copy, you will see the following sub-directories:

jBPM Developer Guide

In the next few sections, we will talk about the most important modules that developers need to know in order to feel comfortable with the framework. Take this as a quick, deep introduction to becoming a JBoss jBPM community member.

Core module

The most important module of the jBPM framework is the core module. This module contains all the framework functionality. Here we will find the base classes that we will use in our applications. If you open this directory, you will find the pom.xml file that describes this project. The important thing to notice from this file is that it gives us the Maven ArtifactID name and the GroupID. We will use this information to build our applications, because in our applications, we will need to specify the jBPM dependency in order to use the framework classes.

The following image will show us only the first section of the pom.xml file located inside the modules/core/directory. This file will describe the project name, the group id that it belongs to, and also the relationship with its parent (the main project).

jBPM Developer Guide

If you open this file, you will notice that all the dependencies that this project (jar archive) needs, in order to be built, will be described in the next section. This is also interesting when you want to know exactly which libraries the framework will need to have in the classpath in order to run. You need to remember that Maven will take care of all the transitory dependencies, meaning that in this project file, only the first order dependencies will be described. So, for example, in the dependencies section of the pom.xml file, we will see the Hibernate dependency, but you won’t see all the artifacts needed to build and run Hibernate—Maven will take care of all these second order dependencies.

If we build only the Core module project by running the clean install goal (mvn clean install -Dmaven.test.skip), we will get three new JAR archives in the target directory. These archives will be:

  • jbpm-jpdl-3.2.6.SP1.jar : The core functionality of the framework—you will need this JAR in all your applications that use jBPM directly. Remember, if you are using Maven, you will need to add this artifact dependency to your project and not this archive.
  • jbpm-jpdl-3.2.6.SP1-config.jar : Some XML configurations that the framework needs. This confi guration will be used if you need your process to persist in some relational database.
  • jbpm-jpdl-3.2.6.SP1-sources.jar : This JAR will contain all the sources that were used to build the main jar file. This can be helpful to debug our application and see how the core classes interact with each other when our processes are in the execution stage.

You will also find a few directories that were used as temporary directories to build these three JAR files.

DB module

This module is in charge of building the different database schemes to run jBPM needed by the different vendors that support Hibernate. If you build this module in the target directory of the project (generated with the clean install of maven goals).

Distribution module

This is only a module created with specific goals to build and create the binary installer, which can be downloaded from jBPM’s official page. If you want to get a modified installer of this framework, you will need to build this module. But it is rarely used by development teams.

Enterprise module

This module will contain extra features for high-availability environments, including a command service to interact with the framework’s APIs, an enterprise messages solution for asynchronous execution, and enterprise-ready timers.

If we build this module, we will get three JAR fies. The main one will be jbpm-enterprise-3.2.6.SP1.jar, the source code and the configuration files that these classes will need.

Example module

This is a very interesting module, because it contains some basic examples about how the framework could be used. If you open this module, you will find different packages with JUnit tests that show us how to use the framework APIs to achieve some common situations. These tests are used only for a learning purpose and try to introduce the most common classes that all developers will use. Feel free to play with these tests, modify them, and try to understand what is going on there.

Identity module

This module contains a proof of concept model to use out of the box when we start creating applications that handle human interactions. The basic idea here is to have a simple model to represent how the process users are structured in our company. As you can imagine, depending on the company structure, we need to be able to adapt this model to our business needs. This is just a basic implementation that you will probably replace for your own customized implementation.

jBPM Developer Guide

Simulation module

This module includes some use cases for simulating our process executions. The idea here is to know how to obtain reports that help us to improve our process executions, measuring times, and costs for each execution.

User Guide module

This module will let you build the official documentation from scratch. It is not built when the main project is built, just to save us time. You can build all the documentation in three formats—HTML file separated, one single and long HTML file, or PDF.

Knowing this structure will help us to decide where to make changes and where to look for a specific functionality inside the framework sources. Try to go deep inside the src directory for each project to see how the sources are distributed for each project in more detail.

Building real world applications

In this section, we are going to build two example applications—both similar in content and functionalities, but built with different methodologies. The first one will be created using the Eclipse Plugin provided by the jBPM framework. This approach will give us a quick structure that lets us create our first application using jBPM. On the other hand, in the second application that we will build, we will use Maven to describe and manage our project, simulating a more realistic situation where complex applications could be built by mixing different frameworks.

Eclipse Plugin Project/GPD Introduction

In this section, we will build an example application that uses jBPM using the Eclipse plugin, which provides us with the jBPM framework. The idea here is to look at how these kinds of projects are created and what the structure proposed by the plugin. The outcome of this section will be a Process Archive (PAR) file generated by the GPD plugin, which contains a process definition and all the technical details needed to run in an execution environment.

To achieve this, I have set up my workspace in the directory projects inside the software directory. And by having the jBPM plugin installed, you will be able to create new jBPM projects. You can do this by going to File | New | Other and choosing the New type of project called Process Project.

jBPM Developer Guide

Then you must click on the Next button to assign a new name to this project. I chose FirstProcess for the project name (I know, a very original one!) and click on Next again.

The first time that you create some of these projects, Eclipse will ask you to choose the jBPM Runtime that you want. This means that you can have different runtimes (different versions of jBPM to use with this plugin) installed.

jBPM Developer Guide

To configure the correct runtime, you will need to locate the directory that the installer creates—it’s called jbpm-3.2.6.SP1—then assign a name to this runtime. A common practice here is to put the name with the correct version, this will help us to identify the runtime with which we are configuring our process projects.

Then you should click on the Finish button at the bottom of the window. This will generate our first process project called FirstProcess.

If you have problems creating a new jBPM project, this can be noticed because you’ll have a red cross placed in your project name in the Project Explorer window. You could see the current problems in the Problems window (Windows | Show View | Problems). If the problem is that a JAR file called activation.jar is missing, you should do a workaround to fix this situation. To fix this, you should go to your jBPM installation directory—in this case, software/programs/jbpm-3.2.6.SP1 on my desktop, and then go to src/resources/gpd and open a file called version.info.xml and remove the line that makes the reference to the file called activation.jar. Then you should restart the IDE and the problem will disappear. If you create the process project and the sample process definition is not created (under src/main/jpdl), you could use the project created inside this article’s code directory called FirstProcess.

GPD Project structure

Once you have created the project, we could take a look at the current structure proposed by the plugin.

jBPM Developer Guide

This image show us the structure proposed by the GPD plugin. Four source directories will be used to contain different types of resources that our project will use the first one src/main/ java will contain all the Java sources that our process uses in order to execute custom Java logic. Here we will put all the classes that will be used to achieve custom behaviors at runtime. When you create a process project, a sample process and some classes are generated. If you take a look inside this directory, you will find a class called MessageActionHandler.java. This class represents a technical detail that the process definition will use in order to execute custom code when the process is being executed.

The src/main/config directory will contain all the resources that will be needed to configure the framework.

In the src/main/jpdl directory, you will find all the defined processes. When you create a sample process with your project, a process called simple is created.

And in src/test/ java, you will find all the tests created to ensure that our processes behave in the right way when they get executed. When the sample process is created, a test for this process is also created. It will give us a quick preview of the APIs that we will use to run our processes.

For the sample process, a test called SimpleProcessTest is created. This test creates a process execution and runs it to test whether the process will behave in the way in which it is supposed to work. Be careful if you modify the process diagram, because this test will fail. Feel free to play with the diagram and with this test to see what happens. Here we will see a quick introduction about what this test does.


This test is automatically created when you create a jBPM process project with a sample process. If you open this class located in the src/test/java directory of the project, you will notice that the behavior of the test is described with comments in the code. Here we will try to see step by step what the test performs and how the test uses the jBPM APIs to interact with the process defined using the Graphical Process Editor.

This test class, like every JUnit tests class will extend the class TestCase (for JUNIT 3.x). It then defines each test inside methods that start with the prefix test*. In this case, the test is called testSimpleProcess(). Feel free to add your own test in other methods that use the prefix test* in the name of the method.

If we see the testSimpleProcess() method, we will see that the first line of code will create an object called processDefinition of the ProcessDefinition type using the processdefinition.xml file.

ProcessDefinition processDefinition = ProcessDefinition.

At this point, we will have our process definition represented as an object. In other words, the same structure that was represented in the XML file, is now represented in the Java Object.

Using the APIs provided by JUnit, we will check that the ProcessDefinition object is correctly created.

assertNotNull("Definition should not be null", processDefinition);

Then we need to create a process execution that will run based on the process definition object. In the jBPM language, this concept of execution is represented with the word instance. So, we must create a new ProcessInstance object that will represent one execution of our defined process.

ProcessInstance instance = new ProcessInstance(processDefinition);

Then the only thing we need to do is interact with the process and tell the process instance to jump from one node to the next using the concept of a signal, which represents an external event. It tells the process that it needs to continue the execution to the next node.


If you take a look at all the assert methods used in the code, they only confirm that the process is in the node in which it is supposed to be.

Another thing that this test checks is that the Actions attached to the process change the value of a process variable. Try to figure out what is happening with that variable and where the process definition changes this variable’s value.

The following assert can give you a small clue about it:

assertEquals("Message variable contains message",
getVariable("message"), "Going to the first state!");

To run this test, you just need to right click on the source of this class and go to Run As, and then choose JUnit Test.

jBPM Developer Guide

You should check whether the test succeeded in the JUnit panel (a green light will be shown if all goes well).

Graphical Process Editor

In this section, we will analyze the most used GPD windows, giving a brief introduction to all the functionality that this plugin provides us. We already see the project structure and the wizard to create new jBPM projects.

The most frequently used window that GPD proposes to us is the Graphical Process Editor, which lets us draw our processes in a very intuitive way.

This editor contains four tabs that gives us different functionalities for different users/roles.

Subscribe to the weekly Packt Hub newsletter

* indicates required


Please enter your comment!
Please enter your name here