jBPM 6 with spring

As some of you might noticed jBPM got quite few improvements for version 6.0, to just name few:

  • RuntimeManager
  • enhanced timer service
  • new deployment model – based on kjar and maven
  • brand new tooling 
  • see release notes for more
there is (as always) still room for improvements. After 6.0 went out, we started to look at how we could ease the usage of jBPM in Spring based applications on top of the new API. Lots of the API is now based on the concept of fluent API which is not really Spring friendly.
Before we dive into details of the API and how it can be used in Spring let’s look at possible usage scenarios that users might be interested in:
  • Self managed process engine
This is the standard (and the simplest) way to get up and running with jBPM in your application. You only configure it once and run as part of the application. With the RuntimeManager usage, both process engine and task service will be managed in complete synchronization, meaning there is no need from end user to deal with “plumbing” code to make these two work together. 
  • Shared task service
There could be a need in certain situations, that a single instance of a TaskService is used. This approach give more flexibility in configuring the task service instance as it’s not behind RuntimeManager. Once configured it’s then used by the RuntimeManager when requested. RuntimeManager in such situation will not create new instances of task service as it’s done with self managed process engine approach.
To provide spring based way of setting up jBPM, few factory beans where added:

org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean

Factory responsible for producing instances of RuntimeEnvironment that are consumed by RuntimeManager upon creation. It allows to create following types of RuntimeEnvironment (that mainly means what is configured by default):
  • DEFAULT – default (most common) configuration for RuntimeManager
  • EMPTY – completely empty environment to be manually populated
  • DEFAULT_IN_MEMORY – same as DEFAULT but without persistence of the runtime engine
  • DEFAULT_KJAR – same as DEFAULT but knowledge asset are taken from KJAR identified by releaseid or GAV
  • DEFAULT_KJAR_CL – build directly from classpath that consists kmodule.xml descriptor
Mandatory properties depends on the selected type but knowledge information must be given for all types. That means that one of the following must be provided:
  • knowledgeBase
  • assets
  • releaseId
  • groupId, artifactId, version
Next for DEFAULT, DEFAULT_KJAR, DEFAULT_KJAR_CL persistence needs to be configured:
  • entity manager factory
  • transaction manager
Transaction Manager must be Spring transaction manager as based on its presence entire persistence and transaction support is configured.  Optionally EntityManager can be provided to be used instead of always creating new one from EntityManagerFactory – e.g. when using shared entity manager from Spring. All other properties are optional and are meant to override the default given by type of the environment selected.

org.kie.spring.factorybeans.RuntimeManagerFactoryBean

FactoryBean responsible for creation of RuntimeManager instances of given type based on provided runtimeEnvironment. Supported types:
  • SINGLETON
  • PER_REQUEST
  • PER_PROCESS_INSTANCE
where default is SINGLETON when no type is specified.  Every runtime manager must be uniquely identified thus identifier is a mandatory property. All instances created by this factory are cached to be able to properly dispose them using destroy method (close()).

org.kie.spring.factorybeans.TaskServiceFactoryBean

Creates instance of TaskService based on given properties. Following are mandatory properties that must be provided:
  • entity manager factory
  • transaction manager
Transaction Manager must be Spring transaction manager as based on its presence entire persistence and transaction support is configured. Optionally EntityManager can be provided to be used instead of always creating new one from EntityManagerFactory – e.g. when using shared entity manager from Spring. In addition to above there are optional properties that can be set on task service instance:
  • userGroupCallback – implementation of UserGroupCallback to be used, defaults to MVELUserGroupCallbackImpl
  • userInfo – implementation of UserInfo to be used, defaults to DefaultUserInfo
  • listener – list of TaskLifeCycleEventListener that will be notified upon various operations on tasks
This factory creates single instance of task service only as it’s intended to be shared across all other beans in the system.

Now we know what components we are going to use, so it’s time to look at how we could actually configure our spring application to take advantage on jBPM version 6. We start with the simple self managed approach where we configure single runtime manager with inline resources (processes) added.
1. First we setup entity manager factory and transaction manager:
  <bean id="jbpmEMF" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<property name="persistenceUnitName" value="org.jbpm.persistence.spring.jta"/>
</bean>

<bean id="btmConfig" factory-method="getConfiguration" class="bitronix.tm.TransactionManagerServices">
</bean>

<bean id="BitronixTransactionManager" factory-method="getTransactionManager"
class="bitronix.tm.TransactionManagerServices" depends-on="btmConfig" destroy-method="shutdown" />

<bean id="jbpmTxManager" class="org.springframework.transaction.jta.JtaTransactionManager">
<property name="transactionManager" ref="BitronixTransactionManager" />
<property name="userTransaction" ref="BitronixTransactionManager" />
</bean>
with this we have ready persistence configuration that gives us:

  • JTA transaction manager (backed by bitronix – for unit tests or servlet containers)
  • entity manager factory for persistence unit named org.jbpm.persistence.spring.jta
2. Next we configure resource that we are going to use – business process

<bean id="process" factory-method="newClassPathResource" class="org.kie.internal.io.ResourceFactory">
<constructor-arg>
<value>jbpm/processes/sample.bpmn</value>
</constructor-arg>
</bean>

this configures single process that will be available for execution – sample.bpmn that will be taken from class path. This is the simplest way to get your processes included when trying out jbpm.

3. Then we configure RuntimeEnvironment with our infrastructure (entity manager, transaction manager, resources)

<bean id="runtimeEnvironment" class="org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean">
<property name="type" value="DEFAULT"/>
<property name="entityManagerFactory" ref="jbpmEMF"/>
<property name="transactionManager" ref="jbpmTxManager"/>
<property name="assets">
<map>
<entry key-ref="process"><util:constant static-field="org.kie.api.io.ResourceType.BPMN2"/></entry>
</map>
</property>
</bean>

that gives us default runtime environment ready to be used to create instance of a RuntimeManager.

4. And finally we create RuntimeManager with the environment we just setup

<bean id="runtimeManager" class="org.kie.spring.factorybeans.RuntimeManagerFactoryBean" destroy-method="close">
<property name="identifier" value="spring-rm"/>
<property name="runtimeEnvironment" ref="runtimeEnvironment"/>
</bean>

