Get ready for jBPM 7 ... migrate from 6.5 to 7

Yes, that is correct - it's time to get ready for jBPM 7!!!

as part of preparation for final release of community version 7, I'd like to share some thoughts on how to move to it from 6.5.

First of all, the big change that is in version 7 is the separation between authoring/management and runtime. There is no execution engine in workbench any more and obviously there is no REST/JMS endpoints for it either. Though there is still REST api that covers:

  • repository and project management (including maven builds)
  • KIE Server controller
both are in version 6.5 as well and they have not changed much and are expected to be backward compatible.

Focus of this article will be on migrating from 6.5 workbench (as execution server) to 7.0 workbench (as authoring and management) and kie server (as execution server).

Let's put this article in some context, a very basic to keep it simple but should be enough to understand the concepts:
  • single workbench installation running on WildFly
  • single project deployed to execution engine in workbench - org.jbpm:HR:1.5
  • number of process instances started and active in different activities
The goal of this exercise is to make sure we can stop 6.5 "migrate" and start 7 and these process instances can move on.

Prepare for migration

First step before we shutdown version 6.5 is to configure Server Template for the coming version 7 and KIE Server

Here we define server template with name "myserver" that has single container configured "org.jbpm:HR:1.5". The name of the container is important as it must match the deployment id of the project deployed in workbench execution server. And this container is in started state.

As can be seen, there are no remote server attached to it, that's normal as currently workbench is responsible for runtime operations.

Now it's time to shutdown workbench's WildFly server...

Migrate workbench

Once the workbench is stopped it's time to migrate it to version 7 (at the time of writing latest one was Beta8). We are going to reuse same WildFly instance for new version of the workbench, so:
  • Download version 7 of kie-wb for WildFly 10. 
  • Move the workbench (6.5) from deployments directory of the WildFly server
  • Copy new war file into deployments directory - no modification to war file are needed - remember there is no runtime thus there is no persistence.xml to be edited :)
  • remove .index directory that was created by version 6.5 - this is required because version 7 comes with upgraded version of Lucene that is not compatible with one used in 6.5 - don't worry assets will be indexed directly after workbench starts
There is one extra step needed - to add new login module to security domain used by workbench - this is to allow smooth integration with KIE Server on behalf of user logged in to workbench. Just add one line (one marked in red) to standalone[-full].xml

<security-domain name="other" cache-type="default">
       <login-module code="Remoting" flag="optional">
            <module-option name="password-stacking" value="useFirstPass"/>
        <login-module code="RealmDirect" flag="required">
            <module-option name="password-stacking" value="useFirstPass"/>
<login-module code="org.kie.security.jaas.KieLoginModule" flag="optional" module="deployment.kie-wb.war"/>
module  (part in bold) should point to the actual name of the war file you copied to deployments folder.

That's it, now it's time to start WildFly with workbench running version 7...

... yes, we can start it with default profile as there is no runtime in it (mainly JMS) so there is no need for full profile any more. But you can still use standalone-full.xml as server profile, especially if you have done any other configuration changes in it - like system properties, security domain, etc.

After a while, workbench is up and you can logon to it the same way you used to with 6.5.

Once logged in you can navigate to Deploy -> Execution Servers and the server template defined before the migrations should be there.
When you go to Process Definitions or Process Instance they will be empty as there is no KIE Server connected to it ... yet.

NOTE: Workbench uses data set definitions to query data from execution servers. In case you run into errors on data retrieval (process instance, tasks or jobs) make sure you "restore default filters", a small icon on top of the data table

Migrate data base

As of major version, there have been some changes to the data base model that must be applied on data base that was used by version 6.5. jBPM comes with upgrade scripts as part of jbpm installer distribution (alternatively you can find those scripts in github). They are split into data base and version that they upgrade (from -> to)

An example from github:

So this means that the upgrade script is for PostgreSQL db and provides upgrade from 6.5 to 7. Same can be found for major data bases supported by jBPM.

Logon to the data base and execute the script to perform migration of the data model.

Configure KIE Server

Last step is to configure brand new KIE Server version 7. A separate WildFly instance is recommended for it (especially for production like deployments) to separate authoring/management from runtime servers so they won't affect each other.

Most important is to configure WildFly server so it has:
  • same security domain as instance hosting workbench
  • same data sources that point to the active db as had 6.5 workbench 
  • and possibly other execution related configuration 
