jBPM User Guide

This chapter will give an overview of the various components that are offered as part of the jBPM project. It will walk through the different phases in the life cycle of a business process, from modeling and deployment to execution and monitoring.

1.1. Modeling

jBPM currently allows users to create and modify business processes using graphical flow charts. We target both developers and business users, using an Eclipse editors and a web-based editor respectively. Currently, we offer three options to model your BPMN2 processes.

1.1.1. Drools Flow Eclipse Plugin for creating BPMN2 processes

This Eclipse plugin allows developers to create, test and debug BPMN2 processes.

Figure 1.1. The Drools Flow editor for creating BPMN2 processes

1.1.2. jBPM5 Eclipse Plugin for creating BPMN2 processes

This new Eclipse plugin is being created to support the full BPMN2 specification. It is currently still under development and only supports a limited number of constructs and attributes, but can already be used to create simple BPMN2 processes.

Figure 1.2. The jBPM editor for creating BPMN2 processes

1.1.3. Web-based process modeling using Oryx Designer

Web-based editing is possible using the Oryx Designer. This designer is also integrated into Guvnor, the knowledge repository where you can store your processes. The Designer can be used to view, update or create BPMN2 processes.

Figure 1.3. The web-based Oryx editor for creating BPMN2 processes

1.3. Execution

1.3.1. Process engine

The core engine is a lightweight workflow engine in Java:

• native BPMN2 process execution
• pluggable persistence and transactions
• audit and history logging
• based on a generic process engine

We do yet implement all node types and attributes as defined in the BPMN 2.0 specification, but we already support a very significant subset, which includes all common node types. The following list gives an overview of the various elements that can already be executed using the BPMN 2.0 XML format:

• Flow objects
  • Events
    • Start Event (None, Conditional, Signal, Message, Timer)
    • End Event (None, Terminate, Error, Escalation, Signal, Message, Compensation)
    • Intermediate Catch Event (Signal, Timer, Conditional, Message)
    • Intermediate Throw Event (None, Signal, Escalation, Message, Compensation)
    • Non-interrupting Boundary Event (Escalation, Timer)
    • Interrupting Boundary Event (Escalation, Error, Timer, Compensation)
  • Activities
    • Script Task (Java or MVEL expression language)
    • Task
    • Service Task
    • User Task
    • Business Rule Task
    • Manual Task
    • Send Task
    • Receive Task
    • Reusable Sub-Process (Call Activity)
    • Embedded Sub-Process
    • Ad-Hoc Sub-Process
    • Data-Object
  • Gateways
    • Diverging
      • Exclusive (Java, MVEL or XPath expression language)
      • Inclusive (Java, MVEL or XPath expression language)
      • Parallel
      • Event-Based
    • Converging
      • Exclusive
      • Parallel
  • Lanes
• Data
  • Java type language
  • Process properties
  • Embedded Sub-Process properties
  • Activity properties
• Connecting objects
  • Sequence flow

1.3.2. Human task service

Human tasks are an important part of a BPM solution. While some of the work performed in a process can be executed automatically, some tasks need to be executed with the interaction of human actors. This includes task lists for users, claiming and/or assigning tasks, etc. The process engine itself is not tied to one specific, internal implementation but allows for other implementations to be plugged in. By default jBPM currently supports a WS-HT service as the default implementation. The life cycle as supported by the Human Task specification is shown below. Note that the WS-HT service also includes features like group assignment, escalation, assignment rules, etc.

Figure 1.4. The WS-HT human task life cycle

User-defined human task forms are also supported using a template-based approach, while a other task form solutions can easily be integrated.

1.4. Monitoring

To monitoring your processes, you first need the ability to know what happening at runtime. Process listeners can be used to listen to different kinds of events occuring at runtime, like process instances being started or node instances being completed, etc. This information could then be used to create history logs (for reporting or static analysis purposes), or to dymanically analyze and respond using Business Activity Monitoring (BAM).

1.4.1. Web-based management console

Processes can be managed through a web console. This includes features like managing your process instances (starting/stopping/inspecting), ...

Figure 1.5. Managing your process instances

... inspecting your (human) task list and executing those tasks, ...

Figure 1.6. Managing your tasks

... and generating reports.

Figure 1.7. Generating reports

This guide will assist you in installing and running a demo setup of the various components of the jBPM project. If you have any feedback on how to improve this guide, if you encounter problems, or if you want to help out, do not hesitate to contact the jBPM community as described in the "What to do if I encounter problems or have questions?" section.

ant install.demo

ant start.demo

ant stop.demo

To interact with the process engine (to for example start a process), you need to set up a session. This session will be used to communicate with the process engine. A session also needs to have a reference to a knowledge base. This knowledge base is used to look up the process definitions whenever necessary. Whenever a process is started, a new process instance is created (for that process definition) that maintains the state of that specific instance of the process.

