jBPM Developers Guide

Typically, process definitions are static. A process definition is composed of activities and transitions. The runtime behaviour of a activity is encapsulated in a so called Activity and it's decoupled from the process graph structure.

The Process Virtual Machine doesn't contain any such activity implementations. It only provides the execution environment and an activity API to write Activity implementations as Java components. Activities can also be wait states. This means that the activity control flow goes outside the process system. For example a human task or invoking an service asynchronously.

Many executions can be started for one process definition. An execution is a pointer that keeps track of the current activity.

To represent concurrent paths of execution, there is a hierarchical parent-child relation between so that one process instance can cope with concurrent paths of execution.

ClientProcessDefinition processDefinition = ProcessFactory.build("loan")
  .activity("submit loan request").initial().behaviour(AutomaticActivity.class)
    .transition().to("evaluate")
  .activity("evaluate").behaviour(WaitState.class)
    .transition("approve").to("wire money")
    .transition("reject").to("end")
  .activity("wire money").behaviour(AutomaticActivity.class)
    .transition().to("archive")
  .activity("archive").behaviour(WaitState.class)
    .transition().to("end")
  .activity("end").behaviour(WaitState.class)
.done();

The ProcessFactory is a helper class that provides convenience for building an object graph that represents a process definition. AutomaticActivity is a pass-through activity without anything happening and WaitState will wait until an external signal is given. Both activity implementations will be covered in more depth later.

The processDefinition object serves as a factory for process instance objects. A process instance represents one execution of the process definition. More precise, the process instance is the main path of execution.

ClientExecution execution = processDefinition.startProcessInstance();

A process instance itself is also an Execution. Potentially, an execution can have child executions to represent concurrent paths of execution.

The execution can be seen as a state machine that operates as described in the process definition. Starting a process instance means that the initial activity of the process definition is executed. Since this is an automatic activity, the execution will proceed to the evaluate activity. The evaluate activity is a wait state. When the execution arrived at the evaluate activity, the method startProcessInstance will return and waits until an external signal is provided with the signal method. So after the startProcessInstance we can verify if the execution is positioned in the evaluate activity.

assertEquals("evaluate", execution.getActivityName());

To make the process execute further, we provide an external trigger with the signal method. The result of the evaluation will be given as the signalName parameter like this:

execution.signal("approve");

The WaitState activity implementation will take the transition that corresponds to the given signalName. So the execution will first execute the automatic activity wire money and then return after entering the next wait state archive.

assertEquals("archive", execution.getActivityName());

When the execution is waiting in the archive activity, the default signal will make it take the first unnamed transition.

execution.signal();
assertEquals("end", execution.getActivityName());

The process has executed in the thread of the client. The startProcessInstance method only returned when the evaluate activity was reached. In other words, the ClientProcessDefinition.startProcessInstance and ClientExecution.signal methods are blocking until the next wait state is reached.

<jbpm-configuration xmlns="http://jbpm.org/xsd/cfg">

  <process-engine-context>
  
    <deployer-manager>
      <assign-file-type>
        <file extension=".jpdl.xml" type="jpdl" />
      </assign-file-type>
      <parse-jpdl />
      <check-process />
      <check-problems />
      <save />
    </deployer-manager>
    
    <process-service />
    <execution-service />
    <management-service />
  
    <command-service>
      <retry-interceptor />
      <environment-interceptor />
      <standard-transaction-interceptor />
    </command-service>
    
    <hibernate-configuration>
      <properties resource="hibernate.properties" />
      <mapping resource="jbpm.pvm.typedefs.hbm.xml" />
      <mapping resource="jbpm.pvm.wire.hbm.xml" />
      <mapping resource="jbpm.pvm.definition.hbm.xml" />
      <mapping resource="jbpm.pvm.execution.hbm.xml" />
      <mapping resource="jbpm.pvm.variable.hbm.xml" />
      <mapping resource="jbpm.pvm.job.hbm.xml" />
      <mapping resource="jbpm.jpdl.hbm.xml" />
      <cache-configuration resource="jbpm.pvm.cache.xml" 
                           usage="nonstrict-read-write" />
    </hibernate-configuration>
    
    <hibernate-session-factory />
    
    <id-generator />
    <types resource="jbpm.pvm.types.xml" />
    <job-executor auto-start="false" />
  
  </process-engine-context>

  <transaction-context>
    <hibernate-session />
    <transaction />
    <pvm-db-session />
    <job-db-session />
    <message-session />
  </transaction-context>