with just four steps you are ready to execute your processes with Spring and jBPM 6, utilizing EntityManagerFactory and JTA transaction manager.

As an optional step, especially useful when testing you can create AuditLogService to get history information of your process executions.

<bean id="logService" class="org.jbpm.process.audit.JPAAuditLogService">
<constructor-arg>
<ref bean="jbpmEMF"/>
</constructor-arg>
</bean>

Complete spring configuration file can be found here.

This is just one configuration setup that jBPM 6 supports – JTA transaction manager and EntityManagerFactory, others are:

  • JTA and SharedEntityManager
  • Local Persistence Unit and EntityManagerFactory
  • Local Persistence Unit and SharedEntityManager
What is important to note here is that there is no need to setup TaskService at all, some part of it like user group callback, can be configured via RuntimeEnvironment but the whole setup is done automatically by RuntimeManager. No need to worry about that.
Although if you need more control over TaskService instance you can set it up yourself and let RuntimeManager use it instead of creating its own instances.
To do so, you start the same as for self managed process engine case, follow step 1 and 2. Next we configure task service

<bean id="taskService" class="org.kie.spring.factorybeans.TaskServiceFactoryBean" destroy-method="close">
<property name="entityManagerFactory" ref="jbpmEMF"/>
<property name="transactionManager" ref="jbpmTxManager"/>
<property name="listeners">
<list>
<bean class="org.jbpm.services.task.audit.JPATaskLifeCycleEventListener" />
</list>
</property>
</bean>
with that we add an extra task life cycle listener to save all task operations as log entires.

Then, step 3 needs to be slightly enhanced to set task service instance in the runtime environment so RuntimeManager can make use of it

<bean id="runtimeEnvironment" class="org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean">
<property name="type" value="DEFAULT"/>
<property name="entityManagerFactory" ref="jbpmEMF"/>
<property name="transactionManager" ref="jbpmTxManager"/>
<property name="assets">
<map>
<entry key-ref="process"><util:constant static-field="org.kie.api.io.ResourceType.BPMN2"/></entry>
</map>
</property>
<property name="taskService" ref="taskService"/>
</bean>

that will disable task service creation by RuntimeManager and always use this single shared instance.
Step 4 (creating RuntimeManager) is exactly the same.

Look at the example configuration files and test cases for more details on how they are utilized.

Please also note that factory beans for spring integration are currently scheduled to be released with 6.1.0 version of jBPM but I would like to encourage you to give it a try before so in case something is not working or missing we will have time to fix it and let it out with 6.1.0.Final. So all hands on board and let’s spring it 🙂

Results from the Drools & jBPM Workshop @ Bcn (10th Dec)

I’m quite happy to say that the Barcelona Workshop was a complete success. Once again I would like to thanks the @BarcelonaJug for all the effort that they put into organise these meetups. This post is to share some pics and some overall comments about the event.

The Barcelona Java User Group

5df05-logo_bicolor_blog
Find here some pics about the group, with almost 30 attendees interested in Drools & jBPM the workshop was a success, all of the attendees manage to run & play with KIE Workbench:
photo
IMG-20131212-WA0007IMG-20131212-WA0003IMG-20131212-WA0005IMG-20131212-WA0006IMG-20131212-WA0008IMG-20131212-WA0002

If you are working in a company based in Barcelona, I strongly suggest you to support your local JUG. This will benefit you to build up your knowledge, bring expert people from abroad and share the knowledge that is being produced locally by the other members of the group.

Do the Workshop on your own Laptop

Once again I’m sharing the files that we distributed on the workshop so you can try it on your own environment. If you are interested in building all the projects from the source code let me know I can help you out to set up the environment to get you started.

Feedback from the Community

As usual, when we present the community projects, we gather a lot of feedback from the people that is testing the tool and we take notes to improve the user experience. I’ve noticed from this last meet up that there is a lot of interest in knowing about the project internals. For that reason I’ve proposed another meet up probably for the beginning of February to cover Drools & jBPM from the framework perspective without showing the tooling. I do believe that knowing the framework internals is something interesting for most of developers, but at the same time I feel that knowing about the tools will give them a more higher level understand about what’s the main purpose of these frameworks and tools. You can obviously target to a wider audience with the UI provided by the KIE Workbench, showing with this tools how you can help the whole company spectrum with a knowledge driven solution.
As a reminder, all the software that we had shown in the meet up was built using the master branch of the source code repositories, so you can expect some issues that are being solved. The main idea of showing the community builds is to encourage people to participate into this community projects.
Feel free to write some comments into this blog post with some suggestions about what kind of topics you would like to see in an internal talk about Drools & jBPM. I usually like to talk about both frameworks because they shared a lot of common topics that needs to be discussed under the same context.

jBPM 6 first steps

This post is about to give a very quick introduction to how users can take their first steps in jBPM 6. Using completely web tooling to build up:

  • processes
  • rules
  • process and task forms
  • data model
With just three simple examples you will learn how easy and quickly you can start with BPM. So let’s start.

The simples process

First process is illustrating how you move around in KIE workbench web application. Where to:
  • create repository
  • create project
  • configure Knowledge Base, KnowledgeSession
  • create process
  • build and deploy
  • execute process and work with user task

Custom data and forms

Next let’s explore more and start with bit advanced features like:

  • building custom data model that will be used as process variable
  • make use of process variables in user task
  • define custom forms for process and tasks
  • edit and adjust your process and task forms

Make use of business rules and decisions in your process

At the end let’s make the process be more efficient by applying business rules in the process and then use gateways as deception points. This example introduces:

  • use of business rule task
  • define business rules with Drools
  • use XOR gateway to split between different paths in the process
Important to note that business rule task can automatically insert and retract process variables using data input and output of business rule task. When defining them make sure that both data input and output are named exactly the same to allow engine to properly retract the facts on business rule task completion.
That would be all for the first steps with jBPM 6. Stay tuned for more examples and videos!
As usual comments more than welcome.

KIE WORKBENCH: TESTING THE EVALUATION PROCESS

A old/new example was migrated to https://github.com/droolsjbpm/jbpm-playground.git , The evaluation project is now provided and you can try it out following my previous posts from here and here. The Evaluation process shows how a task can be created and assigned based on a process variable. Feel free to try it out and give some feedback about it. Look at the end of the post, if you are looking for helping us to build useful examples.