NOTE: Extra note about security is that users who are going to use workbench to interact with KIE Server (like starting processes, completing tasks) must have kie-server role assigned - security domain that is used by KIE Server.

KIE Server can be started with following command:

Explanation of each line (skipping first line as it's command to start server):
2. select WildFly server profile to be used - requires full as KIE Server comes with JMS support
3. port offset to avoid port conflicts when running on same machine as workbench
4. server id that must match server template name defined in workbench
5. controller location - workbench URL with /rest/controller suffix
6. kie server location - actual location of the kie server (it must include port offset) 
7. hibernate dialect to be used
8. JNDI name of the data source to be used

NOTE: If the kjar was using singleton strategy then file that keeps track of ksession id of that project should be copied from workbench (WILDFLY_HOME/standalone/data/org.jbpm/HR/1.5-jbpmSessionId.ser) to same location in KIE Server's WildFly instance. This is important when you have facts in ksession or timers)

Once server is started, it will connect to workbench and collect list of containers to be deployed (in our case it's just one org.jbpm:HR:1.5)

KIE Server is now connected and ready for execution, you can find it in Deploy -> Execution Servers where it should be now visible as active remote server:

And when navigating to Tasks or Process Instances you should find your active instances left from 6.5

And that's it, now you're ready to take advantage of new features coming in 7 without a need of leaving your 6.5 work behind :)


  1. Separating out the execution service from the workbench is an excellent step. It fits our needs much better - enables pooled + elastic resources. We were able to accommodate something similar with jBPM 6.x using KIE Workbench's "executtion server" capabilities. This was accommplished by simply using the web-exec-server.xml as the web.xml in the KIE war. We required this over the use of the KIE Service as it allowed us to leverage CDI for wiring up custom work item handlers. The KIE Service wasn't CDI capable, if my understanding is correct.

    Is the new execution service CDI capable?

    1. thanks Mark,

      if we are talking about KIE Server itself, it is pure java based, no CDI included. Main motivation for it was all sort of challenges that we faced when supporting major JEE app servers (EAP, WildFly, WebSphere, WebLogic, etc) that caused lots of issues related to CDI and made it really easy when we stayed without any frameworks at all.
      Though if you embed the jbpm you should use jbpm services that come with CDI addon - jbpm services are used by KIE Server as well - so functionality wise they are equal.

    2. We are considering 3 options.

      We are very attached to Dependency Injection. However, we are willing to consider a "pure java" approach. Do you have examples of pure java custom work item handlers for various things like database interaction and rest services (that accommodate more than basic security).

      We are also looking into ways to overlay the version 7 KIE Server (EE7) and add CDI capabilities to it - this would include adding jbpm-services-cdi and wiring the engine up to include InjectableRegisterableItemsFactory.

      We could go the embedded approach - we did this with our current 5.4 based implementation. We wanted to get away from the embedded approach and use jBPM in a less customized way. We wanted to simply take Workbench and an Execution service off the shelf and fully leverage everything you guys have done to facilitate management, configuration, reporting, security, etc..

    3. Mark,

      I am not sure I understand this... either you want to use embedded and then CDI is one of the options or you want to use Kie Server that is then accessible via REST or JMS. If you need to have KIE Server to access CDI beans as part of work item handlers I'd recommend to build a look up layer based on CDI itself - there is programatic way of creating beans or finding them in given context.

  2. ...just wanted to add a quick note here to tie up a previous loose end with my request for "examples of pure java custom work item handlers for ... database interaction". I found a sufficient description of implementing a JPA Work Item from William Siqueira.

    Youtube: https://www.youtube.com/watch?v=jTGEK6zj2oI
    Blog: http://fxapps.blogspot.com/2016/04/a-jbpm-6-jpa-work-item-handler.html
    Github: https://github.com/jesuino/jbpm-jpa-wih

    1. Mark, FYI - William's work is integrated into jBPM (from version 7) as well as he contributed that work.


  3. Hi. I would like to ask, where the reference for kie-server REST API can be found? I've got a list of HTTP methods for version 7, but it has no description, like it was in 6.5 version documentation for Workbench in Chapter 17.

    1. some of the endpoints are described in docs (mainly the common one for all extensions). All endpoints are listed in kie server itself under /docs url. We are currently migrating them to Swagger based and do plan to include documentation for them as part of this migration. so stay tuned.