Introduction to jBPM 6

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
 

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: http://www.jbpm.org/download/download.html

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

jboss.server.wildfly.version=8.2.1.Final
jboss.server.version=wildfly-${jboss.server.wildfly.version}
jboss.home=./${jboss.server.version}
jboss.download.url=http://download.jboss.org/wildfly/${jboss.server.wildfly.version}/${jboss.server.version}.zip
jboss.server.conf.dir=${jboss.home}/standalone/configuration
jboss.server.deploy.dir=${jboss.home}/standalone/deployments
jboss.server.data.dir=${jboss.home}/standalone/data
jboss.clean.repository=true
jboss.war.type=${jboss.server.version}

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';
GRANT ALL PRIVILEGES ON *.* TO 'jbpm'@'localhost' WITH GRANT OPTION;

Next configure your build.properties 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):

#db.driver.jar=${install.home}/db/driver/${db.driver.jar.name}
#db.driver.module.dir=${jboss.home}/modules/${db.driver.module.prefix}/main/
# default is H2
#H2.version=1.3.170
#db.name=h2
#db.driver.jar.name=${db.name}.jar
#db.driver.download.url=http://repo1.maven.org/maven2/com/h2database/h2/${H2.version}/h2-${H2.version}.jar

db.name=mysql
db.driver.module.prefix=com/mysql
db.driver.jar.name=mysql-connector-java-5.1.18.jar
db.driver.download.url=https://repository.jboss.org/nexus/service/local/repositories/central/content/mysql/mysql-connector-java/5.1.18/mysql-connector-java-5.1.18.jar 

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:

<datasources>
   <datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="MySQLDS" enabled="true" use-java-context="true">
      <connection-url>jdbc:mysql://localhost:3306/jbpm</connection-url>
      <driver>mysql</driver>
      <pool />
      <security>
         <user-name>jbpm</user-name>
         <password>jbpm</password>
      </security>
   </datasource>
   <drivers>
      <driver name="mysql" module="com.mysql">
         <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
      </driver>
   </drivers>
</datasources>

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) : -Ddrools.dialect.java.compiler=1.8

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

Follow us on Twitter