Case management in details at RedHat Summit 2017

I'd like to invite everyone interested in upcoming jBPM 7 feature for case management to RedHat Summit talk

Deep dive on case management

We'll be talking about the most important things to know about how case management is built in jBPM 7 and how to make best out of it. A must to attend for those who plan to accelerate their business with new capabilities to make their work even more flexible.

"Nowadays, the work performed by employees on a day-to-day basis isn't typically a well-defined sequence of tasks, but rather depends much more on the so-called knowledge workers to evaluate the data specific to the case and to collaborate with others to achieve their goals. To be able to better assist these kinds of users, traditional Business Process Management (BPM) Suites have evolved to include much more advanced features related to this case management. On top of that, these workers could benefit a lot from advanced applications, customized to the use case they are trying to solve. In this session, you will receive a deep dive from the experts into what case management is and how we extended our existing framework to better support these kinds of use cases. We will show how you can also develop a customized application on top of Red Hat JBoss BPM Suite more quickly, taking advantage of these advanced capabilities."

Check out the details of the talk and other sessions and trainings on Summit agenda. 

Planning to go there? Maybe it will make it easier with a discount code...

Hope to see you there!!!

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

Prepare for future ... KIE Server Router extension

KIE Server Router was built to cover two main areas:

• hide the complexity of many KIE Server instances hosting different projects (kjars)
• aggregate information from different KIE Servers regardless if they share the same db or host the same projects (kjars)

As described in previous articles, it can find the correct KIE Server instance for the incoming request based on container information that is sent through router. So the basic logic is that router keeps information (routing table) that have following information:

• container id mapped to KIE Server location (url)
• container alias mapped to KIE Server location (url)
• server id mapped to KIE Server location (url)

in the context of this article, only first two are relevant. They are used to find the right server (or one of them) to forward the requests to.

The KIE Servers (Kjar 1 and Kjar 2) can have as many instances as they need that will be connected to the same db and will use the same set of containers deployed to them.

Whenever new request comes in, router will try to find if it contains container information and if so will attempt to find the route to the server that supports it. The situation is very simple if the request comes with container id (as opposed to container alias). As container ids are unique (and should be versioned to provide maximum flexibility) so the look up of the route is easy - just get it from routing table.

A bit more complex scenario is when the alias is used. Obviously this is more appealing to end users (client apps) as they don't have to change the URL whenever new container is deployed. So instead of using container id in the URL, container alias can be used to make the client less coupled with the constantly changing environment. 

By default KIE Server Router deals with container aliases same way as for container ids. Looks them up in the routing table to find the server location. Then it's the individual KIE Server that is responsible to find out concrete container that should be used to deal with that request. That is perfectly fine as long as there is no alias shared across different KIE Server - by different I mean KIE Server that host different kjars (usually different versions of the kjar).

As illustrated at the above diagram in such case, Kjar 2 should then take over entire responsibility for given container alias and host both versions of the project. As soon as it up and running the Kjar 1 server should be removed and then the Kjar 2 takes over entire load. 

This architecture promotes reusability of the runtime environment for the same domain - usually the version of given project are incremental updates that stays in the same domain. So that is what is available by default and the logic to find the proper container is within the KIE Server itself.

... but real world is not as simple ...

There are more options for deployments that would then put more responsibility in the KIE Server Router instead. Like for example taking the action to find out the latest container for an alias across all available containers. For example, if we want our clients to always start with latest available version of a process then client will use alias for container and router should resolve it before forwarding to KIE Server. That would mean that the architecture is that each KIE Server hosts single kjar and each version will bring in new KIE Server instance connected to the router but all of them will share the same alias.

The above setup is not covered by default in KIE Server router because the alias can be resolved to different servers that might not have the kjar deployed that given request is targeting. To allow to cover this use case KIE Server Router was enhanced to allow certain components pluggable:

• ContainerResolver - component responsible for finding the container id to be used when interacting with backend servers
• RestrictionPolicy - component responsible for disallowing certain endpoints from being used via KIE Server Router
• ConfigRepository - component responsible for keeping KIE Server Router configuration, mainly related to the routing table

Since KIE Server Router can run in various environments these components can be replaced or enhanced compared to the defaults. For instance to support the described scenario - router to be responsible to find the latest container and then forward it to that kie server. This can be done by implementing custom ContainerResolver and plug it into the router. 

Implementations are discovered by router via ServiceLoader utility so the jar archives bringing in the new implementation need to have included service descriptor:

• ContainerResolver 
• META-INF/services/org.kie.server.router.spi.ContainerResolver
• RestrictionPolicy
• META-INF/services/org.kie.server.router.spi.RestrictionPolicy
• ConfigRepository
• META-INF/services/org.kie.server.router.spi.ConfigRepository

A sample implementation of all these components can be found in this project at github.

Since default KIE Server Router is ran as executable jar, to provide it the extensions the execution needs to slightly change:

java -cp LOCATION/router-ext-0.0.1-SNAPSHOT.jar:kie-server-router-proxy-7.0.0-SNAPSHOT.jar org.kie.server.router.KieServerRouter

once the server is started you will see log output stating what implementation is used for various components:

Mar 01, 2017 1:47:10 PM org.kie.server.router.KieServerRouter <init>

INFO: KIE Server router repository implementation is InMemoryConfigRepository

Mar 01, 2017 1:47:10 PM org.kie.server.router.proxy.KieServerProxyClient <init>

INFO: Using 'LatestVersionContainerResolver' container resolver and restriction policy 'ByPassUserNotAllowedRestrictionPolicy'

Mar 01, 2017 1:47:10 PM org.xnio.Xnio <clinit>

INFO: XNIO version 3.3.6.Final

Mar 01, 2017 1:47:10 PM org.xnio.nio.NioXnio <clinit>

INFO: XNIO NIO Implementation Version 3.3.6.Final

Mar 01, 2017 1:47:11 PM org.kie.server.router.KieServerRouter start

INFO: KieServerRouter started on localhost:9000 at Wed Mar 01 13:47:11 CET 2017

So that would be all for this article. Stay tuned for more updates and hopefully more out of the box implementations for KIE Server Router.