The Evaluation Process Example

This example simulates an internal Evaluation process for the employees inside Acme Inc. This process is executed every quarter once per person inside the research department. The Human Resources department of Acme Inc. will instantiate one process instance for each employee adding a reason justifying why the evaluation is being performed.
Evaluation Process
Evaluation Process
In order to instantiate a process instance you need to specify the user/employee that you are going to evaluate. Notice that the “employee” needs to be a valid user in the system. This is because the first task of the process called “Self Evaluation” will be automatically assigned to the specified employee.
New Process Instance
New Process Instance
In this case the Evaluation will be performed on the already configured user called “salaboy”. So the first task will be automatically assigned to “salaboy“. In order to see the task you will need to be logged as “salaboy”.
Notice that the “HR Evaluation” and the “PR Evaluation” are performed by the HR and PR group respectively. So you need to have users configured for those Groups in order to see the tasks associated with them.
The following screenshot shows how to assign a task to a specific actor using a process variable. In this case the #{employee} expression is picking the process variable called “employee” and assigning the task to the specified actor. For that reason it is important that the employee entered in the first form exists.
Assigning a Task Using a Process Variable
Assigning a Task Using a Process Variable
Once you complete the “Self Evaluation” task the HR Evaluation and PM Evaluation Tasks will be automatically created. You will need to log out and login with users in the HR and PM group in order to perform those tasks and complete the process instance.

Join Us Providing your Example Processes

If you have a process example or a business scenario that you want to see working in the KIE Workbench and you think that it can serve as an example for other people to get used to the tool or to show some specific functionality, please get in touch and we can work together to get that included in the jbpm-playground repository. Notice that I would like to keep only high level and business oriented processes inside that repository, so make sure that it make some sense from the business perspective level. We will be creating 
I will be posting more examples over the week, so we can cover a wide range of scenarios that allows users to build their own by copying from the examples or at least using them as guidelines.

RESULTS: DROOLS & JBPM WORKSHOPS (LONDON)

Hi everyone out there, I’m writing this post just to share the slides from the Drools & jBPM workshops that we (Michael Anstis and I) did this week in central London. Hopefully we can host more of these workshops in other cities. If you are interested in running one of these workshops get in contact and we can help you to set it up.
Here are the slides, and the video for the second day. 

Slides

Video: Day 2 – JBPM and KIE Projects

Special thanks to @mbitencourt for broadcasting the event!

Related Posts

Look at the following posts if you are interested to read about the content of the workshops.
All the examples that I’ve demonstrated in the workshops are hosted in this repository:

Feedback

One of the main purposes behind doing these workshops was to collect feedback from the developers before the Final Community release. We manage to identify three major bugs which were identified and will be fixed for the final release, so I would like to thank you everyone out there who has tested the application and gave feedback about it.
If you want to try it out, read my related posts or get in contact with me so I can guide you to try the KIE Workbench.

KIE-WB / JBPM CONSOLE NG – CONFIGURATIONS

Hi all, this is a follow up post from my previous entry about how to use the jBPM Console. The main idea of this post is to describe some of the most common configurations that you will required to do to the jBPM Console NG in order to use it in your own company. But before going into technical details we will be covering the differences between the KIE Workbench (KIE-WB) and the jBPM Console NG itself. Both applications require similar configurations and its good to understand when to pick one or the other. We will be covering these topics in the free workshops in London. 

Introduction

If you look at the project source code and documentation, you will notice that there are several projects that are being created to provide a complete set of tools for Drools and jBPM. Because of the modular approach that we have adopted for building the tools, you can basically choose between different distributions depending on your needs. The jBPM Console NG can be considered as a distribution of a set of packaged related with BPM only. The KIE Workbench (KIE-WB) is the full distribution, that contains all the components that we are creating, so inside it you will find all the BPM and Rules modules. If more modules are added to the platform, the KIE-WB will contain them.
Sometime ago Michael Anstis posted an article in blog.athico.com to explain this transition: http://blog.athico.com/2013/06/goodbye-guvnor-hello-drools-workbench.html This blog post was targeted to Guvnor users, so they can understand the transition between Drools 5.5 and Drools 6. So the intention behind the following  section is to explain the same but for jBPM users, trying to unify all the concepts together.

Projects Distributions

The previous mentioned blog explains most of the components that we are creating now, but the following image add some details on the BPM side:
Project Distributions
Project Distributions
Some quick notes about this image:
  • Uberfire and Guvnor are both frameworks, not distributions.
  • We are keeping the name Guvnor for what it was originally intended. Guvnor is a framework to define all the internal project automation and organization. Guvnor is the internal framework that we will use to provide a smart layer to define how projects and all the knowledge assets will be managed and maintained.
  • KIE-WB-Common is not a distribution by itself but it could, because it contains all the shared bits between all the distributions.
  • Drools Workbench only contains authoring tools related with Rules, notice that in the same way as Guvnor it doesn’t provide a runtime for your rules. This could be added in the future but in 6.0 is not.
  • The jBPM Console NG replaced the old jBPM GWT console
  • The difference between names (Drools Workbench and jBPM Console NG) is due the fact that the jBPM Console NG does provide all the runtime mechanisms to actually run your Business Processes and all the assets associated with them.
  • Notice that the jBPM Console NG uses some of the Drools-WB modules and also integrates with the jBPM Designer and the Form Modeller.
  • KIE Workbench contains all the components inside the platform and also add the Remote Services to interact with processes.
  • Notice that the Remote Service in 6.x are only for the BPM side, that means that we can also provide the jBPM Console NG distribution with those services, it is not a priority right now but it can be done if someone thinks that it’s a good idea.
  • You can find all these projects under the droolsjbpm organization in github: http://github.com/droolsjbpm
  • All the configurations and blogs related to the jBPM Console NG also applies for the KIE Workbench
  • The jBPM 6.0 installer will come with KIE Workbench bundled and because of this most of my posts will be showing screenshots of KIE-WB instead of the jBPM Console NG.

Configurations & Deployment

