2012/10/19

Dispose session in CMT environment

Since jBPM5 is flexible process engine it can be deployed in various flavours. One of them is to embed it into you enterprise application running on application server, regardless of its vendor (JBoss, WebSphere, WebLogic, etc).
One option among many others is to make use of it as part of you business logic implemented as EJB. If you choose to use bean managed transaction (BMT) you do not need to take any additional steps as your business logic maintains transaction boundaries. Although when you use container managed transaction (CMT) situation is little bit different as it is container (application server) responsibility to manage transaction.

Before we jump into details what needs to be done for CMT based application, let's mention one important and common for both types (BMT and CMT) practice:

Session must be disposed outside transaction, meaning transaction must be committed/rolledback before session could be disposed.

Obviously this applies to situation when session should be disposed as part of business logic, for instance with session per process instance architecture this could be desired. But not when we have single centralized session.

If session will be disposed before transaction is completed, exception will be thrown on transaction completion, complaining that session is already disposed:

IllegalStateException
("Illegal method call. This session was previously disposed.")

Having this in mind, let's take a look at how this can be done in CMT based implementations. Since we do not control transaction how we could dispose session after transaction is completed?
A simple answer to this is to use dedicated Command that will register transaction synchronization object that will be called on transaction completion so we could safely dispose session.

Here is an example of such command's execute method:
    
public Void execute(Context context) {
       
  final StatefulKnowledgeSession ksession =     

                ((KnowledgeCommandContext)context).getStatefulKnowledgesession();
  try {
      TransactionManager tm = 

      (TransactionManager) new InitialContext().lookup(tmLookupName);
      tm.getTransaction().registerSynchronization(new Synchronization() {
               
          @Override
          public void beforeCompletion() {
              // not used here         
          }
               
          @Override
          public void afterCompletion(int arg0) {
              ksession.dispose();           
          }
      });
  } catch (Exception e) {
      e.printStackTrace();
  }  
       
    return null

}

so, instead of calling default ksession.dispose() method at the end of you business logic, simply call ksession.execute(new CMTDisposeCommand());
That will ensure session is disposed as part of transaction completion.

Here is complete CMT dispose command

2012/10/05

jBPM5 Developer Guide book is on its way!!!

For those that keep an eye on jBPM user forum it won't be any surprise as it was already announced and sometime ago even request for comments was posted. So, I would like to emphasise once again - a brand new book for developers about jBPM5 and Drools by Mauricio Salatino a.k.a. Salaboy is coming.



I had a pleasure to slightly help with this book by reviewing it. I admit this is an excellent reading for those that are new to jBPM5 (and Drools) world as well as to those that are already familiar with it and are planning to put it into mission critical systems. Mauricio provides not only guidelines about the engine but goes beyond that by elaborating about different approaches on how to best utilize these frameworks.

It is much more than title would suggest, it is not only about jBPM5 (but main focus is on the business processes) but it covers topics like:
  • BPMN2 specification
  • Human tasks and WS-HT specification
  • Rule engine (Drools Expert)
  • Complex Event Processing (Drools Fusion)
  • Tooling (jBPM Web Designer, eclipse modeller, etc)
  • Centrailzed repository (Drools Guvnor)
Book is equipped with number of real life examples including source code that allows reader to follow all the content put in every chapter.

In conclusion, this is a book that everyone who wants to use jBPM5 to its full extend should get. I definitely recommend it for  everyone who is interested in jBPM and Drools projects as it provides excellent introduction and much more than that.

Book is scheduled to be available in December 2012 so stay tuned.

Credits
Special thanks go to Maurico Salatino and Esteban Aliverti for this great book. Looking forward to the next one :)

2012/08/06

Simulation in jBPM (draft)

Recently some work has been started to provide simulation capabilities for jBPM. Simulation in many cases means different things to various people so let me start with context information on what simulation means to me and actually what current simulation component is capable of.

Simulation of business process is targeting business analysts that work on designing processes and optimizing them this is not a developer tool. It brings analitics into the picutre so while modelling the process various scenarios could be evaluated to see what is the best option based on current knowledge. In my eyes it is a way of learing the process and better understanding its design and prepare for the consequences a particular process can introduce. For example if we consider goods return process that will take care of products that were bought but for some reason was returned to the store. There are several steps that needs to be performed to analyze what is the reason of return:
  • it is broken
  • it does not meet customer expectations
  • etc