For example, image you are writing an application to process sales orders. You could then define one or more process definitions that define how the order should be processed. When starting up your application, you first need to create a knowledge base that contains those process definitions. You can then create a session based on this knowledge base so that, whenever a new sales order then comes in, a new process instance is started for that sales order.

A knowledge base can be shared across sessions and usually is only created once, at the start of the application (as creating a knowledge base can be rather heavy-weight as it involves parsing and compiling the process definitions). Knowledge bases can be dynamically changed (so you can add or remove processes at runtime).

Sessions can be created based on a knowledge base and are used to execute processes and interact with the engine. You can create as much independent session as you want and creating a session is considered relatively lightweight. How much sessions you create is up to you, but in general you could for example create one session and direct all calls in your application to that one session. You could decide to create multiple sessions if for example you want to have multiple independent processing units (for example, you want all processes from one customer be completely independent of processes of another customer so you could create an independent session for each customer), or if you need multiple sessions for scalability reasons. If you don't know what to do, simply start by having one knowledge base that contains all your process definitions and one create session that you then use to execute all your processes.

4.1. The jBPM API

The project has a clear separation between the API the users should be interacting with and the actual implementation classes. The public API exposes most of the features we believe "normal" users can safely use and should remain rather stable across releases. Expert users can still access internal classes but should be aware that they should know what they are doing and that internal API might still change in the future.

As explained above, the jBPM API should thus be used to (1) create a knowledge base that contains your process definitions, and to (2) create a session to start new process instances, signal existing ones, register listeners, etc.

4.1.1. Knowledge Base

The jBPM API allows you to first create a knowledge base. This knowledge base should include all your process definitions that might need to be executed. The following code snippet shows how to create a knowledge base consisting of only one process definition (using a knowledge builder, in this case to add a resource from the classpath).

KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();

kbuilder.add(ResourceFactory.newClassPathResource("MyProcess.bpmn"), ResourceType.BPMN2);

KnowledgeBase kbase = kbuilder.newKnowledgeBase();

4.1.2. Session

Next, you should create a session to interact with the engine. The following code snippet shows how easy it is to create a session based on the earlier created knowledge base, and to start a process (by id).

StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();

ProcessInstance processInstance = ksession.startProcess("com.sample.MyProcess");

The ProcessRuntime interface defines all the session methods for interacting with processes, as shown below.

    /**

     * Start a new process instance.  The process (definition) that should

     * be used is referenced by the given process id.

     * 

     * @param processId  The id of the process that should be started

     * @return the ProcessInstance that represents the instance of the process that was started

     */

    ProcessInstance startProcess(String processId);


    /**

     * Start a new process instance.  The process (definition) that should

     * be used is referenced by the given process id.  Parameters can be passed

     * to the process instance (as name-value pairs), and these will be set

     * as variables of the process instance. 

     * 

     * @param processId  the id of the process that should be started

     * @param parameters  the process variables that should be set when starting the process instance 

     * @return the ProcessInstance that represents the instance of the process that was started

     */

    ProcessInstance startProcess(String processId,

                                 Map<String, Object> parameters);


    /**

     * Signals the engine that an event has occurred. The type parameter defines

     * which type of event and the event parameter can contain additional information

     * related to the event.  All process instances that are listening to this type

     * of (external) event will be notified.  For performance reasons, this type of event

     * signaling should only be used if one process instance should be able to notify

     * other process instances. For internal event within one process instance, use the

     * signalEvent method that also include the processInstanceId of the process instance

     * in question. 

     * 

     * @param type the type of event

     * @param event the data associated with this event

     */

    void signalEvent(String type,

                     Object event);


    /**

     * Signals the process instance that an event has occurred. The type parameter defines

     * which type of event and the event parameter can contain additional information

     * related to the event.  All node instances inside the given process instance that

     * are listening to this type of (internal) event will be notified.  Note that the event

     * will only be processed inside the given process instance.  All other process instances

     * waiting for this type of event will not be notified.

     * 

     * @param type the type of event

     * @param event the data associated with this event

     * @param processInstanceId the id of the process instance that should be signaled

     */

    void signalEvent(String type,

                     Object event,

                     long processInstanceId);


    /**

     * Returns a collection of currently active process instances.  Note that only process

     * instances that are currently loaded and active inside the engine will be returned.

     * When using persistence, it is likely not all running process instances will be loaded

     * as their state will be stored persistently.  It is recommended not to use this

     * method to collect information about the state of your process instances but to use

     * a history log for that purpose.

     * 

     * @return a collection of process instances currently active in the session

     */

    Collection<ProcessInstance> getProcessInstances();


    /**

     * Returns the process instance with the given id.  Note that only active process instances

     * will be returned.  If a process instance has been completed already, this method will return

     * null.

     * 

     * @param id the id of the process instance

     * @return the process instance with the given id or null if it cannot be found

     */

    ProcessInstance getProcessInstance(long processInstanceId);


    /**

     * Aborts the process instance with the given id.  If the process instance has been completed

     * (or aborted), or the process instance cannot be found, this method will throw an

     * IllegalArgumentException.

     * 

     * @param id the id of the process instance

     */

    void abortProcessInstance(long processInstanceId);


    /**

     * Returns the WorkItemManager related to this session.  This can be used to

     * register new WorkItemHandlers or to complete (or abort) WorkItems.

     * 

     * @return the WorkItemManager related to this session

     */

    WorkItemManager getWorkItemManager();

