Introduction to jBPM 6

This tutorial is an introduction to the jBPM 6 platform which has now reached its final release, bringing lots of power to your business processes. For those which are new to jBPM, you should be aware that jBPM is a Business Process Engine that allows defining executing an monitoring your business processes. jBPM is distributed as a set of libraries therefore you are free to choose whether to use it embedded in your applications or simply using it as a BPM Service, for example via the REST API.

In this tutorial we will learn at first how to install the jBPM 6 platform on your machine an create a simple demo process from the jbpm console. In the next lessons we will learn how to run more complex examples using User Tasks and Forms.

Installing jBPM 6

Requirements: You need Apache ant installed on your machine in order to be able to run the installer

Why do we need an installer ?

Technically, jBPM does not need any installer to use it: it is simply made up of a set of JAR files which can be added as a dependency to your project. The installer, however buys you some useful toolings such as: Kie WorkBench or the Eclipse tooling which can be used for Process and rules authoring and testing.

Start by downloading the full installer from:

Once downloaded, check the file which defines several things such as the Application Server version that will contain the KieWorkBench and the Database to be used:


As you can see from the top line, by default the application server WildFly 8.2.1 will be installed. Change the value of the jboss.server.wildfly.version to download a different version of the Application server.

Configuring jbpm6 Database

Jbpm requires a Database for storing Process information and State. out of the box, it is configured to use the embedded in-memory H2 Database. As this configuration is included only for demonstrative purposes, we will show how to install some other Database on it such as MySQL.

It is assumed that you have an installed MySql database: let’s create a database named “jbpm” and an user named as well “jbpm” with full grant privileges:

create database jbpm;
CREATE USER 'jbpm'@'localhost' IDENTIFIED BY 'jbpm';

Next configure your file so that you use the MySQL JDBC Driver settings. At first comment the H2 database setting, next configure MySQL db driver as follows (adapt to your JDBC Driver name):

# default is H2

Great, we’re almost done. Now we will configure the application server to use the MySQL datasource instead of the default H2 db. Reach out the standalone-full-wildfly-8.2.1.Final.xml and configure the jBPM Datasource in both files to use MySQL JDBC Driver:

   <datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="MySQLDS" enabled="true" use-java-context="true">
      <pool />
      <driver name="mysql" module="com.mysql">

Now last thing we need to adapt is the MySQL dialect that is used in the persistence settings. Open the file jbpm-installer\db\jbpm-persistence-JPA2.xml and comment H2 dialect and replace it with:

<!--  <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect" />-->
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>

Great! we are done and we can try running the installation with:

ant install.demo

This will requires just a few minutes as nothing should be downloaded but just expanded from your distribution.

A tweak for WildFly users

There is a known issue that the ejc (eclipse java compiler) jar included in that version of Wildfly is NOT recognising Java8 correctly, and is therefore falling back to Java 1.5 (where auto-casting of Long to long isn’t supported). In order to force the application server to use Java8 simply pass this System Property to the application server (ex. in JAVA_OPTS) :

Database schema creation required ?

The Database schema is created automatically, once that the engine is started, from the Entity classes. As an alternative, prior to launching the application server, you can execute the DDL scripts which are contained in the db\ddl-scripts\mysql5 folder of your installer:

mysql < jbpm mysql5-jbpm-schema.sql -u jbpm -p
mysql < quartz_tables_mysql.sql -u jbpm -p

Starting jBPM 6 engine

Once completed, we will start the application server and check out the jbpm console. Since the jbpm6 console contains some resources bound to the jms adapter, we will need starting jboss using the full (or full-ha) profile:

standalone.bat -c standalone-full.xml

Once the application server is up and running, verify that the jbpm-console has been deployed by reaching out the default address: http://localhost:8080/jbpm-console
The default users and their roles are picked up from the and contained in the configuration folder of the application server. Choose one such as krisv/krisv and enter them in the console.

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto

The KIE Workbench is a rich web application which can be used for a variety of purposes such as authoring processes, starting and monitoring them and their tasks. The first thing we will do is selecting from the upper Menu Authoring -> Project Authoring

jbpm 6 tutorial introduction howto
From there, you will be able to access the “New Item” Menu where we will choose the “Project” option. Enter a name for the new project in the following window:

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto
Now you will be requested to enter the Group Specification version for our project: as you can see, projects stored in jbpm6 repository are stored as Maven resources and you have even some ready-to use Maven artifacts for creating jbpm6 projects.

jbpm 6 tutorial introduction howto
Save your Project. We will now create a Business Process in this project. Select from the New Item menu the option “Business Process“. Enter a name for the process and check that it’s part of your project.

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto
Now the BPMN 2.0 editor will start: click on the Object library icon (“<<“) to show the palette of items you can add to your process. In this very basic example, we will just add a Script item (under the Tasks menu) and an End item (“End events”). Connect each item by clicking on the item and selecting the Edge option which will connect a pair of items. So your first process should look like this:

jbpm 6 tutorial introduction howto

Now let’s specify an action to execute on the Script node: just select it and pickup the icon “<<” which is located on the right border of your process. Enter a Java expression in the “Script” field, such a basic HelloWorld Message.

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto
Now click on the “Save” icon, in the process toolbar:

jbpm 6 tutorial introduction howto
Now return to the upper menu Authoring->Project Authoring. In the upper right side, you will find the Save – Build And Deploy options.

jbpm 6 tutorial jbpm 6 tutorial introduction howto

Choose to Save changes first, then click on Build and Deploy. A quick popup message will inform you that the pom.xml has been saved and your project deployed. Now we will execute our first project: select the Process Management->Process Definition option. There you will find the demoprocess that we have just created and click on the start icon.

jbpm 6 tutorial introduction howto
A window containing an automatically generated form will appear. As we didn’t enter any variable definition in our form, just click on the right arrow to launch your process:

jbpm 6 tutorial introduction howto
The Instance Details frame will populate including the details of your process that we have just started.

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto
As a confirmation that your process correctly executed, move to the Application Server console and check out for the log message:

jbpm 6 tutorial introduction howto jbpm 6 tutorial introduction howto
Great! you have just completed your first jBPM 6 process.