</jbpm-configuration>

And next to it a hibernate.properties like this

hibernate.dialect                      org.hibernate.dialect.HSQLDialect
hibernate.connection.driver_class      org.hsqldb.jdbcDriver
hibernate.connection.url               jdbc:hsqldb:mem:.
hibernate.connection.username          sa
hibernate.connection.password
hibernate.hbm2ddl.auto                 create-drop
hibernate.cache.use_second_level_cache true
hibernate.cache.provider_class         org.hibernate.cache.HashtableCacheProvider
# hibernate.show_sql                     true
hibernate.format_sql                   true
hibernate.use_sql_comments             true

Then you can obtain the services from the environment factory like this:

EnvironmentFactory environmentFactory = new PvmEnvironmentFactory("environment.cfg.xml");

ProcessService processService = environmentFactory.get(ProcessService.class);
ExecutionService executionService = environmentFactory.get(ExecutionService.class);
ManagementService managementService = environmentFactory.get(ManagementService.class);

The responsibility of the ProcessService is to manage the repository of process definitions. Before we can start a process execution, the process definition needs to be deployed into the process repository. Process definitions can be supplied in various formats and process definition languages. A deployment collects process definition information from various sources like a ZIP file, an XML file or a process definition object. The method ProcessService.deploy will take a deployment through all the deployers that are configured in the configuration file.

In this example, we'll supply a process definition programmatically for deployment.

ClientProcessDefinition processDefinition = ProcessFactory.build("loan")
  .activity("submit loan request").initial().behaviour(AutomaticActivity.class)
    .transition().to("evaluate")
  .activity("evaluate").behaviour(WaitState.class)
    .transition("approve").to("wire money")
    .transition("reject").to("end")
  .activity("wire money").behaviour(AutomaticActivity.class)
    .transition().to("archive")
  .activity("archive").behaviour(WaitState.class)
    .transition().to("end")
  .activity("end").behaviour(WaitState.class)
.done();

Deployment deployment = new Deployment(processDefinition);
processService.deploy(deployment);

Now, a version of that process definition is stored in the database. The check-version deployer will have assigned version 1 to the stored process definition. The create-id deployer will have distilled id loan:1 from the process name and the assigned version.

Deploying that process again will lead to a new process definition version being created in the database. But an incremented version number will be assigned. For the purpose of versioning, process definitions are considered equal if they have the same name.

It is recommended that a user provided key reference is supplied for all process executions. Starting a new process execution goes like this:

Execution execution = executionService.startExecution("loan:1", "request7836");

The return value is an execution interface, which prevents navigation of relations. That is because outside of the service methods, the transaction and hibernate session is not guaranteed to still be open. In fact, the default configuration as given above will only keep the transaction and session open for the duration of the service method. So navigating the relations outside of the service methods might result into a hibernate LazyInitializationException. But the current activity name can still be verified:

assertEquals("evaluate", execution.getActivityName());

Also very important is the generated id that can be obtained. The default id-generator will use the process definition id and the given key to make a unique id for the process execution like this:

assertEquals("loan:1/request7836", execution.getId());

That id must be when providing the subsequent external triggers to the process execution like this:

executionService.signalExecution("loan:1/request7836", "approve");

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