4.1.3. Events

The session provides methods for registering and removing listeners. A ProcessEventListener can be used to listen to process-related events, like starting or completing a process, entering and leaving a node, etc. Below, the different methods of the ProcessEventListener class are shown. An event object provides access to related information, like the process instance and node instance linked to the event.

public interface ProcessEventListener {


  void beforeProcessStarted( ProcessStartedEvent event );

  void afterProcessStarted( ProcessStartedEvent event );

  void beforeProcessCompleted( ProcessCompletedEvent event );

  void afterProcessCompleted( ProcessCompletedEvent event );

  void beforeNodeTriggered( ProcessNodeTriggeredEvent event );

  void afterNodeTriggered( ProcessNodeTriggeredEvent event );

  void beforeNodeLeft( ProcessNodeLeftEvent event );

  void afterNodeLeft( ProcessNodeLeftEvent event );


}

An audit log can be created based on the information provided by these process listeners. We provide various default logger implementations:

1. Console logger: This logger writes out all the events to the console.

2. File logger: This logger writes out all the events to a file using an XML representation. This log file might then be used in the IDE to generate a tree-based visualization of the events that occurred during execution.

3. Threaded file logger: Because a file logger writes the events to disk only when closing the logger or when the number of events in the logger reaches a predefined level, it cannot be used when debugging processes at runtime. A threaded file logger writes the events to a file after a specified time interval, making it possible to use the logger to visualize the progress in realtime, while debugging processes.

The KnowledgeRuntimeLoggerFactory lets you add a logger to your session, as shown below. When creating a console logger, the knowledge session for which the logger needs to be created must be passed as an argument. The file logger also requires the name of the log file to be created, and the threaded file logger requires the interval (in milliseconds) after which the events should be saved.

KnowledgeRuntimeLogger logger =

    KnowledgeRuntimeLoggerFactory.newFileLogger( ksession, "test" );

// add invocations to the process engine here,

// e.g. ksession.startProcess(processId);

...

logger.close();

The log file can be opened in Eclipse, using the Audit View in the Drools Eclipse plugin, where the events are visualized as a tree. Events that occur between the before and after event are shown as children of that event. The following screenshot shows a simple example, where a process is started, resulting in the activation of the Start node, an Action node and an End node, after which the process was completed.

An important aspect of work flow and BPM is human task management. While some of the work performed in a process can be executed automatically, some tasks need to be executed with the interaction of human actors. jBPM supports the use of human tasks inside processes using a special user task node that will represent this interaction. This node allows process designers to define the type of task, the actor(s), the data associated with the task, etc. We also have implemented a task service that can be used to manage these user tasks. Users are however open to integrate any other solution if they want to, as this is fully pluggable.

To start using human tasks inside your processes, you first need to (1) include user task nodes inside your process, (2) integrate a task management component of your choice (e.g. the WS-HT implementation provided by us) and (3) have end users interact with the human task management component using some kind of user interface. These elements will be discussed in more detail in the next sections.

5.1. Human tasks inside processes

jBPM supports the use of human tasks inside processes using a special user task node (as shown in the figure above). A user task node represents an atomic task that needs to be executed by a human actor. Although jBPM has a special user task node for including human tasks inside a process, human tasks are simply considered as any other kind of external service that needs to be invoked and are therefore simply implemented as a special kind of work item. The only thing that is special about the user task node is that we have added support for swimlanes, making it easier to assign tasks to users (see below). A user task node contains the following properties:

• Id: The id of the node (which is unique within one node container).
• Name: The display name of the node.
• TaskName: The name of the human task.
• Priority: An integer indicating the priority of the human task.
• Comment: A comment associated with the human task.
• ActorId: The actor id that is responsible for executing the human task. A list of actor id's can be specified using a comma (',') as separator.
• Skippable: Specifies whether the human task can be skipped (i.e. the actor decides not to execute the human task).
• Content: The data associated with this task.
• Swimlane: The swimlane this human task node is part of. Swimlanes make it easy to assign multiple human tasks to the same actor. See below for more detail on how to use swimlanes.
• Wait for completion: If this property is true, the human task node will only continue if the human task has been terminated (i.e. completed or any other terminal state); otherwise it will continue immediately after creating the human task.
• On-entry and on-exit actions: Actions that are executed upon entry and exit of this node.
• Parameter mapping: Allows copying the value of process variables to parameters of the human task. Upon creation of the human tasks, the values will be copied.
• Result mapping: Allows copying the value of result parameters of the human task to a process variable. Upon completion of the human task, the values will be copied. Note that can only use result mappings when "Wait for completion" is set to true. A human task has a result variable "Result" that contains the data returned by the human actor. The variable "ActorId" contains the id of the actor that actually executed the task.
• Timers: Timers that are linked to this node (see the 'timers' section for more details).
• ParentId: Allows to specify the parent task id, in the case that this task is a sub task of another. (see the 'sub task' section for more details)