If you take a look at the source code repositories in Github, you will find that the jBPM Console NG, Drools Workbench and Kie Workbench contains a project called *-distribution-wars. These projects are in charge of generating the applications to be distributed for different Servlet Containers and Application Servers. For now we are providing bundles for Tomcat 7, JBoss AS 7, and JBoss EAP 6.1. (If you are a developer, you can also run these applications using the GWT Hosted Mode, which starts up a Jetty server and automatically deploys the application so it can be easily debugged.)
Here we will see how to deploy and configure the application to work in JBoss AS 7. Obviously you don’t need to do so if the jBPM Installer does that for you. But is always good to know what is going on under the hood, just in case that you prefer to manually install the applications.
There are three points to consider when we configure the application for deployment:
  1. Users/Roles/Groups
  2. Domain Specific (Custom) Connectors
  3. JBoss AS 7 Profile
For the sake of simplicity, I’ve borrowed a JBoss AS 7 configured by Maciej and deployed the KIE Workbench latest snapshot, so you can download it and we can review it’s configurations from there. You can download it from here:

Users/Roles/Groups

By default the KIE-Workbench uses the JBoss AS configured users to work. In order to create a new user we need to use the ./add-user.sh script located inside the /bin/ directory. Using this script we will be creating all the users required by our business processes, and for that reason we will be also assigning them groups and roles.
Adding a New User
Adding a New User
As you can see in the previous image, using the ./add-user.sh script you can create a new user for the application (first two options: option B, and empty realm). Note that you need to use different strings for the user name and for the password. For now you can create users with role admin, so it will have access to all the screens of the tool and then you can write the groups where the user belongs. In this case the user salaboy has Role: admin and he belongs to the IT group. There are some restricted words that cannot be used as group names. For now avoid using “analyst”, “admin”, “developer” for group names.

Domain Specific (Custom) Tasks / Connectors

Domain Specific Connectors are the way to integrate your business processes with external services that can be inside or outside your company. These connectors are considered technical assets and because of that needs to be handled by technical users. Most of the time it is recommended to not change/modify the connectors when the application is running, and for that reason these connectors needs to be provided for the application to use in runtime.
Three things are required to use a Custom Connector:
  1. Provide an implementation of the WorkItemHandler interface, which is the one that will be executed in runtime.
  2. Bind the implementation to a Service Task name
  3. Create the WorkItem Descriptor inside the tool
In order to provide these three configuration points you can take a look at the Customer Relationship example in the jbpm-playground repository.
Customer Relationships Example
Customer Relationships Example
The main idea here is to have a separate project that contains the workItems implementations, for example: CreateCustomerWorkItemHandler , you will need to compile this project with maven and install the produced jar file inside the KIE-WB application. In order to do that you just copy the customer-services-workitems-1.0-SNAPSHOT.jar into the WEB-INF/lib directory of the kie-wb.war app. On this example the workItemHandler implementations interacts with a public web service that you can check here , so you will require internet connection in order to try this example.
Notice also that inside the customer-relationship project there are some high level mappings of the Domain Specific Tasks that can be used inside our Customer Relationship Project -> WorkItemDefinitions.wid. This configuration will basically add you Service Tasks inside the Process Designer Palette:
Domain Specific Service Tasks
Domain Specific Service Tasks
The last step is to bind the High Level mapping to their implementation for this environment. You can do that by adding new entries into the WEB-INF/classes/META-INF/CustomWorkItemHandlers.conf  file, for this example we just need to add the following entries:
“CreateCustomer”: new org.jbpm.customer.services.CreateCustomerWorkItemHandler(),
“AddCustomerComment”: new org.jbpm.customer.services.AddCustomerCommentsWorkItemHandler(),
“ManagersReport”: new org.jbpm.customer.services.ManagersReportWorkItemHandler(),

Note about the JBoss AS 7 Profile

In order to run the KIE Workbench you need to run it with full JBoss AS7 profile, so if you are installing it using a fresh JBoss AS7 please don’t forget to point to the full project when you use the ./standalone.sh script:
./standalone.sh –server-config=standalone-full.xml

Download