<!DOCTYPE hibernate-configuration PUBLIC
          "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
          "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>
  <session-factory>

    <property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property>
    <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
    <property name="hibernate.connection.url">jdbc:hsqldb:mem:.</property>
    <property name="hibernate.connection.username">sa</property>
    <property name="hibernate.connection.password"></property>
    <property name="hibernate.hbm2ddl.auto">create</property>
    <property name="hibernate.show_sql">true"</property>
    <property name="hibernate.format_sql">true"</property>
    <property name="hibernate.use_sql_comments">true"</property>
    
    <mapping resource="Loan.hbm.xml"/>
    
  </session-factory>
</hibernate-configuration>

And a

<?xml version="1.0"?<

<!DOCTYPE hibernate-mapping PUBLIC 
          "-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
          "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"<

<hibernate-mapping package="org.jbpm.pvm.api.db.embedded" default-access="field"<

  <typedef name="execution" class="org.jbpm.pvm.internal.hibernate.ExecutionType" /<

  <class name="Loan" table="LOAN"<

    <id name="dbid"<
      <generator class="sequence"/<
    </id<

    <property name="execution" type="execution" /<
    <property name="customer" /<
    <property name="amount" /<
    
  </class<

</hibernate-mapping<

Then you can use the Loan class like this in a test

Configuration configuration = new Configuration();
configuration.configure();
SessionFactory sessionFactory = configuration.buildSessionFactory();

// start a session/transaction
Session session = sessionFactory.openSession();
Transaction transaction = session.beginTransaction();

Loan loan = new Loan("john doe", 234.0);
session.save(loan);
assertEquals("evaluate", loan.getState());

// start a new session/transaction
transaction.commit();
session.close();
session = sessionFactory.openSession();
transaction = session.beginTransaction();

loan = (Loan) session.get(Loan.class, loan.getDbid());
assertEquals("evaluate", loan.getState());
loan.approve();
assertEquals("archive", loan.getState());

// start a new session/transaction
transaction.commit();
session.close();

After executing this code snippet, this is the loan record in the DB:

The services interfaces should be used from application code that wants to interact with the Process Virtual Machine which runs in transactional persistent mode, backed by a database. This is the most typical way how users interact with the PVM as a workflow engine.

To execute processes without persistence, the client API can be used to work with process and execution objects directly. The client API expose the methods of the core model objects.

The activity API is used to implement the runtime behaviour of activities. So a activity type is in fact a component with at the core an implementation of the Activity interface. Activity implementations can control the flow of execution.

The event listener API serves to write pieces of Java code that should be executed upon process events. It's very similar to the activity API with that exception that event listeners are not able to control the flow of execution.

The retry interceptor is the first in the chain and that one that will be exposed as the CommandService.class from the environment. So the retry interceptor will be given to the respective services process-service, execution-service and management-service.

The retry-interceptor will catch hibernate StaleObjectExceptions (indicating optimistic locking failures) and retry to execute the command.

The environment-interceptor will put an environment block around the execution of the command.

The standard-transaction-interceptor will initialize a StandardTransaction. The hibernate session/transaction will be enlisted as a resource with this standard transaction.

Different configurations of this interceptor stack will also enable to

ClientProcessDefinition processDefinition = ProcessFactory.build()
    .activity("a").initial().behaviour(new Display("hello"))
      .transition().to("b")
    .activity("b").behaviour(new Display("world"))
.done();

Now we can execute this process as follows:

Execution execution = processDefinition.startExecution();

The invocation of startExecution will print hello world to the console:

hello
world

One thing already worth noticing is that activities can be configured with properties. In the Display example, you can see that the message property is configured differently in the two usages. With configuration properties it becomes possible to write reusable activities. They can then be configured differently each time they are used in a process. That is an essential part of how process languages can be build on top of the Process Virtual Machine.