You can edit these variables in the properties view (see below) when selecting the user task node, or the most important properties can also be edited by double-clicking the user task node, after which a custom user task node editor is opened, as shown below as well.

Note that you could either specify the values of the different parameters (actorId, priority, content, etc.) directly (in which case they will be the same for each execution of this process), or make them context-specific, based on the data inside the process instance. For example, parameters of type String can use #{expression} to embed a value in the String. The value will be retrieved when creating the work item and the #{...} will be replaced by the toString() value of the variable. The expression could simply be the name of a variable (in which case it will be resolved to the value of the variable), but more advanced MVEL expressions are possible as well, like #{person.name.firstname}. For example, when sending an email, the body of the email could contain something like "Dear #{customer.name}, ...". For other types of variables, it is possible to map the value of a variable to a parameter using the parameter mapping.

5.1.1. Swimlanes

User task nodes can be used in combination with swimlanes to assign multiple human tasks to the similar actors. Tasks in the same swimlane will be assigned to the same actor. Whenever the first task in a swimlane is created, and that task has an actorId specified, that actorId will be assigned to the swimlane as well. All other tasks that will be created in that swimlane will use that actorId as well, even if an actorId has been specified for the task as well.

Whenever a human task that is part of a swimlane is completed, the actorId of that swimlane is set to the actorId that executed that human task. This allows for example to assign a human task to a group of users, and to assign future tasks of that swimlame to the user that claimed the first task. This will also automatically change the assignment of tasks if at some point one of the tasks is reassigned to another user.

To add a human task to a swimlane, simply specify the name of the swimlane as the value of the "Swimlane" parameter of the user task node. A process must also define all the swimlanes that it contains. To do so, open the process properties by clicking on the background of the process and click on the "Swimlanes" property. You can add new swimlanes there.

5.2. Human task management component

As far as the jBPM engine is concerned, human tasks are similar to any other external service that needs to be invoked and are implemented as an extension of normal work items. As a result, the process itself only contains an abstract description of the human tasks that need to be executed, and a work item handler is responsible for binding this abstract tasks to a specific implementation. Using our pluggable work item handler approach (see the chapter on domain-specific processes for more details), users can plug in any back-end implementation.

We do however provide an implementation of such a human task management component based on the WS-HumanTask specification. If you do not have the requirement to integrate a specific human task component yourself, you can use this service. It manages the task life cycle of the tasks (creation, claiming, completion, etc.) and stores the state of the task persistently. It also supports features like internationalization, calendar integration, different types of assignments, delegation, deadlines, etc.

Because we did not want to implement a custom solution when a standard is available, we chose to implement our service based on the WS-HumanTask (WS-HT) specification. This specification defines in detail the model of the tasks, the life cycle, and a lot of other features as the ones mentioned above. It is pretty comprehensive and can be found here.

5.2.1. Task life cycle

Looking from the perspective of the process, whenever a user task node is triggered during the execution of a process instance, a human task is created. The process will only continue from that point when that human task has been completed or aborted (unless of course you specify that the process does not need to wait for the human task to complete, by setting the "Wait for completion" property to true). However, the human task usually has a separate life cycle itself. We will now shortly introduce this life cycle, as shown in the figure below. For more details, check out the WS-HumanTask specification.

Whenever a task is created, it starts in the "Created" stage. It usually automatically transfers to the "Ready" state, at which point the task will show up on the task list of all the actors that are allowed to execute the task. There, it is waiting for one of these actors to claim the task, indicating that he or she will be executing the task. Once a user has claimed a task, the status is changed to "Reserved". Note that a task that only has one potential actor will automatically be assigned to that actor upon creation of that task. After claiming the task, that user can then at some point decide to start executing the task, in which case the task status is changed to "InProgress". Finally, once the task has been performed, the user must complete the task (and can specify the result data related to the task), in which case the status is changed to "Completed". If the task could not be completed, the user can also indicate this using a fault response (possibly with fault data associated), in which case the status is changed to "Failed".

The life cycle explained above is the normal life cycle. The service also allows a lot of other life cycle methods, like:

• Delegating or forwarding a task, in which case it is assigned to another actor
• Revoking a task, so it is no longer claimed by one specific actor but reappears on the task list of all potential actors
• Temporarly suspending and resuming a task
• Stopping a task in progress
• Skipping a task (if the task has been marked as skippable), in which case the task will not be executed

5.2.2. Linking the task component to the jBPM engine