You can download a pre installed version of KIE-WB where you can clone the jbpm-playground repository which contains the example (Authoring -> Administration and then Clone a Repository using the jbpm-playground url: https://github.com/droolsjbpm/jbpm-playground).
This pre installed version contains the workItemHandlers already installed and configured for the Customer Relationship example, but you can obviously make some changes and upgrade them if it’s needed.
It also has two users created:
User/Password: jbpm/jbpm6 (Groups: IT, HR, Accounting, etc)
User/Password: salaboy/salaboy123 (Groups: IT)
Please feel to try it out and let me know if it works for you.
There are some few seats available for the Drools & jBPM Free Workshop Tomorrow and on Thursday. If you are planning to assist please write me an email to salaboy (at) redhat (dot) com. For more details about it look here. 

Drools and jBPM 6 Free Workshops (23/24 October – London)

Hi All, I would like to invite everyone to a couple of developer oriented workshops about the tools in the newest Drools and jBPM releases (6 series). The main idea of these workshops is to introduce developers to the new set of features and tooling provided by the projects.
We (Michael Anstis and I) will be showing how to configure and set up your working environment to work, customize and contribute to these projects.
We will be trying to cover the following topics:
  • General Overview about the tools
  • Distributions and Modules
  • Technology Stack
  • How to setup your working environment
  • How to extend/customize the tooling
If you are brave enough and want to know the low level technical details of the tooling, please bring your laptop and be prepared to download the code and compile it in your own environment. We will assist you in the process and give you all the pointers to fix issues or provide new features.
Michael will be in charge of the Drools Side of the platform and I (Salaboy) will be in charge of the BPM side of the tooling. If you are planning to start using these tools, we encourage you to attend to see the new features and get a high level overview about all the new things that are coming with the new version.
The place and the coffee will be sponsored by Plug Tree and the workshops will take place on the 23rd and 24th of October at No. 1 Poultry, London, EC2R 8JR From 3pm to 5pm+.  Seats are very limited, and because workshops are free you need to get in touch with us (salaboy at redhat dot com) if you are planning to attend. We will probably send you details of what you need to download before coming to the workshop so as not to depend on the local internet connection.

jBPM6 samples with RuntimeManager

jBPM6 introduces new module – jbpm-runtime-manager – that aims at significantly simplify management of:

  • KnowledgeBase (KieBase)
  • KnowledgeSession (KieSession)
Moreover it allows to use predefined strategies for handling knowledge sessions and its relation to process instance. By default jBPM6 comes with three strategies:
  • Singleton – single knowledge session that will execute all process instances
  • Per Request – every request (which is in fact call to getRuntimeEngine) will get new knowledge session
  • Per Process Instance – every process instance will have its dedicated knowledge session for the entire life time
To make use of the strategy it’s enough to create proper type of RuntimeManager. jBPM6 allows to obtain instance of the RuntimeManager in various ways, this article will provide hands on information on how it can be achieved. 
With jBPM6 a whole new way of building application has been provided – Context and Dependency Injection is now available for users to build application and bring the power of jBPM to next level. Obviously CDI is not the only way to make use of jBPM – the regular API based approach is still available and fully functional.

CDI integration

jBPM6 tooling (like jbpm console or kie-wb) is built on CDI and thanks to that set of services has been provided to ease the development for custom applications that are based on CDI. These services are bundled as part of jbpm-kie-services and provides compact solution to most of the required operations to put BPM into your application:
  • deployment service – deploys and undeploys units (kjars) into the process engine
  • runtime service – gives access to state of the process engine, like retrieve process definitions, process instances, history log, etc
  • bpmn2 data service – gives access to details of the process definition taken from BPMN2 xml
  • form provider service – gives access to forms for processes and tasks
So whenever custom application is built with CDI these services are recommended way to go to get most of the power of CDI and jBPM. Moreover it’s the safest way too as it is used in jBPM tooling so it got fair amount of testing to secure it does what is expected.
Using jbpm-kie-services is not a mandatory to be able to use jBPM6 in CDI environment but it does have some advantages:
– allow to maintain multiple RuntimeManagers within single execution environment
– allow independent deploy and undeploy of units (kjar) without server/application restart
– allow to select different strategies for different units
See jbpm-sample-cdi-services project for details.
while these are all appealing add-ons they are not always needed, especially if application requires only single RuntimeManager instance to be included in the application. If that’s the case we can let CDI container to create the RuntimeManager instance for us. That is considered second approach to CDI integration where only single instance of RuntimeManager is active and it’s managed completely by the CDI container. Application needs to provide environment that RuntimeManager will be based on. 
See jbpm-sample-cdi project for details.

API approach

Last but not least is the regular API based approach to jBPM6 and RuntimeManager. It expects to be built by the application and in fact provides all configuration options. Moreover this is the simplest way to extend the functionality of RuntimeManager that comes out of the box.
See jbpm-sample project for details.
This article is just an introduction to the way jBPM6 and RuntimeManager can be used. More detailed articles will follow to provide in-depth information on every option given here (cdi with services, pure cdi, api).
If you have any aspects that you would like to see in next articles (regarding runtime manager and CDI) just drop a comment here and I’ll do by best to include them.

Make your work asynchronous

Asynchronous execution as part of a business process is common requirement. jBPM has had support for it via custom implementation of WorkItemHandler. In general it was as simple as providing async handler (is it as simple as it sounds?) that delegates the actual work to some worker e.g. a separate thread that proceeds with the execution.

Before we dig into details on jBPM v6 support for asynchronous execution let’s look at what are the common requirements for such execution:

  • first and foremost it allows asynchronous execution of given piece of business logic
  • it allows to retry in case of resources are temporarily unavailable e.g. external system interaction
  • it allows to handle errors in case all retries has been attempted
  • it provides cancelation option
  • it provides history log of execution
When confronting these requirements with the “simple async handler” we can directly notice that all of these would need to be implemented all over again by different systems. So that is not so appealing, isn’t?

jBPM executor to the rescue 

Since version 6, jBPM introduces new component called jbpm executor which provides quite advanced features for asynchronous execution. It delivers generic environment for background execution of commands. Commands are nothing more than business logic encapsulated with simple interface. It does not have any process runtime related information, that means no need to complete work items, or anything of that sort. It purely focuses on the business logic to be executed. It receives data via CommandContext and returns results of the execution with ExecutionResults. The most important rule for both input and output data is – it must be serializable.
Executor covers all requirements listed above and provides user interface as part of jbpm console and kie workbench (kie-wb) applications.
Illustrates Jobs panel in kie-wb application
Above screenshot illustrates history view of executor’s job queue. As can be seen on it there are several options available:
  • view details of the job
  • cancel given job
  • create new job
With that quite few things can already be achieved. But what about executing logic as part of a process instance – via work item handler?

Async work item handler

jBPM (again since version 6) provides an out of the box async work item handler that is backed by the jbpm executor. So by default all features that executor delivers will be available for background execution within process instance. AsyncWorkItemHandler can be configured in two ways:
  1. as generic handler that expects to get the command name as part of work item parameters
  2. as specific handler for given type of work item – for example web service
Option number 1 is by default configured for jbpm console and kie-wb web applications and is registered under async name in every ksession that is bootstrapped within the applications. So whenever there is a need to execute some logic asynchronously following needs to be done at modeling time (using jbpm web designer):
  • specify async as TaskName property 
  • create data input called CommandClass
  • assign fully qualified class name for the CommandClass data input
Next follow regular way to complete process modeling. Note that all data inputs will be transferred to executor so they must be serializable.
Illustrates assignments for an async node (web service execution)
Second option allows to register different instances of AsyncWorkItemHandler for different work items. Since it’s registered for dedicated work item most likely the command will be dedicated to that work item as well. If so CommandClass can be specified on registration time instead of requiring it to be set as work item parameters. To register such handlers for jbpm console or kie-wb additional class is required to inform what shall be registered. A CDI bean that implements WorkItemHandlerProducer interface needs to be provided and placed on the application classpath so CDI container will be able to find it. Then at modeling time TaskName property needs to be aligned with those used at registration time.

Ready to give it a try?

To see this working it’s enough to give a try to the latest kie-wb or jbpm console build (either master or CR2). As soon as application is deployed, go to Authoring perspective and you’ll find an async-examples project in jbpm-playground repository. It comes with three samples that illustrates asynchronous execution from within process instance:
  • async executor
  • async data executor
  • check weather
Async executor is the simplest execution process that allows execute commands asynchronously. When starting a process instance it will ask for fully qualified class name of the command, for demo purpose use org.jbpm.executor.commands.PrintOutCommand which is similar to the SystemOutWorkItemHandler that simple prints out to logs the content of the CommandContext. You can leave it empty or provide invalid command class name to see the error handling mechanism (using boundary error event).
Async data executor is preatty much same as Async executor but it does operate on custom data (included in the project – User and UserCommand). On start process form use org.jbpm.examples.cmd.UserCommand to invoke custom command included in the project.

Check weather is asynchronous execution of a web service call. It checks weather for any U.S. zip code and provides results as a human task. So on start form specify who should receive user task with results and what is the zip code of the city you would like to get weather forecast for.

Start Check weather process with async web service execution
And that’s it, asynchronous execution is now available out of the box in jBPM v6. 
Have fun and as usual keep the comments coming so we can add more useful features!

Clustering in jBPM v6

Clustering in jBPM v5 was not an easy task, there where several known issues that had to be resolved on client (project that was implementing solution with jBPM) side, to name few:

  • session management – when to load/dispose knowledge session
  • timer management – required to keep knowledge session active to fire timers
This is not the case any more in version 6 where several improvements made their place in code base, for example new module that is responsible for complete session management was introduced – jbpm runtime manager. More on runtime manager in next post, this one focuses on how clustered solution might look like. First of all lets start with all the important pieces jbpm environment consists of:
  1. asset repository – VFS based repository backed with GIT – this is where all the assets are stored during authoring phase
  2. jbpm server that includes JBoss AS7 with deployed jbpm console (bpm focused web application) of kie-wb (fully features web application that combines BPM and BRM worlds)
  3. data base – backend where all the state date is kept (process instances, ksessions, history log, etc)

Repository clustering

Asset repository is GIT backed virtual file system (VFS) that keeps all the assets (process definitions, rules, data model, forms, etc) is reliable and efficient way. Anyone who used to work with GIT understands perfectly how good it is for source management and what else assets are if not source code?
So if that is file system it resides on the same machine as the server that uses it, that enforces it to be kept in sync between all servers of a cluster. For that jbpm makes use of two well know open source projects:
Zookeeper is responsible for gluing all parts together where Helix is cluster management component that registers all cluster details (cluster itself, nodes, resources).
So this two components are utilized by the runtime environment on which jbpm v6 is based on:
  • kie-commons – provides VFS implementation and clustering 
  • uber fire framework – provides backbone of the web applications
So let’s take a look at what we need to do to setup cluster of our VFS:

Get the software

  • download Apache Zookeeper (note that 3.3.4 and 3.3.5 are the only versions that were currently tested so make sure you get the correct version)
  • download Apache Helix  (note that version that was tested was 0.6.1)

Install and configure

  • unzip Apache Zookeeper into desired location – ( from now one we refer to it as zookeeper_home)
  • go to zookeeper_home/conf and make a copy of zoo_sample.conf to zoo.conf
  • edit zoo.conf and adjust settings if needed, these two are important in most of the cases:

# the directory where the snapshot is stored.
dataDir=/tmp/zookeeper
# the port at which the clients will connect
clientPort=2181

  •  unzip Apache helix to into desired location (from now one we refer to it as helix_home)

Setup cluster

Now we have all the software available locally so next step is to configure the cluster itself. We start with start of the Zookeeper server that will be master of the configuration of the cluster:
  • go to zookeeper_home/bin
  • execute following command to start zookeeper server:

sudo ./zkServer.sh start

  • zookeeper server should be started, if the server fails to start make sure that the data directory defined in zoo.conf file exists and is accessible
  • all zookeeper activities can be viewed zookeeper_home/bin/zookeeper.out
To do so, Apache Helix provides utility scripts that can be found in helix_home/bin.
  • go to helix_home/bin
  • create cluster
./helix-admin.sh –zkSvr localhost:2181 –addCluster jbpm-cluster
  • add nodes to the cluster 
node 1
./helix-admin.sh –zkSvr localhost:2181 –addNode jbpm-cluster nodeOne:12345
node2
    ./helix-admin.sh –zkSvr localhost:2181 –addNode jbpm-cluster nodeTwo:12346
add as many nodes as you will have cluster members of jBPM server (in most cases number of application servers in the cluster)
NOTE: nodeOne:12345 is the unique identifier of the node, that will be referenced later on when configuring application severs, although it looks like host and port number it is use to identify uniquely logical node.
  • add resources to the cluster
./helix-admin.sh –zkSvr localhost:2181 
           –addResource jbpm-cluster vfs-repo 1 LeaderStandby AUTO_REBALANCE
  • rebalance cluster to initialize it

./helix-admin.sh –zkSvr localhost:2181 –rebalance jbpm-cluster vfs-repo 2

  • start the Helix controller to manage the cluster
./run-helix-controller.sh –zkSvr localhost:2181 
                        –cluster jbpm-cluster 2>&1 > /tmp/controller.log &
Values given above are just examples and can be changed according to the needs:
cluster name: jbpm-cluster
node name: nodeOne:12345, nodeTwo:12346
resource name: vfs-repo
zkSvr value must match Zookeeper server that is used.

Prepare data base 

Before we start with application server configuration data base needs to be prepared, for this example we use PostgreSQL data base. jBPM server will create all required tables itself by default so there is no big work required for this but some simple tasks must be done before starting the server configuration.

Create data base user and data base

First of all PostgreSQL data base needs to be installed, next user needs to be created on the data base that will own the jbpm schema, in this example we use:
user name: jbpm
password: jbpm
Once the user is ready, data base can be created, and again for the example jbpm is chosen for the data base name.
NOTE: this information (username, password, data base name) will be used later on in application server configuration.

Create Quartz tables

Lastly Quartz related tables must be created, to do so best is to utilize the data base scripts provided with Quartz distribution, jbpm uses Quartz 1.8.5. DB scripts are usually located under QUARTZ_HOME/docs/dbTables.

Create quartz definition file 

Quartz configuration that will be used by the jbpm server needs to accomodate the needs of the environment, as this guide is about to show the basic setup obviously it will not cover all the needs but will allow for further improvements.
Here is a sample configuration used in this setup:
#============================================================================
# Configure Main Scheduler Properties  
#============================================================================

org.quartz.scheduler.instanceName = jBPMClusteredScheduler
org.quartz.scheduler.instanceId = AUTO

#============================================================================
# Configure ThreadPool  
#============================================================================

org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount = 5
org.quartz.threadPool.threadPriority = 5

#============================================================================
# Configure JobStore  
#============================================================================

org.quartz.jobStore.misfireThreshold = 60000

org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreCMT
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
org.quartz.jobStore.useProperties=false
org.quartz.jobStore.dataSource=managedDS
org.quartz.jobStore.nonManagedTXDataSource=notManagedDS
org.quartz.jobStore.tablePrefix=QRTZ_
org.quartz.jobStore.isClustered=true
org.quartz.jobStore.clusterCheckinInterval = 20000

#============================================================================
# Configure Datasources  
#============================================================================
org.quartz.dataSource.managedDS.jndiURL=jboss/datasources/psjbpmDS
org.quartz.dataSource.notManagedDS.jndiURL=jboss/datasources/quartzNotManagedDS

Configure JBoss AS 7 domain

1. Create JDBC driver module – for this example PostgreSQL
a) go to JBOSS_HOME/modules directory (on EAP JBOSS_HOME/modules/system/layers/base)
b) create module folder org/postgresql/main
c) copy postgresql driver jar into the module folder (org/postgresql/main) as postgresql-jdbc.jar          name
d) create module.xml file inside module folder (org/postgresql/main) with following content:
         <module xmlns=”urn:jboss:module:1.0″ name=”org.postgresql”>
         <resources>
           <resource-root path=”postgresql-jdbc.jar”/>
         </resources>

             <dependencies>
      <module name=”javax.api”/>
      <module name=”javax.transaction.api”/>
         </dependencies>