The other part that needs explanation is that this activity implementation does not contain any instructions for the propagation of the execution. When a new process instance is started, the execution is positioned in the initial activity and that activity is executed. The method Display.execute makes use of what is called implicit propagation of execution. Concretely this means that the activity itself does not invoke any of the methods on the execution to propagate it. In that case implicit propagation kicks in. Implicit propagation will take the first transition if there is one. If not, it will end the execution. This explains why both activities a and b are executed and that the execution stops after activity b is executed.

ClientProcessDefinition processDefinition = ProcessFactory.build()
    .activity("a").initial().behaviour(new WaitState())
      .transition().to("b")
    .activity("b").behaviour(new WaitState())
.done();

Let's start a new process instance for this process definition:

ClientExecution execution = processDefinition.startProcessInstance();

Starting this process will execute the WaitState activity in activity a. WaitState.execute will invoke ActivityExecution.waitForSignal. So when the processDefinition.startProcessInstance() returns, the execution will still be positioned in activity a.

assertEquals("a", execution.getActivityName());

Then we provide the external trigger by calling the signal method.

execution.signal();

The execution.signal() will delegate to the activity of the current activity. So in this case that is the WaitState activity in activity a. The WaitState.signal will invoke the ActivityExecution.take(String transitionName). Since we didn't supply a signalName, the first transition with name null will be taken. The only transition we specified out of activity a didn't get a name so that one will be taken. And that transition points to activity b. When the execution arrives in activity b, the WaitState in activity b is executed. Similar as we saw above, the execution will wait in activity b and this time the signal method will return, leaving the execution positioned in activity b.

assertEquals("b", execution.getActivityName());

Now, the execution is at an interesting point. There are two transitions out of the state evaluate. One transition is called approve and one transition is called reject. As we explained above, the WaitState implementation will take the transition that corresponds to the signal that is given. Let's feed in the 'approve' signal like this:

execution.signal("approve");

The approve signal will cause the execution to take the approve transition and it will arrive in the activity wire money.

In activity wire money, the message will be printed to the console. Since, the Display activity didn't invoke the execution.waitForSignal(), nor any of the other execution propagation methods, the implicit proceed behaviour will just make the execution continue over the outgoing transition to activity archive, which is again a WaitState.

So only when the archive wait state is reached, the signal("approve") returns.

Another signal like this:

execution.signal("approve");

will bring the execution eventually in the end state.

ClientProcessDefinition processDefinition = ProcessFactory.build()
  .activity("a").initial().behaviour(new AutomaticActivity())
    .event("end")
      .listener(new PrintLn("leaving a"))
      .listener(new PrintLn("second message while leaving a"))
    .transition().to("b")
      .listener(new PrintLn("taking transition"))
  .activity("b").behaviour(new WaitState())
    .event("start")
      .listener(new PrintLn("entering b"))
.done();

The first event shows how to register multiple listeners to the same event. They will be notified in the order as they are specified.

Then, on the transition, there is only one type of event. So in that case, the event type must not be specified and the listeners can be added directly on the transition.

A listeners will be called each time an execution fires the event to which the listener is subscribed. The execution will be provided in the activity interface as a parameter and can be used by listeners except for the methods that control the propagation of execution.

TODO update code snippet

Next we'll start an execution.

ClientExecution execution = processDefinition.startProcessInstance();

After starting a new execution, the execution will be in activity a as that is the initial activity. No activities have been left so no message is logged. Next a signal will be given to the execution, causing it to take the transition from a to b.

execution.signal();

When the signal method returns, the execution will have taken the transition and the end event will be fired on activity a. That event will be propagated to the composite activity and to the process definition. Since our DisplaySource event listener is placed on the composite activity, it will receive the event and print the following message on the console:

leaving activity(a)

Another

execution.signal();

will take the transition from b to c. That will fire two activity-leave events. One on activity b and one on activity composite. So the following lines will be appended to the console output:

leaving activity(b)
leaving activity(composite)