The task management component needs to be integrated with the jBPM engine just like any other external service, by registering a work item handler that is responsible for translating the abstract work item (in this case a human task) to a specific invocation. We have implemented such a work item handler (org.jbpm.process.workitem.wsht.WSHumanTaskHandler in the jbpm-human-task module) so you can easily link this work item handler like this:

StatefulKnowledgeSession ksession = ...;

ksession.getWorkItemManager().registerWorkItemHandler("Human Task", new WSHumanTaskHandler());

By default, this handler will connect to the human task management component on the local machine on port 9123, but you can easily change that by invoking the setConnection(ipAddress, port) method on the WSHumanTaskHandler.

If you are using persistence for the session (check out the chapter on persistence for more information), you should use the org.jbpm.process.workitem.wsht.CommandBasedWSHumanTaskHandler as that makes sure that the state of the process instances is persisted correctly after interacting with the process engine.

The communication between the human task service and the process engine, or any task client, is done using messages being sent between the client and the server. The implementation allows different transport mechanisms being plugged in, but by default, Mina (http://mina.apache.org/) is used for client/server communication. An alternative implementation using HornetQ is also available.

A task client offers the following methods for managing the life cycle of human tasks:

public void start( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void stop( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void release( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void suspend( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void resume( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void skip( long taskId, String userId, TaskOperationResponseHandler responseHandler )

public void delegate( long taskId, String userId, String targetUserId,

                      TaskOperationResponseHandler responseHandler )

public void complete( long taskId, String userId, ContentData outputData,

                      TaskOperationResponseHandler responseHandler )

...

You can either use these methods directly, or probably use some kind of GUI that the end user will use to lookup and execute the tasks that are assigned to them. If you take a look a the method signatures you will notice that almost all of this method takes the following arguments:

• taskId: The id of the task that we are working with. This is usually extract from the currently selected task in the user task list in the user interface.

• userId: The id of the user that is executing the action. This is usually the id of the user that is logged in into the application.

• responseHandler: Communication with the task service is usually asynchronous, so you should use a response handler that will be notified when the results are available.

As you can imagine all the methods create a message that will be sent to the server, and the server will execute the logic that implements the correct action.

5.2.3. Starting the Task Management Component

The task management component is a completely independent service that the process engine communicates with. We therefore recommend to start it as a separate service as well. The installer contains a command to start the task server (in this case using Mina as transport protocol), or you can use the following code fragment:

EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.task");

TaskService taskService = new TaskService(emf, SystemEventListenerFactory.getSystemEventListener());

MinaTaskServer server = new MinaTaskServer( taskService );

Thread thread = new Thread( server );

thread.start();

The task management component uses the Java Persistence API (JPA) to store all task information in a persistent manner. To configure the persistence, you need to modify the persistence.xml configuration file accordingly. We refer to the JPA documentation on how to do that. The following fragment shows for example how to use the task management component with hibernate and an in-memory H2 database:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<persistence

    version="1.0"

    xsi:schemaLocation=

      "http://java.sun.com/xml/ns/persistence

       http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd

       http://java.sun.com/xml/ns/persistence/orm

       http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"

    xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xmlns="http://java.sun.com/xml/ns/persistence">



  <persistence-unit name="org.drools.task">

    <provider>org.hibernate.ejb.HibernatePersistence</provider>

    <class>org.jbpm.task.Attachment</class>

    <class>org.jbpm.task.Content</class>

    <class>org.jbpm.task.BooleanExpression</class>

    <class>org.jbpm.task.Comment</class>

    <class>org.jbpm.task.Deadline</class>

    <class>org.jbpm.task.Comment</class>

    <class>org.jbpm.task.Deadline</class>

    <class>org.jbpm.task.Delegation</class>

    <class>org.jbpm.task.Escalation</class>

    <class>org.jbpm.task.Group</class>

    <class>org.jbpm.task.I18NText</class>

    <class>org.jbpm.task.Notification</class>

    <class>org.jbpm.task.EmailNotification</class>

    <class>org.jbpm.task.EmailNotificationHeader</class>

    <class>org.jbpm.task.PeopleAssignments</class>

    <class>org.jbpm.task.Reassignment</class>

    <class>org.jbpm.task.Status</class>

    <class>org.jbpm.task.Task</class>

    <class>org.jbpm.task.TaskData</class>

    <class>org.jbpm.task.SubTasksStrategy</class>

    <class>org.jbpm.task.OnParentAbortAllSubTasksEndStrategy</class>

    <class>org.jbpm.task.OnAllSubTasksEndParentEndStrategy</class>

    <class>org.jbpm.task.User</class>



    <properties>

      <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>

      <property name="hibernate.connection.driver_class" value="org.h2.Driver"/>

      <property name="hibernate.connection.url" value="jdbc:h2:mem:mydb" />

      <property name="hibernate.connection.username" value="sa"/>

      <property name="hibernate.connection.password" value="sasa"/>

      <property name="hibernate.connection.autocommit" value="false" />

      <property name="hibernate.max_fetch_depth" value="3"/>

      <property name="hibernate.hbm2ddl.auto" value="create" />

      <property name="hibernate.show_sql" value="true" />

    </properties>

  </persistence-unit>

</persistence>

The first time you start the task management component, you need to make sure that all the necessary users and groups are added to the database. Our implementation requires all users and groups to be predefined before trying to assign a task to that user or group. So you need to make sure you add the necessary users and group to the database using the taskSession.addUser(user) and taskSession.addGroup(group) methods. Note that you at least need an "Administrator" user as all tasks are automatically assigned to this user as the administrator role.

The jbpm-human-task module contains a org.jbpm.task.RunTaskService class in the src/test/java source folder that can be used to start a task server. It automatically adds users and groups as defined in LoadUsers.mvel and LoadGroups.mvel configuration files.

5.2.4. Interacting With the Task Management Component

The task management component exposes various methods to manage the life cycle of the tasks through a Java API. This allows clients to integrate (at a low level) with the task management component. Note that end users should probably not interact with this low-level API directly but rather use one of the task list clients (see below). These clients interact with the task management component using this API. The following code sample shows how to create a task client and interact with the task service to create, start and complete a task.

TaskClient client = new TaskClient(new MinaTaskClientConnector("client 1",

    new MinaTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));

client.connect("127.0.0.1", 9123);


// adding a task

BlockingAddTaskResponseHandler addTaskResponseHandler = new BlockingAddTaskResponseHandler();

Task task = ...;

client.addTask( task, null, addTaskResponseHandler );

long taskId = addTaskResponseHandler.getTaskId();

        

// getting tasks for user "bobba"

BlockingTaskSummaryResponseHandler taskSummaryResponseHandler =

    new BlockingTaskSummaryResponseHandler();

client.getTasksAssignedAsPotentialOwner("bobba", "en-UK", taskSummaryResponseHandler);

List<TaskSummary> tasks = taskSummaryResponseHandler.getResults();


// starting a task

BlockingTaskOperationResponseHandler responseHandler =

    new BlockingTaskOperationResponseHandler();

client.start( taskId, "bobba", responseHandler );  


// completing a task

responseHandler = new BlockingTaskOperationResponseHandler();

client.complete( taskId, users.get( "bobba" ).getId(), null, responseHandler );

5.3. Human Task Management Interface

5.3.1. Eclipse integration

The Drools IDE contains a org.drools.eclipse.task plugin that allows you to test and/or debug processes using human tasks. In contains a Human Task View that can connect to a running task management component, request the relevant tasks for a particular user (i.e. the tasks where the user is either a potential owner or the tasks that the user already claimed and is executing). The life cycle of these tasks can then be executed, i.e. claiming or releasing a task, starting or stopping the execution of a task, completing a task, etc. A screenshot of this Human Task View is shown below. You can configure which task management component to connect to in the Drools Task preference page (select Window -> Preferences and select Drools Task). Here you can specify the url and port (default = 127.0.0.1:9123).

5.3.2. Web-based Task View

The jBPM console also contains a task view for looking up task lists and managing the life cycle of tasks. See the chapter on the jBPM console for more information.

jBPM allows the persistent storage of certain information, i.e., the process runtime state, the history information, etc.

// create the entity manager factory and register it in the environment

EntityManagerFactory emf =

    Persistence.createEntityManagerFactory( "org.jbpm.persistence.jpa" );

Environment env = KnowledgeBaseFactory.newEnvironment();

env.set( EnvironmentName.ENTITY_MANAGER_FACTORY, emf );


// create a new knowledge session that uses JPA to store the runtime state

StatefulKnowledgeSession ksession =

    JPAKnowledgeService.newStatefulKnowledgeSession( kbase, null, env );

int sessionId = ksession.getId();


// invoke methods on your method here

ksession.startProcess( "MyProcess" );

ksession.dispose();

// recreate the session from database using the sessionId

ksession = JPAKnowledgeService.loadStatefulKnowledgeSession( sessionId, kbase, null, env );

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<persistence

  version="1.0"

  xsi:schemaLocation=

    "http://java.sun.com/xml/ns/persistence

     http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd

     http://java.sun.com/xml/ns/persistence/orm

     http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"

  xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xmlns="http://java.sun.com/xml/ns/persistence">



  <persistence-unit name="org.jbpm.persistence.jpa">

    <provider>org.hibernate.ejb.HibernatePersistence</provider>

    <jta-data-source>jdbc/processInstanceDS</jta-data-source>

    <class>org.drools.persistence.session.SessionInfo</class>

    <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class>

    <class>org.jbpm.persistence.processinstance.WorkItemInfo</class>



    <properties>

      <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>

      <property name="hibernate.max_fetch_depth" value="3"/>

      <property name="hibernate.hbm2ddl.auto" value="update"/>

      <property name="hibernate.show_sql" value="true"/>

      <property name="hibernate.transaction.manager_lookup_class"

                value="org.hibernate.transaction.BTMTransactionManagerLookup"/>

    </properties>

  </persistence-unit>

</persistence>

PoolingDataSource ds = new PoolingDataSource();

ds.setUniqueName("jdbc/testDS1");

ds.setClassName("org.h2.jdbcx.JdbcDataSource");

ds.setMaxPoolSize(3);

ds.setAllowLocalTransactions(true);

ds.getDriverProperties().put("user", "sa");

ds.getDriverProperties().put("password", "sasa");

ds.getDriverProperties().put("URL", "jdbc:h2:file:/NotBackedUp/data/process-instance-db");

ds.init();

<?xml version="1.0" encoding="UTF-8"?>

<datasources>

  <local-tx-datasource>

    <jndi-name>jdbc/testDS1</jndi-name>

    <connection-url>jdbc:h2:file:/NotBackedUp/data/process-instance-db</connection-url>

    <driver-class>org.h2.jdbcx.JdbcDataSource</driver-class>

    <user-name>sa</user-name>

    <password>sasa</password>

  </local-tx-datasource>

</datasources>

// create the entity manager factory and register it in the environment

EntityManagerFactory emf =

    Persistence.createEntityManagerFactory( "org.jbpm.persistence.jpa" );

Environment env = KnowledgeBaseFactory.newEnvironment();

env.set( EnvironmentName.ENTITY_MANAGER_FACTORY, emf );

env.set( EnvironmentName.TRANSACTION_MANAGER,

         TransactionManagerServices.getTransactionManager() );


// create a new knowledge session that uses JPA to store the runtime state

StatefulKnowledgeSession ksession =

    JPAKnowledgeService.newStatefulKnowledgeSession( kbase, null, env );


// start the transaction

UserTransaction ut =

  (UserTransaction) new InitialContext().lookup( "java:comp/UserTransaction" );

ut.begin();


// perform multiple commands inside one transaction

ksession.insert( new Person( "John Doe" ) );

ksession.startProcess( "MyProcess" );


// commit the transaction

ut.commit();

7.3. History Log

In many cases it is useful (if not necessary) to store information about the execution of process instances, so that this information can be used afterwards, for example, to verify what actions have been executed for a particular process instance, or to monitor and analyze the efficiency of a particular process. Storing history information in the runtime database is usually not a good idea, as this would result in ever-growing runtime data, and monitoring and analysis queries might influence the performance of your runtime engine. That is why history information about the execution of process instances is stored separately.

This history log of execution information is created based on the events generated by the process engine during execution. The Drools runtime engine provides a generic mechanism to listen to different kinds of events. The necessary information can easily be extracted from these events and made persistent, for example in a database. Filters can be used to only store the information you find relevant.

7.3.1. Storing Process Events in a Database

The jbpm-bam module contains an event listener that stores process-related information in a database using JPA or Hibernate directly. The database contains two tables, one for process instance information and one for node instance information (see the figure below):

1. ProcessInstanceLog: This lists the process instance id, the process (definition) id, the start date and (if applicable) the end date of all process instances.
2. NodeInstanceLog: This table contains more detailed information about which nodes were actually executed inside each process instance. Whenever a node instance is entered from one of its incomming connections or is exited through one of its outgoing connections, that information is stored in this table. For this, it stores the process instance id and the process id of the process instance it is being executed in, and the node instance id and the corresponding node id (in the process definition) of the node instance in question. Finally, the type of event (0 = enter, 1 = exit) and the date of the event is stored as well.

To log process history information in a database like this, you need to register the logger on your session (or working memory) like this:

StatefulKnowledgeSession ksession = ...;

JPAWorkingMemoryDbLogger logger = new JPAWorkingMemoryDbLogger(ksession);


// invoke methods one your session here


logger.dispose();

Note that this logger is like any other audit logger, which means that you can add one or more filters by calling the method addFilter to ensure that only relevant information is stored in the database. Only information accepted by all your filters will appear in the database. You should dispose the logger when it is no longer needed.

To specify the database where the information should be stored, modify the file persistence.xml file to include the audit log classes as well (ProcessInstanceLog, NodeInstanceLog and VariableInstanceLog), as shown below.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<persistence

  version="1.0"

  xsi:schemaLocation=

    "http://java.sun.com/xml/ns/persistence

     http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd

     http://java.sun.com/xml/ns/persistence/orm

     http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"

  xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xmlns="http://java.sun.com/xml/ns/persistence">



  <persistence-unit name="org.jbpm.persistence.jpa">

    <provider>org.hibernate.ejb.HibernatePersistence</provider>

    <jta-data-source>jdbc/processInstanceDS</jta-data-source>

    <class>org.drools.persistence.session.SessionInfo</class>

    <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class>

    <class>org.jbpm.persistence.processinstance.WorkItemInfo</class>

    <class>org.jbpm.process.audit.ProcessInstanceLog</class>

    <class>org.jbpm.process.audit.NodeInstanceLog</class>

    <class>org.jbpm.process.audit.VariableInstanceLog</class>



    <properties>

      <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>

      <property name="hibernate.max_fetch_depth" value="3"/>

      <property name="hibernate.hbm2ddl.auto" value="update"/>

      <property name="hibernate.show_sql" value="true"/>

      <property name="hibernate.transaction.manager_lookup_class"

                value="org.hibernate.transaction.BTMTransactionManagerLookup"/>

    </properties>

  </persistence-unit>

</persistence>

All this information can easily be queried and used in a lot of different use cases, ranging from creating a history log for one specific process instance to analyzing the performance of all instances of a specific process.

This audit log should only be considered a default implementation. We don't know what information you need to store for analysis afterwards, and for performance reasons it is recommended to only store the relevant data. Depending on your use cases, you might define your own data model for storing the information you need, and use the process event listeners to extract that information.

Business processes can be managed through a web console. This includes features like managing your process instances (starting/stopping/inspecting), inspecting your (human) task list and executing those tasks, and generating reports.

The jBPM console consists of two wars that must be deployed in your application server and contains the necessary libraries, the actual application, etc. One jar contains the server application, the other one the client.

8.2. Running the process management console

Now navigate to the following URL (replace the host and/or port depending on how the application server is configured): http://localhost:8080/jbpm-console

A login screen should pop up, asking for your user name and password. By default, the following username/password configurations are supported: krisv/krisv, admin/admin, john/john and mary/mary.

After filling these in, the process management workbench should be opened, as shown in the screenshot below. On the right you will see several tabs, related to process instance management, human task lists and reporting, as explained in the following sections.

8.2.1. Managing process instances

The "Processes" section allows you to inspect the process definitions that are currently part of the installed knowledge base, start new process instances and manage running process instances (which includes inspecting their state and data).

8.2.1.1. Inspecting process definitions

When you open the process definition list, all known process definitions are shown. You can then either inspect process instances for one specific process or start a new process instance.

8.2.1.2. Starting new process instances

To start a new process instance for one specific process definition, select the process definition in the process definition list. Click on the "Start" button in the instances table to start a new instance of that specific process. When a form is associated with this particular process (to ask for additional information before starting the process), this form will be shown. After completing this form, the process will be started with the provided information.

8.2.1.3. Managing process instances

The process instances table shows all running instances of that specific process definition. Select a process instance to show the details of that specific process instance.

8.2.1.4. Inspecting process instance state

You can inspect the state of a specific process instance by clicking on the "Diagram" button. This will show you the process flow chart, where a red traingle is shown at each node that is currently active (like for example a human task node waiting for the task to be completed or a join node waiting for more incoming connections before continuing). [Note that multiple instances of one node could be executing simultaneously. They will still be shown using only one red triangle.]

8.2.1.5. Inspecting process instance variables

You can inspect the (top-level) variables of a specific process instance by clicking on the "Instance Data" button. This will show you how each variable defined in the process maps to it's corresponding value for that specific process instance.

8.2.2. Human task lists

The task management section allows a user to see his/her current task list. The group task list shows all the tasks that are not yet assigned to one specific user but that the currently logged in user could claim. The personal task list shows all tasks that are assigned to the currently logged in user. To execute a task, select it in your personal task list and select "View". If a form is associated with the selected task (for example to ask for additional information), this form will be shown. After completing the form, the task will also be completed.

8.2.3. Reporting

The reporting section allows you to view reports about the execution of processes. This includes an overall report showing an overview of all processes, as shown below.

A report regarding one specific process instance can also be generated.

jBPM provides some sample reports that could be used to visualize some generic execution characteristics like the number of active process instances per process etc. But custom reports could be generated to show the information your company thinks is important, by replacing the report templates in the report directory.

<html>

<body>

<h2>Start Performance Evaluation</h2>

<hr>

<form action="complete" method="POST" enctype="multipart/form-data">

Please fill in your username: <input type="text" name="employee" /></BR>

<input type="submit" value="Complete">

</form>

</body>

</html>

<html>

<body>

<h2>Employee evaluation</h2>

<hr>

${task.descriptions[0].text}<br/>

<br/>

Please fill in the following evaluation form: 

<form action="complete" method="POST" enctype="multipart/form-data">

Rate the overall performance: <select name="performance">

<option value="outstanding">Outstanding</option>

<option value="exceeding">Exceeding expectations</option>

<option value="acceptable">Acceptable</option>

<option value="below">Below average</option>

</select><br/>

<br/>

Check any that apply:<br/>

<input type="checkbox" name="initiative" value="initiative">Displaying initiative<br/>

<input type="checkbox" name="change" value="change">Thriving on change<br/>

<input type="checkbox" name="communication" value="communication">Good communication skills<br/>

<br/>

<input type="submit" value="Complete">

</form>

</body>

</html>