</module>
2. Configure data sources for jbpm server
a) go to JBOSS_HOME/domain/configuration
b) edit domain.xml file
for simplicity sake we use default domain configuration which uses profile “full” that defines two 
        server nodes as part of main-server-group
c) locate the profile “full” inside the domain.xml file and add new data sources
main data source used by jbpm
   <datasource jndi-name=”java:jboss/datasources/psjbpmDS” 
                pool-name=”postgresDS” enabled=”true” use-java-context=”true”>
        <connection-url>jdbc:postgresql://localhost:5432/jbpm</connection-url>
        <driver>postgres</driver>
        <security>
            <user-name>jbpm</user-name>
                <password>jbpm</password>
        </security>
   </datasource>
        
        additional data source for quartz (non managed pool)
        <datasource jta=”false” jndi-name=”java:jboss/datasources/quartzNotManagedDS”   
           pool-name=”quartzNotManagedDS” enabled=”true” use-java-context=”true”>
      <connection-url>jdbc:postgresql://localhost:5432/jbpm</connection-url>
        <driver>postgres</driver>
        <security>
         <user-name>jbpm</user-name>
                <password>jbpm</password>
        </security>
    </datasource>
defined the driver used for the data sources
<driver name=”postgres” module=”org.postgresql”>
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
        