Depending on the reason various decisions could be taken, from rejecting the return, through sending that for further analysis to verify it is broken up to accepting it and returning funds. Following diagram illustrates sample of such process

We can imagine that this process is prepared for heavy sale period which could be Xmas time. Analyst considers that there could be quite some returns due to it was a duplicated/missed gift and is wondering how to prepare its company to deal with it efficiently. With simulation and just few additional information (input data) provided as some sort of forecast on the expected load and available resources (s)he could identify potential bottlenecks in the organization that will prevent it from gathering profit (working efficiently). To name few of these information:
  • probability of taking a given path on the gateway
  • time spent on executing given activity
  • how many people are available to work on user tasks

Once such information are provided a simulated run through this process is executed and result is gathered and presented to the analyst for inspection. Number of runs can be executed with various input data to exercise "what if" scenarios. Alternative sources of information can exist, for instance analyst can make use of real time data collected by business activity monitoring for processes that are already running on production systems.

With this short introduction we can move on to look into how this is realized by jbpm simulation.

First of all jbpm simulation is divided into two components:
  • path finder
  • simulation engine extension

path finder component is responsible for determining all alternative paths in the process to illustrate how a process can be traversed. This is not only informational but as well input for running simulation. Following image shows the sample process with identified alternative paths and one is visualized on the diagram.


simulation engine extension is (as name suggests) an extension to jbpm engine that allows you to run simulations instead of normal process instance executions. Instead of relying on process data like variable it will traverse the process based on identified paths. So that means that path finder component is responsible for providing input to the simulation engine extension component. This at least is the main use case,it could be used as well to alter the path flow in cases of debugging the simulation.

Simulation engine extension provides core of the simulation dedicated to processes but does not run the simulation itself. For that drools- simulator (some details about it can be found here and here) is employed together with its fluent api that is based on paths and steps that can be positioned in time.

A typical use case would look like this:
  • model process definition
  • determine all alternative paths
  • each alternative path will be a path in drools simulatoin fluent
  • define steps for the path (there could be several steps configured for a drools simulator path that in fact represents simulation instance) on a given time distance
  • add SimulateProcessPathCommand for each step
  • run simulation
To see a running example of such simulation take a look at test case that is part of the jbpm-simulation.

Simulation engine extension while executing simulation will generate events for every simulated activity those events will be stored in simulation repository that could have various capabilities. Personally I prefer one that is backed up with stateful knowledge session and can employ complex event processing  and rules to provide meaningful simulation results.

This is just short heads up on the simulation efforts in jbpm so please leave your comments on what would you like to see supported by this component.

Further details about jbpm-simulation components can be found in jbpm wiki (soon).

2012/07/31

Service Task with web service implementation

Invocation of web services as part of business process is common and most likely because of that default implementation of Service Task in BPMN2 specification is web service. Recently (5.4) jBPM5 has gotten support for such activity.

jBPM5 web service support is based on Apache CXF dynamic client. It provides dedicated Service Task handler (that implements WorkItemHandler interface).

org.jbpm.process.workitem.bpmn2.ServiceTaskHandler

Worth noting is that this handler is capable of invoking both web service end points and simple Java based services as with previous ServiceTask handler (org.jbpm.bpmn2.handler.SendTaskHandler) based on the implementation attribute of service task node

web service implementation
 <bpmn2:serviceTask id="ServiceTask_1" name="Service Task" implementation="##WebService" operationRef="_2_ServiceOperation"> </bpmn2:serviceTask>

java implementation
<bpmn2:serviceTask id="_2" name="Hello" operationRef="_2_ServiceOperation" implementation="Other" >
</bpmn2:serviceTask>

ServiceTaskHandler can invoke web service operations in three modes:
  • synchronous (sends request and waits for response before continuing)
  • asynchronous (sends request and uses callback to get response)
  • one way (sends request and does not wait for any response)
This configuration is done on service node level as parameter (data input) so it allows to have different configuration for service nodes and to be handled by the same service task handler.

Let's try to go through this implementation with example. We are going to build a process that will get weather forecast for given zip codes in US. So process will look like this:

This process will:
  • ask for couple of zip codes on the first human task (task is assigned to john)
  • next transform result of the user task to a collection that will be used as input for multi instance service task
  • then based on the input collection process will create several instances of service task to query the weather forecast service
  • once all service task instances are completed it will log result to the console
  • and create another human task to show the weather forecast for selected zip codes (task is assigned to john)
When process instance is started it will prompt the user to select in what mode service task instances should be executed: async or sync. With this particular example changing the mode from async to sync will not make big difference as the service we use is rather fast but with services that takes some time to respond difference will be noticeable.

But how does it know it is web service and even more important what web service it is? This is configured as part of process definition using few dedicated constructs:

1. first of all we need to tell the engine where is our WSDL so it can be read and operations from it can be invoked - this is done with BPMN2 import:
 <import importType="http://schemas.xmlsoap.org/wsdl/" location="http://wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL" namespace="http://ws.cdyne.com/WeatherWS/"/>

2. next message, interface and operations must be defined:
<itemDefinition id="_2-2-4_InMessageType" />
<message id="_2-2-4_InMessage" itemRef="_2-2-4_InMessageType" />

<interface id="_2-2-4_ServiceInterface" name="" implementationRef="Weather">
 
  <operation id="_2-2-4_ServiceOperation"   
       implementationRef="GetCityWeatherByZIP" name="hello">
      <inMessageRef>_2-2-4_InMessage</inMessageRef>
  </operation>
</interface>

Important: make sure that implementationRef for both interface and operations point to valid service and operation in WSDL.