Event propagation is build on the hierarchical composition structure of the process definition. The top level element is always the process definition. The process definition contains a list of activities. Each activity can be a leaf activity or it can be a composite activity, which means that it contains a list of nested activities. Nested activities can be used for e.g. super states or composite activities in nested process languages like BPEL.

So the even model also works similarly for composite activities as it did for the process definition above. Suppose that 'Phase one' models a super state as in state machines. Then event propagation allows to subscribe to all events within that super state. The idea is that the hierarchical composition corresponds to diagram representation. If an element 'e' is drawn inside another element 'p', then p is the parent of e. A process definition has a set of top level activities. Every activity can have a set of nested activities. The parent of a transition is considered as the first common parent for it's source and destination.

If an event listener is not interested in propagated events, propagation can be disabled with propagationDisabled() while building the process with the ProcessFactory. The next process is the same process as above except that propagated events will be disabled on the event listener. The graph diagram remains the same.

Building the process with the process factory:

TODO update code snippet

So when the first signal is given for this process, again the end event will be fired on activity a, but now the event listener on the composite activity will not be executed cause propagated events have been disabled. Disabling propagation is a property on the individual event listener and doesn't influence the other listeners. The event will always be fired and propagated over the whole parent hierarchy.

ClientExecution execution = processDefinition.startProcessInstance();

The first signal will take the process from a to b. No messages will be printed to the console.

execution.signal();

Next, the second signal will take the transition from b to c.

execution.signal()

Again two end events are fired just like above on activities b and composite respectively. The first event is the end event on activity b. That will be propagated to the composite activity. So the event listener will not be executed for this event cause it has propagation disabled. But the event listener will be executed for the end event on the composite activity. That is not propagated, but fired directly on the composite activity. So the event listener will now be executed only once for the composite activity as shown in the following console output:

leaving activity(composite)

Here's how to build the process:

ClientProcessDefinition processDefinition = ProcessFactory.build("automatic")
    .activity("wait 1").initial().behaviour(new WaitState())
      .transition().to("automatic 1")
    .activity("automatic 1").behaviour(new Display("one"))
      .transition().to("wait 2")
    .activity("wait 2").behaviour(new WaitState())
      .transition().to("automatic 2")
    .activity("automatic 2").behaviour(new Display("two"))
      .transition().to("automatic 3")
    .activity("automatic 3").behaviour(new Display("three"))
      .transition().to("automatic 4")
    .activity("automatic 4").behaviour(new Display("four"))
      .transition().to("wait 3")
    .activity("wait 3").behaviour(new WaitState())
.done();

Let's walk you through one execution of this process.

ClientExecution execution = processDefinition.startProcessInstance();

Starting a new execution means that the initial activity is executed. So if an automatic activity is the initial activity, this means that immediately the first unnamed outgoing transition is taken. This happens all inside of the invocation of startProcessInstance.

In this case however, the initial activity is a wait state. So the method startProcessInstance returns immediately and the execution will be positioned in the initial activity 'wait 1'.

Then an external trigger is given with the signal method.

execution.signal();

Then the execution is now waiting for an external trigger just as an object (more precisely an object graph) in memory until the next external trigger is given with the signal method.

execution.signal();

This second invocation of signal will take the execution similarly all the way to wait 3 before it returns.

In most situations, the computational work that needs to be done as part of the process after an external trigger (the red pieces) is pretty minimal. Typically transactions combining the process execution and processing the request from the UI takes typically less then a second. Whereas the wait state in business processes typically can span for hours, days or even years. The clue is to clearly distinct when a wait state starts so that only the computational work done before the start of that wait state should be included in the transaction.

Think of it this way: "When an approval arrives, what are all the automated processing that needs to be done before the process system needs to wait for another external trigger?" Unless pdf's need to be generated or mass emails need to be send, the amount of time that this takes is usually neglectable. That is why in the default persistent execution mode, the process work is executed in the thread of the client.