3. Configure security domain 
     a) go to JBOSS_HOME/domain/configuration
     b) edit domain.xml file
for simplicity sake we use default domain configuration which uses profile “full” that defines two
        server nodes as part of main-server-group
      
     c) locate the profile “full” inside the domain.xml file and add new security domain to define security 
         domain for jbpm-console (or kie-wb) – this is just a copy of the “other” security domain defined 
         there by default
    
<security-domain name=”jbpm-console-ng” 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>
        </authentication>
    </security-domain>  
        
for kie-wb application, simply replace jbpm-console-ng with kie-ide as name of the security domain.  
        
4. Configure server nodes
    a) go to JBOSS_HOME/domain/configuration
    b) edit host.xml file
    c) locate servers that belongs to “main-server-group” in host.xml file and add following system  
        properties:
    

property name property value comments
org.uberfire.nio.git.dir /home/jbpm/node[N]/repo location where the VFS asset repository will be stored for the node[N]
org.quartz.properties /jbpm/quartz-definition.properties absolute file path to the quartz definition properties
jboss.node.name nodeOne unique node name within cluster (nodeOne, nodeTwo, etc)
org.uberfire.cluster.id jbpm-cluster name of the helix cluster
org.uberfire.cluster.zk localhost:2181 location of the zookeeper server
org.uberfire.cluster.local.id nodeOne_12345 unique id of the helix cluster node, note that ‘:’ is replaced with ‘_’
org.uberfire.cluster.vfs.lock vfs-repo name of the resource defined on helix cluster
org.uberfire.nio.git.daemon.port 9418 port used by the GIT repo to accept client connections, must be unique for each cluster member
org.uberfire.nio.git.ssh.port 8001 port used by the GIT repo to accept client connections (over ssh), must be unique for each cluster member
org.uberfire.nio.git.daemon.host localhost host used by the GIT repo to accept client connections, in case cluster members run on different machines this property must be set to actual host name instead of localhost otherwise synchronization won’t work
org.uberfire.nio.git.ssh.host localhost host used by the GIT repo to accept client connections (over ssh), in case cluster members run on different machines this property must be set to actual host name instead of localhost otherwise synchronization won’t work
org.uberfire.metadata.index.dir /home/jbpm/node[N]/index location where index for search will be created (maintained by Apache Lucene)
org.uberfire.cluster.autostart false delays VFS clustering until the application is fully initialized to avoid conficts when all cluster members create local clones
    
examples for the two nodes:
    
  •     nodeOne
<system-properties>
  <property name=”org.uberfire.nio.git.dir” value=”/tmp/jbpm/nodeone” 
                                       boot-time=”false”/>
  <property name=”org.quartz.properties” 
      value=”/tmp/jbpm/quartz/quartz-db-postgres.properties” boot-time=”false”/>
  <property name=”jboss.node.name” value=”nodeOne” boot-time=”false”/>
  <property name=”org.uberfire.cluster.id” value=”jbpm-cluster” 
                                           boot-time=”false”/>
    <property name=”org.uberfire.cluster.zk” value=”localhost:2181″ 
                                           boot-time=”false”/>
  <property name=”org.uberfire.cluster.local.id” value=”nodeOne_12345″ 
                                                 boot-time=”false”/>
  <property name=”org.uberfire.cluster.vfs.lock” value=”vfs-repo” 
                                                 boot-time=”false”/>
  <property name=”org.uberfire.nio.git.daemon.port” value=”9418″ boot-time=”false”/>
  <property name=”org.uberfire.metadata.index.dir” value=”/tmp/jbpm/nodeone” boot-time=”false”/>
  <property name=”org.uberfire.cluster.autostart” value=”false” boot-time=”false”/>