3. Next use defined operation in your service task and set implementation as web service (or don't specify that attribute at all so default will be taken):
<serviceTask id="_2" name="Service Task" operationRef="_2-2-4_ServiceOperation" implementation="##WebService" >
........
</serviceTask>

NOTE: Unfortunately tooling does not support this yet so the bpmn2 file needs to be edited by hand. Soon tooling will provide this as well.

Yet another important thing here is that if you plan to use request or response object of the service in your process as variables make sure that all of them implement java.io.Serializable interface so they can be properly persisted. One way to do this (used in the example) is to provide additional configuration to tell JAXB to add Serializable while generating classes from WSDL and generate classes as part of the build:

Complete source code can be found here. It comes with test cases that uses this example as well as local service that can be used to illustrate difference between sync and async modes.

This example can be executed on jbpm-console when build from master, as it already has this service task handler configured. Here is a short guide on how to do it:
1. clone jbpm master and build it with mvn clean install -DskipTests -Dfull (alternatively download latest build from build server)
2. clone jbpm-examples and build jbpm-ws-example project with mvn clean install
3. copy result of build in point 2 (jbpm-ws-sample-1.0-SNAPSHOT.jar) into jbpm-installer/dependencies
4. copy WeatherWSServiceProcess.bpmn2 into jbpm-installer/sample/evaluation/src/main/resource
5. copy all archives from jbpm-distribution into jbpm-installer/lib
6. use jbpm-installer to install jbpm into jboss AS7 - ant install.demo.noeclipse
7. start demo server - ant start.demo.noeclipse

then go to jbpm-console and run the process with name WeatherWSServiceProcess.

Have fun!

2012/07/30

JUDCon2012 - Boston

JUDCon 2012 in Boston was a great place to meet with fellow developers and discuss about future of jBPM. I had a pleasure to give a talk about experimental project that I have been working on for quite some time, but unfortunately not enough time was spent on it. Anyway, I gave a introduction to the project that I use to call jbpm enterprise.



The goal of this project is to provide comprehensive BPM platform on top of jBPM and Drools projects to leverage the most of them in the enterprise (Java EE) environment. So what it does?
  • First of all it bundles jbpm and drools (together with all dependencies) into JBoss Module. 
  • Next it provides very tiny layer that abstracts knowledge api and provides simplified interfaces to interact with execution engine (execution engine is knowledge base with sessions enclosed by an component with additional characteristics - more in presentation)
  • exposes some services via OSGi service repository
  • provides maven archetypes to build your components that utilize the platform over OSGi service registry
    • bundle archetype that is dedicated to put you process/rules/events logic in
    • web application archetype that makes use of the platform (starts, signal processes, etc)

More details can be found in the presentation from the JUDCon2012 conference.

If some one would like to give it a test drive please find a downloadable artefacts and short guide here.

Have fun and as usual comments are welcome.

In this case your feedback is even more important to see if that is something that community expects.

2012/06/01

Self managable user tasks - notification and reassignment

As a continuation of the first post, let's try to make use of LDAP configuration to make actors aware of the tasks awaiting their attention.
Human task service is capable of reacting on certain events such as task was not started or task was not completed in time. Currently there are two options a process designer can choose from:
  • remind the user about the task
  • reassign the task to another actor/group
Depending on the needs either one of them or both can be configured on a user task activity, moreover designers are not limited to single instances of those events, for instance user task can be modelled as follows:
  1. as soon as task is created send notification to the actor assigned to it
  2. if there is no action within a day, send a reminder to the actor
  3. if there is no action within two days, reassign the task to another actor
  4. if the task is not completed within a week send notification to a manager
This is illustrated on following screen cast, starting at designing a process with user task, configuring deadlines (reassignment and notifications), building and running the process.

1. first let's design the process and define deadlines


2. now it is time to build the package and execute process


Task service supports four types of events:
  • reassign if not started
  • reassign if not completed
  • notify if not started
  • notify if not completed
To give some flexibility, expression that reference process and task variables are supported, for instance when modelling notification, users and/or groups can point to a process variables to get a list of users/groups that should be notified. In addition, notification subject and body can reference both process and task variables and provides additional variables that could be useful when referring to a task:
  • processInstanceId
  • processSessionId
  • workItemId
  • taskId
  • owners
 and all task variables are available as Map in
  • doc
Process variables are accessed with #{variable} and task variables are accessed with ${variable}, simple notification could look like this:

Hello,

A task with id ${taskId} was assigned to you. You can access it in your personal <a href="http://localhost:8080/jbpm-console/app.html#errai_ToolSet_Tasks;Group_Tasks.3">inbox</a>.

Regards
jBPM

Although HTML notifications are supported it is recommended to make use of process variables and some services to provide email templates instead of putting them inline within process definition, the bpmn2 file. Both subject and body of the notification can be declared as process variable.

but how to configure it?

Note: This guide assumes that human task service is deployed as web application, if that is not the case please refer to online documentation.

There are two elements that needs to be provided to make human task capable of performing deadline actions:
  1. configure user info component that delivers information required by notification mechanism
  2. configure email service
And of course declare deadline requirements on the user task in your process.

Previous post showed how to configure LDAP user info component to utilize external service as user information provider (Quick recap - it simple requires to put the right class name in web.xml init param section - user.info.class and LDAP configuration property file). As this is rather common to use LDAP in such cases there is a way to add custom implementations as well so you are not limited to that.

Configuring email service is done by providing drools.email.conf property file that contains smtp configuration and place it inside META-INF directory of jbpm-human-task-war/WEB-INF/classes.

from = sender-email-address (required)
replyTo = reply-to-email-address (optional)
host = smtp-host-name (required)
port = smtp-port-number (required)
defaultLanguage = en-UK
user=username-if-authentication-enabled
password=password-if-authentication-enabled

NOTE: there could be a need of prefixing file name with additional drools. to be found properly due to bug. So file name should be drools.drools.email.conf; this will be fixed in 5.4.

With this, many uses cases can be covered as shown in the example but most likely not all, so if there are any scenarios you find yourself in and think it might be useful to others please let us know about it:)

2012/05/14

jBPM 5.3 brings LDAP into the picture

jBPM engine itself does not require to have knowledge about users and groups but to build more complete platform based on it sooner or later users and their memberships will be needed. Prior to version 5.3, jBPM relied on basic (and demo only) setup based on some property files. With 5.3 you can make use of integration that allow to employ existing LDAP server.

So, let's start digging into it :)

User and group information are relevant to two components:
  • jbpm console
  • human task server
jbpm console need to know about users and their roles to properly authenticate and grant them with correct access in the console.
Human task server has bit more to do with users and groups. First of all it requires it when assigning task to entities (either user or group). Next, in case notification mechanism is configured it requires to fetch more information about the entity (such as email address, etc.)

Bit of heads up is always welcome, but how this can be configured and used? Firstly, we need to have a LDAP server that could be used as user repository. If you have already one this step can be omitted.

Install and configure LDAP server


