2017/03/29

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">
    <authentication>
       <login-module code="Remoting" flag="optional">
            <module-option name="password-stacking" value="useFirstPass"/>
        </login-module>
        <login-module code="RealmDirect" flag="required">
            <module-option name="password-stacking" value="useFirstPass"/>
        </login-module>
<login-module code="org.kie.security.jaas.KieLoginModule" flag="optional" module="deployment.kie-wb.war"/>
      </authentication>
</security-domain>
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...

./standalone.sh
... 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:
jbpm-installer/src/main/resources/db/upgrade-scripts/postgresql/jbpm-6.5-to-7.0.sql

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:
./standalone.sh
 --server-config=standalone-full.xml 
-Djboss.socket.binding.port-offset=150 
-Dorg.kie.server.id=myserver 
-Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller 
-Dorg.kie.server.location=http://localhost:8230/kie-server/services/rest/server 
-Dorg.kie.server.persistence.dialect=org.hibernate.dialect.PostgreSQLDialect 
-Dorg.kie.server.persistence.ds=java:jboss/datasources/psjbpmDS

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 :)