</system-properties>
    
  •     nodeTwo
<system-properties>
    <property name=”org.uberfire.nio.git.dir” value=”/tmp/jbpm/nodetwo” 
                                         boot-time=”false”/>
    <property name=”org.quartz.properties” 
       value=”/tmp/jbpm/quartz/quartz-db-postgres.properties” boot-time=”false”/>
    <property name=”jboss.node.name” value=”nodeTwo” boot-time=”false”/>
    <property name=”org.uberfire.cluster.id” value=”jbpm-cluster” 
                                             boot-time=”false”/>
    <property name=”org.uberfire.cluster.zk” value=”localhost:2181″ 
                                             boot-time=”false”/>
    <property name=”org.uberfire.cluster.local.id” value=”nodeTwo_12346″ 
                                                   boot-time=”false”/>
    <property name=”org.uberfire.cluster.vfs.lock” value=”vfs-repo” 
                                                   boot-time=”false”/>
    <property name=”org.uberfire.nio.git.daemon.port” value=”9419″ boot-time=”false”/>
    <property name=”org.uberfire.metadata.index.dir” value=”/tmp/jbpm/nodetwo” boot-
     time=”false”/>
    <property name=”org.uberfire.cluster.autostart” value=”false” boot-time=”false”/>
</system-properties>

NOTE: since this example runs on single node host properties for ssh and git daemons are omitted.

Since repository synchronization is done between git servers make sure that GIT daemons are active (and properly configured – host name and port) on every cluster member.
5. Create user(s) and assign it to proper roles on application server
Add application users
In previous step security domain has been created so jbpm console (or kie-wb) users could be authenticated while logging on. Now it’s time to add some users to be able to logon to the application once it’s deployed. To do so:
 a) go to JBOSS_HOME/bin
 b) execute ./add-user.sh script and follow the instructions on the screen
  – use Application realm not management
  – when asked for roles, make sure you assign at least:
  for jbpm-console: jbpm-console-user
  for kie-wb: kie-user
 
add as many users you need, same goes for roles, listed above are required to be authorized to use the web application. 

Add management (of application server) user
To be able to manage the application server as domain, we need to add administrator user, it’s similar to what was defined for adding application users but the realm needs to be management
 a) go to JBOSS_HOME/bin
 b) execute ./add-user.sh script and follow the instructions on the screen
  – use Management realm not application
Application server should be now ready to be used, so let’s start the domain:
JBOSS_HOME/bin/domain.sh
after few seconds (it’s still empty servers) you should be able to access both server nodes on following locations:
administration console: http://localhost:9990/console
the port offset is configurable in host.xml for given server.

Deploy application – jBPM console (or kie-wb)

Now it’s time to prepare and deploy application, either jbpm-console or kie-wb. As by default both application comes with predefined persistence that uses ExampleDS from AS7 and H2 data base there is a need to alter this configuration to use PostgreSQL data base instead.

Required changes in persistence.xml

  • change jta-data-source name to match one defined on application server

             java:jboss/datasources/psjbpmDS

  • change hibernate dialect to be postgresql 

             org.hibernate.dialect.PostgreSQLDialect

Application build from source

If the application is built from source then you need to edit persistence.xml file that is located under:
jbpm-console-ng/jbpm-console-ng-distribution-wars/src/main/jbossas7/WEB-INF/classes/META-INF/
next rebuild the jbpm-distribution-wars module to prepare deployable package – once that is named: 
jbpm-console-ng-jboss-as7.0.war

    Deployable package downloaded

    In case you have deployable package downloaded (which is already a war file) you need to extract it change the persistence.xml located under:
    WEB-INF/classes/META-INF
    once the file is edited and contains correct values to work properly with PostgreSQL data base application needs to be repackaged:
    NOTE: before repackaging make use that previous war is not in the same directory otherwise it will be packaged into new war too.

    jar -cfm jbpm-console-ng.war META-INF/MANIFEST.MF *

    IMPORTANT: make sure that you include the same manifest file that was in original war file as it contains valuable entires.


    To deploy application logon as management user into administration console of the domain and add new deployments using Runtime view of console. Once the deployment is added to the domain, assign it to the right server group – in this example we used main-server-group it will be default enable this deployment on all servers within that group – meaning deploy it on the servers. This will take a while and after successful deployment you should be able to access jbpm-console (or kie-wb) on following locations:
    the context root (jbpm-console-ng) depends on the name of the war file that was deployed so if the filename will be jbpm-console-ng-jboss7.war then the context root will be jbpm-console-ng-jboss7. Same rule apply to kie-wb deployment.
    And that’s it – you should have fully operational jbpm cluster environment!!!
    Obviously in normal scenarios you would like to hide the complexity of different urls to the application from end users (like putting in front of them a load balancer) but I explicitly left that out of this example to show proper behavior of independent cluster nodes.
    Next post will go into details on how different components play smoothly in cluster, to name few:
    • failover – in case cluster node goes down
    • timer management – how does timer fire in cluster environment
    • session management – auto reactivation of session on demand
    • etc
    As we are still in development mode, please share your thoughts on what would you like to see in cluster support for jBPM, your input is most appreciated!

    Update:
    There was a change in naming of system properties since the article was written so for those that configured it already for 6.0.0.Final there will be a need to adjust name of following system properties:

    • org.kie.nio.git.dir -> org.uberfire.nio.git.dir
    • org.kie.nio.git.daemon.port -> org.uberfire.nio.git.daemon.port
    • org.kie.kieora.index.dir -> org.uberfire.metadata.index.dir
    • org.uberfire.cluster.autostart – new parameter
    Table above already contains proper values for 6.0.0.Final