Install and configure LDAP server of your choice, I personally use OpenLDAP that can be downloaded and used freely for evaluation purpose. Regardless of your choice most likely the best guide on installation and configuration is to be found on the server home page.

Note: make sure that when configuring your LDAP server inetOrgPerson schema is included otherwise import of example ldif will fail.

Once the server is up and running it's time to load it with some information that will be used later on by jBPM. Following is a sample setup of users and groups that matches the one used in previous versions of jBPM5 (Example ldif file expect that there is already domain configured (dc=jbpm,dc=org)):

Sample LDIF file

Rest of the post assumes that LDAP server is installed on the same machine as application server that hosts jbpm (but it is not limited to that).

Configure JBoss AS7 security domain to use LDAP


Next step is to configure application server that host jbpm console to authenticate users using LDAP instead of the default property file based security domain. In fact there are no changes needed to jbpm console itself but only to JBoss AS7 configuration.
To use LDAP, jbpm-console security domain inside standalone.xml file should be replaced with:
 <security-domain name="jbpm-console">
      <authentication>
         <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required">
             <module-option name="baseCtxDN" value="ou=People,dc=jbpm,dc=org"/>
             <module-option name="baseFilter" value="(uid={0})"/>
             <module-option name="rolesCtxDN" value="ou=Roles,dc=jbpm,dc=org"/>
             <module-option name="roleFilter" value="(member=uid={0},ou=People,dc=jbpm,dc=org)"/>
             <module-option name="roleAttributeID" value="cn"/>
             <module-option name="allowEmptyPasswords" value="true"/>
         </login-module>
     </authentication>
 </security-domain>
This is pure JBoss configuration so in case of more advanced setup is required please visit JBoss AS7 documentation.

Note that from jBPM 5.3 jbpm console is capable of using any security domain that JBoss AS supports with just configuring it properly on application server so it is not limited to LDAP.

Configure Human task server to use LDAP


Finally it is time to look into the details of human task server configuration to make it use of LDAP as user repository. Those that are following jBPM development are already familiar with UserGroupCallback interface that is responsible for providing user and group/role information to the task server. So naturally LDAP integration is done through implementation of that interface.
Similar to configuring application server, ldap callback needs to be configured (with property file for instance). Here is a sample file that corresponds to the configuration used throughout the post:

ldap.user.ctx=ou\=People,dc\=jbpm,dc\=org
ldap.role.ctx=ou\=Roles,dc\=jbpm,dc\=org
ldap.user.roles.ctx=ou\=Roles,dc\=jbpm,dc\=org
ldap.user.filter=(uid\={0})
ldap.role.filter=(cn\={0})
ldap.user.roles.filter=(member\={0})

As from 5.3 by default human task server is deployed as web application on Jboss AS7. With this, user can simply adjust configuration of the human task server by editing its web.xml file. And this is how LDAP callback is registered.

<init-param>
     <param-name>user.group.callback.class</param-name>
     <param-value>org.jbpm.task.service.LDAPUserGroupCallbackImpl</param-value>
</init-param>

Next put the jbpm.usergroup.callback.properties on the root of the classpath inside jbpm-human-task.war web application and your LDAP callback will be ready to rock!

In addition, when using deadlines on your tasks together with notification, there is one more step to configure so user information (for instance email address) could be retrieved from LDAP server. UserInfo interface is dedicated to providing this sort of information to the deadline handler and thus it's implementation needs to registered as well.
Similar as user group callback was registered it can be done via web.xml of human task web application:

<init-param>
     <param-name>user.info.class</param-name>
     <param-value>org.jbpm.task.service.LDAPUserInfoImpl</param-value>
</init-param>

It requires to be configured as well and it could be done via property file that should be named jbpm.user.info.properties and be placed on root of the class path.
As it shares most of the properties with callback configuration, in many cases users could use single file that contains all required values and instruct both implementation where to find this file with system properties:

-Djbpm.user.info.properties=classpath-location-and-file-name
-Djbpm.usergroup.callback.properties=classpath-location-and-file-name

With all that jBPM will now utilize your LDAP server for users and groups information whenever it needs them.

P.S.
This post is more of introduction to the LDAP integration rather than complete and comprehensive guide as it touches on high level all the components involved. More detailed information about configuring particular pieces can be found in jBPM documentation for 5.3 release.

Any comments are more than welcome.