This reasoning even holds in case of concurrent paths of execution. When a single path of execution splits into concurrent paths of execution, the process overhead of calculating that is neglectable. So that is why it makes sense for a fork or split activity implementation that targets persistent execution mode to spawn the concurrent paths sequentially in the same thread. Basically it's all just computational work as part of the same transaction. This can only be done because the fork/split knows that each concurrent path of execution will return whenever a wait state is encountered.

Since this is a difficult concept to grasp, I'll explain it again with other words. Look at it from the overhead that is produced by the process execution itself in persistent execution mode. If in a transaction, an execution is given an external trigger and that causes the execution to split into multiple concurrent paths of execution. Then the process overhead of calculating this is neglectable. Also the overhead of the generated SQL is neglectable. And since all the work done in the concurrent branches must be done inside that single transaction, there is typically no point in having fork/split implementations spawn the concurrent paths of execution in multiple threads.

To make executable processes, developers need to know exactly what the automatic activities are, what the wait states are and which threads will be allocated to the process execution. For business analysts that draw the analysis process, things are a bit simpler. For the activities they draw, they usually know whether it's a human or a system that is responsible. But they typically don't not how this translates to threads and transactions.

So for the developer, the first job is to analyse what needs to be executed within the thread of control of the process and what is outside. Looking for the external triggers can be a good start to find the wait states in a process, just like verbs and nouns can be the rule of thumb in building UML class diagrams.

To establish multiple concurrent paths of execution, activity implementations like a fork or split can create child executions with method ActivityExecution.createExecution. Activity implementations like join or merge can stop these concurrent paths of execution by calling method stop on the concurrent execution.

Only leaf executions can be active. Non-leave executions should be inactive. This tree structure of executions doesn't enforce a particular type of concurrency or join behaviour. It's up to the forks or and-splits and to the joins or and-merges to use the execution tree structure in any way they want to define the wanted concurrency behaviour. Here you see an example of concurrent executions.

There is a billing and a shipping path of execution. In this case, the flat bar activities represent activities that fork and join. The execution shows a three executions. The main path of execution is inactive (represented as gray) and the billing and shipping paths of execution are active and point to the activity bill and ship respectively.

It's up to the activity behaviour implementations how they want to use this execution structure. Suppose that multiple tasks have to be completed before the execution is to proceed. The activity behaviour can spawn a series of child executions for this. Or alternatively, the task component could support task groups that are associated to one single execution. In that case, the task component becomes responsible for synchronizing the tasks, thereby moving this responsibility outside the scope of the execution tree structure.

If an execution is locked, methods that change the execution will throw a PvmException and the message will reference the actual locking state. Firing events, updating variables, updating priority and adding comments are not considered to change an execution. Also creation and removal of child executions are unchecked, which means that those methods can be invoked by external API clients and activity behaviour methods, even while the execution is in a locked state.

Make sure that comparisons between getState() and the STATE_* constants are done with .equals and not with '==' because if executions are loaded from persistent storage, a new string is created instead of the constants.

An execution implementation will be locked:

Furthermore, locking can be used by Activity implementations to make executions read only during wait states hen responsibility for the execution is transferred to an external entity such as:

In these situations the strategy is that the external entity should get full control over the execution because it wants to control what is allowed and what not. To get that control, they lock the execution so that all interactions have to go through the external entity.

One of the main reasons to create external entities is that they can live on after the execution has already proceeded. For example, in case of a service invocation, a timer could cause the execution to take the timeout transition. When the response arrives after the timeout, the service invocation entity should make sure it doesn't signal the execution. So the service invocation can be seen as a activity instance (aka activity instance) and is unique for every execution of the activity.

External entities themselves are responsible for managing the execution lock. If the timers and client applications are consequent in addressing the external entities instead of the execution directly, then locking is in theory unnecessary. It's up to the activity behaviour implementations whether they want to take the overhead of locking and unlocking.