Configuring Activiti Database

In this example we will learn how to configure Activiti to use another Relational Database. We will switch from the default H2 database to PostgreSQL.

You can configure a different database using two main strategies:

Programmatic configuration

Using a Programmatic configuration, you will define the ProcessEngineConfiguration and set JDBC parameters as follows:

ProcessEngineConfiguration config = (StandaloneProcessEngineConfiguration)ProcessEngineConfiguration
        ProcessEngine processEngine = config.buildProcessEngine();

Declarative configuration in activiti.cxf.xml

On the other hand, you can use the main Activiti configuration file and define the JDBC settings in the StandaloneProcessEngineConfiguration Bean as in the following example:

<beans xmlns=""

	<bean id="processEngineConfiguration"

		<property name="databaseType" value="postgres" />
		<property name="jdbcUrl" value="jdbc:postgresql://localhost:5432/activiti" />
		<property name="jdbcDriver" value="org.postgresql.Driver" />
		<property name="jdbcUsername" value="postgres" />
		<property name="jdbcPassword" value="postgres" />

		<!-- <property name="dataSource" ref="dataSource" /> -->

		<!-- Database configurations -->
		<property name="databaseSchemaUpdate" value="create-drop" />

		<!-- job executor configurations -->
		<property name="jobExecutorActivate" value="true" />

		<property name="createDiagramOnDeploy" value="false" />



In terms of code, you will need to configure the RespositoryService to use the configuration provided by Activiti configuration as follows:

final RepositoryService repositoryService = processEngine.getRepositoryService();

Here is where you can place the activiti.cfg.xml in the DemoActiviti project that we have uploaded on github at:

├── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── mastertheboss
    │   │           ├── activiti
    │   │           │   └── DemoActiviti
    │   │           │       └──
    │   │           └── task
    │   │               └──
    │   └── resources
    │       ├── activiti.cfg.xml
    │       └── DemoProcess.bpmn

Adding the JDBC Driver in the pom.xml

Finally, whahever is your approach to configuring JDBC, you have to include the driver libraries in your application. If you are using Maven, then include the database JDBC driver in the pom.xml


How to install activiti-explorer on WildFly-JBoss

This short tutorial will teach you how to deploy activiti-explorer Web application on WildFly / JBoss EAP using a custom database such as PostgreSQL.

First of all, download Activiti last stable release from

There, within the zip file, you will find the war folder which contains the activiti-explorer.war file. Here are the steps for changing the database.

$ unzip activiti-explorer.war

Edit the file WEB-INF/classes/ and specify the JDBC settings for the Database. This is the default file:


Here’s a sample configuration for PostgreSQL


In addition, consider that Activiti Explorer generates demo user and groups, process definitions and models by default. To disable this, the file (also in the WEB-INF/classes folder) should be changed. To disable the demo setup fully you can set all of these properties to false. But as you can see you can also enable and disable items individually.

# demo data properties

Update activiti-explorer with JDBC driver

Last step will be copying the JDBC Driver for your DB, in the WEB-INF/lib folder of activiti-explorer.war

$ cp postgresql-9.4-1204.jdbc4.jar activiti-explorer.war/WEB-INF/lib

Now, pack activiti-explorer.war and deploy the activiti-explorer to WildFly / JBoss

$ cp activiti-explorer.war $JBOSS_HOME/standalone/deployments

Clustering activiti BPMN

In this interview Activiti‘s project lead Tijs Rademakers discusses about best practices for running Activiti BPMN 2.0 solution as part of a cluster of application server nodes.  

The Activiti BPM solution is a well adopted and consolidated solution in the Java EE arena. As most of the Enterprise applications running in production are configured to provide redundancy of services by means of cluster, I’d like to explore the capabilities of the Activiti framework in a cluster.

1) So, at first which is the recommended Activiti setup in a cluster ? (Shared database vs Multiple databases with data replication)

There€s no general recommended Activiti setup because this depends on a lot of different aspects and can change between use cases. When there€s a need to cluster multiple Activiti Engines, it€s often best to go for a shared database.

There€s one main component in Activiti that should be taken into account when clustering Activiti and that€s the Job Executor. The Job Executor performs timer logic and asynchronous activities in the Activiti Engine. The Job Executor can be disabled per Activiti Engine, which means that in a cluster of 3 Activiti Engines you could run the Job Executor on only one Activiti Engine. But running 3 Job Executors is supported out-of-the-box as well and a job will only be executed by one Job Executor with a locking strategy.

2) Is Activiti able to execute failover of processes ? Let’s say for example that the first call hits the Activiti EngineB which will launch the process on NodeB of the cluster. Supposing for example that the process on EngineB is waiting for human interaction task. Before the human interaction occurs, NodeB goes down. When the interaction occurs, the Load Balancer in front of the cluster will direct the request to another node, let’s say NodeA – will this correctly continue the process?

Yes that€s supported without additional configuration. The Activiti database will contain the process instance created by Node B and Node A will be able to perform the human interaction logic on the same process instance.

3) Supposing that your Processes are idempotent, that is you can re-execute them in case of failure without corrupting data. In such a scenario would you recommend an architecture where you have on each Server: 1 Application Server – 1 Activiti Engine – 1 Database

Like mentioned in 1) the typical usage would be to use a shared database. But yes 1 Application and 1 Activiti Engine would be a typical architecture.

4) Which (if any) Activiti components are cached in the engines that are part of the cluster ?

The main artifacts that are cached in the Activiti Engine are process definitions. Every Activiti Engine will have a cache of process definitions in-memory. In addition there€s a thread cache when running a process instance until it gets persisted to the Activiti database.

5) How do you ensure that multi threaded requests from process engines are properly synchronized ? is it demanded to the database specific features or it is done enterely by Java code ?

The first request trying to complete a specific user task will be executed and the second request will get an exception. If multiple requests access different process instances in the Activiti Engine then each request is executed as expected of course.

6) What happens if the Job executor is deployed on every node of the cluster ? would you recommend it ?

It€s recommended to have more than one Job Executor to have fail-over. When each node in a cluster has a Job Executor running then that€s fine as well. Each Job Executor will poll the jobs table to look for jobs to be executed. But only one Job Executor will be able to lock the job and then execute it. If you really need that many Job Executors depends on the number of jobs (timers, asynchronous activities) that you have in your process definition. Typically, having 2 Job Executors is enough for a lot of use cases.

Tijs Rademakers is a senior software engineer specializing in open source BPM, lead developer of Activiti Designer, and member of the core Activiti development team. He is the author of the book Activiti in Action published by Manning

Activiti BPMN on JBoss AS 7

In this tutorial we show how to install the Activiti BPMN platform on JBoss AS 7 and how to deploy and test a sample process in it. 

Activiti is a light-weight workflow and Business Process Management (BPM)  engine. We have already published an Activiti tutorial about one year ago, now we will explore a newer release and try it with the latest JBoss AS 7.

Start by downloading Activiti latest release

Installing Activiti

Just unzip the file to a directory of choice and then check out the readme.html that includes pointers to the docs and the release notes. The userguide ( docs/userguide/index.html ) includes instructions on how to get started simple and quick.

The default activiti installation is targeted on H2 in memory Database. We will show here how to switch to MySQL database.

Create the Activiti Database

mysql> create database activiti;

mysql> grant usage on *.* to kermit@localhost identified by ‘kermit’;

mysql> grant all privileges on activiti.* to kermit@localhost ;

Picktup the createdb script: The script is named activiti.mysql.create.engine.sql and is located in the activiti-engine-5.9.jar (Into the org\activiti\db\create folder). Execute the script from your sql session (or any other Sql client application)

mysql> source activiti.mysql.create.engine.sql

Install the Eclipse plugin

Activiti comes with an Eclipse plugin, the Activiti Eclipse Designer, that can be used to graphically model, test and deploy BPMN 2.0 processes.
Go to Help -> Install New Software. In the following panel, click on Add button and fill in the following fields:

Name: Activiti BPMN 2.0 designer


Once installed restart Eclipse.

Create an Activiti Project

Now we will create a new Activiti Project which will provide the archetype for building our first application.
Next add a diagram to it. In this diagram we will simulate a Review process which will be used to approve or reject a candidate.
Create a process where you have an User Task (that will be in charge to evaluate the candidate) and two Mail Tasks where you will dispatch the approval or rejection of your candidate.

Here’s how your process looks like:

Within the User Task (1), select the Main Config Tab and choose as Assignee the user “kermit” (the default administrator).

Next move to the Form Tab we will set three properties (name, mail and experience) that can be filled by the Reviewers and will decide the path of the workflow.

Now move to the upper Sequence Flow (2) and add the condition which will be undertaken if approved the candidate (in this simple process we suppose that candidates with over 5 years of experience are accepted).

Now add the corresponding confition in the lower Sequence Flow (3)

Next move to the Mail task (4) and adds the information necessary to dispatch the mail. The mail will be sent to the address specified by the “mail” variable and, into the text, we will use as well the “name” form property.

Fine, repeat the same for th Mail task(5) in case the candidate is rejected.

Good, now your simple Review process can be uploaded. It should look like this (we have not included for brevity the bpmn graphic notation. You can download the full process from here)

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="" xmlns:xsi="" xmlns:activiti="" xmlns:bpmndi="" xmlns:omgdc="" xmlns:omgdi="" typeLanguage="" expressionLanguage="" targetNamespace="">
  <process id="SampleReview" name="SampleReview">
    <startEvent id="startevent1" name="Start"></startEvent>
    <endEvent id="endevent1" name="End"></endEvent>
    <userTask id="usertask1" name="User Task" activiti:assignee="kermit">
        <activiti:formProperty id="name" name="name" type="string"></activiti:formProperty>
        <activiti:formProperty id="experience" name="experience" type="long" required="true"></activiti:formProperty>
        <activiti:formProperty id="email" name="email" type="string"></activiti:formProperty>
    <serviceTask id="mailtask1" name="Approved" activiti:type="mail">
        <activiti:field name="to" expression="${email}"></activiti:field>
        <activiti:field name="subject" expression="Request Approved"></activiti:field>
        <activiti:field name="html">
          <activiti:expression><![CDATA[${name} we are glad to inform you that your canditature has been accepted.]]></activiti:expression>
    <serviceTask id="mailtask2" name="Rejected" activiti:type="mail">
        <activiti:field name="to" expression="${email}"></activiti:field>
        <activiti:field name="subject" expression="Request Rejected"></activiti:field>
        <activiti:field name="html">
          <activiti:expression><![CDATA[${name} we are sorry to inform you that your canditature has been accepted.]]></activiti:expression>
    <sequenceFlow id="flow1" name="" sourceRef="startevent1" targetRef="usertask1"></sequenceFlow>
    <exclusiveGateway id="exclusivegateway1" name="Exclusive Gateway"></exclusiveGateway>
    <sequenceFlow id="flow2" name="" sourceRef="usertask1" targetRef="exclusivegateway1"></sequenceFlow>
    <sequenceFlow id="flow3" name="" sourceRef="exclusivegateway1" targetRef="mailtask1">
      <conditionExpression xsi:type="tFormalExpression"><![CDATA[${experience > 5}]]></conditionExpression>
    <sequenceFlow id="flow4" name="" sourceRef="exclusivegateway1" targetRef="mailtask2">
      <conditionExpression xsi:type="tFormalExpression"><![CDATA[${experience <= 5}]]></conditionExpression>
    <sequenceFlow id="flow5" name="" sourceRef="mailtask1" targetRef="endevent1"></sequenceFlow>
    <sequenceFlow id="flow6" name="" sourceRef="mailtask2" targetRef="endevent1"></sequenceFlow>

(In order to upload it from the Activiti explorer you can either use a .zip file, a .bar archive or an xml file ending with .bpmn20.xml)

Deploy Activiti Process Explorer on JBoss AS 7

The Activiti process explorer is an handy web application which can be used to manage your processes. It is located into your apps\apache-tomcat-6.0.32\webapps path of your Activiti installation.

In order to enable the deployment of this application on JBoss AS 7 you have:
1) Rename the folder as activiti-explorer.war (so that the AS7 deployer will target is as a web application)

2) Open the applicationContext.xml file which is located in the WEB-INF path of your application and modify it so that it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""
    xmlns:xsi="" xmlns:context=""
    xmlns:tx="" xmlns:jee=""

    <bean id="dbProperties"
        <property name="location" value="" />

        <property name="ignoreUnresolvablePlaceholders" value="true" />

    <bean id="demoDataGenerator" class="org.activiti.explorer.demo.DemoDataGenerator">
        <property name="processEngine" ref="processEngine" />

    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="com.mysql.jdbc.Driver" />
        <property name="url"
            value="jdbc:mysql://localhost:3306/activiti?autoReconnect=true" />
        <property name="username" value="kermit" />
        <property name="password" value="kermit" />
        <property name="defaultAutoCommit" value="false" />

    <bean id="transactionManager"
        <property name="dataSource" ref="dataSource" />

    <bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
        <property name="dataSource" ref="dataSource" />
        <property name="mailServerHost" value="localhost" />
        <property name="mailServerPort" value="25" />
        <property name="mailServerUsername" value="fmarchioni" />
        <property name="mailServerPassword" value="fmarchioni" />
        <property name="transactionManager" ref="transactionManager" />
        <property name="databaseSchemaUpdate" value="true" />
        <property name="jobExecutorActivate" value="true" />
        <property name="customFormTypes">
                <ref bean="userFormType" />

    <bean id="processEngine" class="org.activiti.spring.ProcessEngineFactoryBean"
        <property name="processEngineConfiguration" ref="processEngineConfiguration" />

    <bean id="repositoryService" factory-bean="processEngine"
        factory-method="getRepositoryService" />
    <bean id="runtimeService" factory-bean="processEngine"
        factory-method="getRuntimeService" />
    <bean id="taskService" factory-bean="processEngine"
        factory-method="getTaskService" />
    <bean id="historyService" factory-bean="processEngine"
        factory-method="getHistoryService" />
    <bean id="managementService" factory-bean="processEngine"
        factory-method="getManagementService" />
    <bean id="identityService" factory-bean="processEngine"
        factory-method="getIdentityService" />

    <bean id="activitiLoginHandler" class="org.activiti.explorer.ui.login.DefaultLoginHandler">
        <property name="identityService" ref="identityService" />

    <import resource="activiti-ui-context.xml" />

    <bean id="userFormType" class="org.activiti.explorer.form.UserFormType" />


Please notice the Datasource section, which contains the MySql settings for the dataSource Bean. In this case, the simplest way to achieve this is to use the org.apache.commons.dbcp.BasicDataSource.


Using JBoss AS Datasource

If you don’t have to use Apache connection pool and rather want to use JBoss own datasource you have to do a bit more of work, as it will require installing Activiti CDI libraries as well: at first create a datasource on jBoss AS as described in this tutorial:
Then, comment the dataSource bean definition. Instead of it, you will have to reference the datasource through the processEngineConfiguration as shown here:

   <!-- process engine configuration -->
   <bean id="processEngineConfiguration" class="org.activiti.cdi.CdiJtaProcessEngineConfiguration">
      <property name="dataSourceJndiName" value="java:jboss/datasources/MySQLDS" />
      <property name="databaseType" value="mysql" />
      <property name="transactionManager" ref="transactionManager" />
      <property name="transactionsExternallyManaged" value="true" />
      <property name="databaseSchemaUpdate" value="true" />

  <bean id="transactionManager" class="org.springframework.jndi.JndiObjectFactoryBean">
      <property name="jndiName" value="java:jboss/TransactionManager"></property>
      <property name="resourceRef" value="true" />

If you try to deploy the Activiti Explorer with this configuration, the deployer will complain that cannot find the java.lang.ClassNotFoundException: org.activiti.cdi.CdiJtaProcessEngineConfigurationNext. As a matter of fact, the new process engine configuration will require CDI dependencies. They are not included in the default Activiti distribution, you have to pick them up using Maven, with the following dependencies:


Finally, once the application is started up, the activiti-cdi.jar will try to boot the process engine. To accomplish this it will lookup a bean implementing the “ProcessEngineLookup” interface. You will have to provide one, extending LocalProcessEngine lookup, which will create a spring-configured process engine:

public class ProcessEngineConfiguration extends LocalProcessEngineLookup {

Well, that was a bit lenghty procedure, however if you want to learn more about it, we suggest you looking at this repository which shows how to set up Activiti + CDI on JBoss 7.1.1:

Configure the mail support:

Since this process will deliver an email to the candidate which will be reviewed by you, we will configure a simple mail server solution with Apache James. You can try Apache James which is an opensource mail server, pretty light and simple to get started with it. Download it. Next unzip it and launch the run script which will start the mail server.


At startup James server just contains an administrative root account, so we will use this to add an user account. Unfortunately James does not provide (as far as I know!) a GUI interface to add users, to do that, telnet to localhost on port 4555 with the command:

telnet localhost 4555


You can log in with the root user name and password. After the login, we’ll add an user. The adduser command expects a username and password combination. After adding users, you can use the listusers command to verify the entries and then exit the remote manager by typing quit. The whole session should look like this:

Now copy the Process Explorer on JBoss AS 7 deployments folder and add a activiti-explorer.war.dodeploy to trigger the deployment of the exploded archive.

That’s all. Start the process explorer with: http://localhost:8080/activiti-explorer/

We have found out some errors in the JBoss console about the GWT GUI libraries. This does not seem to cause any issue however we suggest you picking up the gwt-user-2.3.0 from Grep Code repository.

Now login into the Process Explorer console, with one of the built-in administrator kermit/kermit.As first step, upload the process through the “Manage” upper tab and the Deployments menu.

Once deployed the bpmn20 file, move to the “Process” upper tab, where you can review the process picture and start a new instance of it, through the “Start process” button.

Once started, fill up the form properties which are related to the process. In this example we have filled an “experience” which is over 5 years, thus the expected outcome is to receive a mail containing the approval for the candidate.

Let’s open your mail client (in our example Thunderbird) and verify it:

That’s all! In this tutorial we have showed how to run a BPMN 2.0 process using Activiti Engine on JBoss AS 7. In the next one, we will show how to start and manage this process programmatically, using Activiti API. Stay tuned !

Activiti faqs

Are you using Activiti to model your processes ? here is a list of technical faqs which will guide you to some most common development issues.


#What is Activiti ?

Activiti is an opensource BPM (Business Process Management) framework distributed under Apache license. It delivers BPMN2.0 compliant processes. However, the Activiti engine Activiti leverages also a lot of limited and dedicated process languages for specific use cases.

#Are Activiti processes synchronous or asynchronous ?

By default, Activiti Engine uses the thread of the client to perform it’s work. If you need to spawn several instances of a process you can use Java Threads.

If you want async behaviour you have to add an async attribute to the service task configuration:

<serviceTask id="MyTaskAsync"
name="Async Service" 

When we define a Service Task with the async attribute set to true, the execution of the service task logic will be launched in a separate transaction and thread. The process state is persisted to the Activiti database and a job is created to handle the service task execution

#How to start and manage a process from another application (also non-Java application) ?
The easiest way would be to use Activiti’s REST API. See

#What kind of variables can be used in an Activiti process ?

Basically two types: Process variables and Task Variables.
Process variables are visibile throughout the process, while Task variable are local to the Task.
Example Process variable (set in a serviceTask):

public class ToUppercase implements JavaDelegate {
   public void execute(DelegateExecution execution) throws Exception {
     String var = (String) execution.getVariable("input");
     var = var.toUpperCase();
     execution.setVariable("input", var);

Task local variable example:

From the TaskService Api:

taskService.setVariableLocal("123", "myVariable", "Variable value");

Or inside a TaskListener, using DelegateTask

public void notify(DelegateTask delegateTask) {
   delegateTask.setVariableLocal("123", "myVariable", "Variable value");

#Are class level variables defined in a serviceTask thread safe ?
No. As stated in the docs “there will be only one instance of that Java class created for the serviceTask it is defined on“.

public class ToUppercase implements JavaDelegate {

 private int sharedCounter; 
 public void execute(DelegateExecution execution) throws Exception {
  synchronized (this) {
     // modify sharedCounter


For this reason, any class member variable will be shared between all process instances. It’s your responsibility to synchronize access their access.

#How to persist process variables ?
Process variables are automatically stored in the database. Check the ACT_RU_VARIABLE table.

#How to propagate Task variables to the process ?
Add a listener to the task, that simply injects the task local variable to the process.

#How to read a process variable programmatically?
Supposing you set this variable in a serviceTask:

public void execute(DelegateExecution arg0) throws Exception {
 . . . . 
 arg0.setVariable("user", rs.getString(1));

You should use the runtimeService for this and fetch the variables for the execution you want:

runtimeService.getVariables(execution.getId());  // Get all variables
runtimeService.getVariable(execution.getId()."user")   // get user variable

#How to read a process variable from the Process Instance ?

ProcessInstance processInstance = startProcessInstance();
RuntimeService runtimeService = processEngine.getRuntimeService();

Date validatetime = (Date) runtimeService.getVariable(processInstance.getId(), "validatetime");

#How to invoke REST Api programmatically

–without authentication

DefaultHttpClient dhc = new DefaultHttpClient();
HttpPost hp = new HttpPost("http://localhost:8080/activiti-rest/service/process-instance");
hp.setEntity(new StringEntity("{\"processDefinitionId\":\"helloworld:1\"}", "UTF-8"));

HttpResponse processResponse = dhc.execute(hp);

—   With basic authentication:

DefaultHttpClient dhc = new DefaultHttpClient();
dhc.getCredentialsProvider().setCredentials(new AuthScope(AuthScope.ANY_HOST, AuthScope.ANY_PORT, AuthScope.ANY_REALM), new UsernamePasswordCredentials("kermit", "kermit"));

HttpPost hp = new HttpPost("http://localhost:8080/activiti-rest/service/process-instance");
hp.setEntity(new StringEntity("{\"processDefinitionId\":\"helloworld:1\"}", "UTF-8"));
HttpResponse processResponse = dhc.execute(hp);

#How to re-assign a task from a user to another ?
You can change the assignee (user assigned to the user task) via the TaskService interface. Just call the setAssignee method with the taskId and the new assignee name.

#How to delete Process Engine History old data ?
Programmatically, it’s possible to remove just HistoricTaskInstances (runtimeService.deleteHistoricTaskInstance).

However, since there are timestamps included in all history tables (start/end times), so if you need to purge the whole process engine you can create a batch-process that runs every day and cleans up the history for X days ago using plain old SQL

#Should my serviceTask implement JavaDelegate  or ActivityBehavior ?
Implementing org.activiti.engine.delegate.JavaDelegate is considered the best practice and should be used in most cases.

public class SampleServiceTask implements JavaDelegate {
   public void execute(DelegateExecution execution) throws Exception {
    . . .

Implementing org.activiti.engine.impl.pvm.delegate.ActivityBehavior gives access to the powerful ActivityExecution which allows to manipulate the flow of execution. This however would apply to a smaller set of cases as it hides to business analysts the actual rules behind the process flow.

public class ThrowsExceptionBehavior implements ActivityBehavior {

   public void execute(ActivityExecution execution) throws Exception {
   String var = (String) execution.getVariable("var");

 PvmTransition transition = null;
 try {
      transition = execution.getActivity().findOutgoingTransition("no-exception");
 }   catch (Exception e) {
      transition = execution.getActivity().findOutgoingTransition("exception");


#How to read the result from a serviceTask?
You can simply place the result in a process variable. If the process variable is the last node in the process, as a workaround you can place a dummy userTask between the serviceTask and the end, you will be able to use and query the value of your ‘result’ variable.

#Can I start a Task with external code?
You can use the REST-API to start up a process or complete a task

#Activiti Modeler: export/print a diagram
The Activiti Modeler does support exporting a process to both png and pdf.

One way to access the rendered process image is to load the URL of the modeler as follows:

http://{URL to activiti-modeler}/p/model/{path to process xml}/{format}

http://localhost:8080/activiti-modeler/ … yx.xml/png
http://localhost:8080/activiti-modeler/ … yx.xml/pdf
#How to use Activiti in my web/ejb application ?

We suggest using Maven and adding the following dependencies in your pom.xml




#The installation cannot find the JDBC Driver

Verify that you have copied the jdbc driver (for example ojdbc5.jar) to setup/files/dependencies/libs/

#How to invoke a JAX-WS Web service from Activiti ?
See this link
Basically, you can wrap the Web service invocation in a serviceTask and use JaxWsDynamicClientFactory to invoke the Web service.

 <process name="SimpleWS" id="SimpleWS">
 <serviceTask id="Call_WS" name="Call WS" activiti:class="" >
 <activiti:field name="wsdl" expression="http://localhost:18080/VacationService?wsdl" />
 <activiti:field name="operation" expression="saveVacationApproval" />
 <activiti:field name="parameters" expression="${user}, ${days}" />
 <activiti:field name="returnValue" expression="myReturn" />

public class WsDelegate implements org.activiti.engine.delegate.JavaDelegate {
 private Expression wsdl;
 private Expression operation;
 private Expression parameters;
 private Expression returnValue;

 public void execute(DelegateExecution execution) throws Exception {
 String wsdlString = (String)wsdl.getValue(execution);

 JaxWsDynamicClientFactory dcf = JaxWsDynamicClientFactory.newInstance();
 Client client = dcf.createClient(wsdlString);

 ArrayList paramStrings = new ArrayList();
 if (parameters!=null) {
 StringTokenizer st = new StringTokenizer( (String)parameters.getValue(execution), ",");
 while (st.hasMoreTokens()) {
 Object response = client.invoke((String)operation.getValue(execution), paramStrings.toArray(new Object[0]));
 if (returnValue!=null) {
 String returnVariableName = (String) returnValue.getValue(execution);
 execution.setVariable(returnVariableName, response);

#Where is my activiti configuration stored ?
Activiti configuration is stored in the file activiti.cfg.xml. On the default applications (Activiti Probe/Explorer/Cycle/REST Api) the activiti configuration
is deployed as a jar file named activiti.cfg.jar.
So for example if you want to change the settings of your Activiti REST Api, you have to place a new activiti.cfg.jar into /apps/tomcat/webapps/activiti-rest/lib/
#How to change the configuration of Activiti web applications (Activiti Explorer, Activiti Probe etc.) ?
If you have already built yout activiti demo suite and you need to change the configuration,just issue :

ant cfg.create demo.stop build.webapps demo.start

#Updating Activiti database
To upgrade, at first you have to set the following configuration property in your activiti.cfg.xml configuration file:

<beans ... > 
 <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"> 
 <!-- ... --> 
 <property name="databaseSchemaUpdate" value="true" />     
 <!-- ... --> 


Then just upgrade the Activiti libraries in your application. Or start up a new version of Activiti and point it to a database that contains an older version. With databaseSchemaUpdate set to true, Activiti will automatically upgrade the DB schema to the newer version the first time when it notices that libraries and DB schema are out of sync.

#How to use Process variables in a Script ?
All process variables that are accessible through the execution that arrives in the script task, can be used within the script.
See this sample:

public class ServiceTask implements JavaDelegate {
 public void execute(DelegateExecution execution) throws Exception {
 execution.setVariable("command", "executable arg1 arg2 arg3");

{xtypo_code}<scriptTask id=”theScriptTask” name=”Execute script” scriptFormat=”groovy”>

def proc = command.execute()                 // Call *execute* on the string
proc.waitFor()                               // Wait for the command to finish

// Obtain status and output
def exitValue =  proc.exitValue();
println “stderr: ${proc.err.text}”
println “stdout: ${}” // *out* from the external program is *in* for groovy
#How to set Process variables in a Script ?
Conversely, it is possible to set process variables from inside the script. In the above example, the “exitValue” variable
is defined as the exit value of the command.

In a script-task, you can just declare a variable and it will be stored as process-variable, eg:

<scriptTask id=”theScriptTask” name=”Execute script” scriptFormat=”js”>
var myVariable = ‘this is a value’;

Quick tip:
For a quick process variable setting you can use the current execution, which is available as a reserved variable called ‘execution’.

def scriptVar = “test123”
execution.setVariable(“myVar”, scriptVar)

#Using another script language in Activiti
You can use any JSR-223 compliant language. For example, in order to use JYthon, just add it to the classpath and change the ‘scriptFormat’ value.

#Is it possible to use Beans, like Spring Beans in scripting ?
Using beans in scripts is available in activiti 5.3 (

#How to intercept Process End Event
If you need to perform some activity at the end of the process, then the simplest thing is using an executionListener that listens to the end of the process instance.

#How to handle exceptions raised in a Java ServiceTask ?
It depends on the type of Exception. Basically a business exception (which means an exception raised by a business case) should be visible in the diagram and designed as boundaryEvent.
In this example, the application exception raised by the “javaService” are intercepted by the boundaryEvent “catchError” and lead to a different sequenceFlow, named “catchError”:

<serviceTask id="javaService" .../>
<boundaryEvent id="catchError" attachedToRef="javaService">
<sequenceFlow id="errorFlow" sourceRef="catchError" targetRef="someOtherTask"/>

When the nature of Exception is not of matter to the analyst, or the other stakeholder of the process, you can just handle the exception inside the serviceTask (using ActivityBehavior interface) the and route process execution through another path in case some exception occurs. The following example,taken from the user guide, shows how this is done.

<serviceTask id="javaService" 
 name="Java service invocation" 
<sequenceFlow id="no-exception" sourceRef="javaService" targetRef="theEnd" />
<sequenceFlow id="exception" sourceRef="javaService" targetRef="fixException" />

Here, the service task has two outgoing sequence flow, called exception and no-exception. This sequence flow id will be used to direct process flow in case of an exception:

public class ThrowsExceptionBehavior implements ActivityBehavior {

 public void execute(ActivityExecution execution) throws Exception {
 String var = (String) execution.getVariable("var");

 PvmTransition transition = null;
 try {
 transition = execution.getActivity().findOutgoingTransition("no-exception");
 } catch (Exception e) {
 transition = execution.getActivity().findOutgoingTransition("exception");

#When are transactions committed in Activiti ?
An Activiti process commits its transactions either when the process ends or when it needs to wait for an external trigger (f.e. when a human task needs to be performed). That is when the execution state is persisted and then the transaction commit.

#What happens when an Exception is raised in Java service node ?
In case of exceptions, Activiti will rollback the ongoing transaction.The database will rollback to the previous state in the database.
So the last action (runtimeService.startProcessInstance or runtimeService.signal or task.complete) will return with an exception.

#How to use a Custom ELResolver?
Sometimes you would need to inject your own custom ELResolver into Activiti engine. For example, if you use a very flexible bean structure with configurable classes and properties, it would be difficult to implement this with simple setter and getters.
In Activiti, you can use the ProcessEngineFactoryBean, which uses a custom SpringExpressionManagers. This adds an ELResolver to handle spring-beans. This way, you can use all your spring-beans. If using spring-beans doesn’t cut it, you could write a similar mechanism as done there: creating your own expression-manager, which creates composite EL-resolver containing your custom EL-resolving logic.

#How to deploy project from designer
Actually, you can prepare you artifacts from the Designer and then connect to Activiti Probe to deploy the archive.

1. Go to the Package Explorer (not to be confused with the Project Explorer)
2. Right-click on the project and select “Create deployment artifacts”
3. The .bar file will then be created in a folder called “deployment”

Now use Activiti Probe to upload the artifact.

#How to monitor the process graphically ?
Activiti offers the process-instance visualisation in activiti Probe, or through the REST-API:

#How to download the Eclipse designer ?
If you cannot use Eclipse designer update site, just download Eclipse designer from activiti achive :

#How to use a checkbox in a task form ?
<input type=”checkbox” name=”bwVideo” ${(bwVideo ? ‘CHECKED’ : ”} />

#Adding new form property types
There is a property available on the ProcessEngineConfigutionImpl which allows plugging in your own types, called ‘customFormTypes’. It expects a list of org.activiti.engine.impl.form.AbstractFormType subclasses, which are added to the default types which you have mentioned.

#How to create in a form a Boolean property?

<select name="vacationApproved">
 <option value="true">Yes</option>
 <option value="false">No</option>
<input type="hidden" name="vacationApproved_type" value="Boolean" />

#How to cluster Activiti
Nothing prevents running several instances of Activiti. All application instances are independent, effectively knowing nothing of each other. As a matter of fact Activiti uses optimistic locking on the DB to deal with concurrency.
Job distribution happens through use of database-level locks and job ownership includes information about thread name and host.
When a job is ready to be executed and not locked yet, JobExecutors will try to put a lock on it. Due to use of optimistic locking, only one of them will succeed, the ones that got an OptimisticLockingException will pause for a defined time before acquiring new jobs.
For this reason you are adviced to use a JobExecutor on a single machine to prevent that multiple JobExecutor compete for the same job, causing unnecessary optimistic locking failures.


Activiti tutorial

[Updated to the version 7 of Activiti BPMN]

Activiti is an open-source BPMN platform distributed under the Apache license. It’s written in Java and thus can run in any Java application, on a server, on a cluster or in the cloud. Two deployment options are available for Activiti:

  • Activiti Cloud: which is a set of Cloud Native components designed from the ground up to work in distributed environments based on Kubernetes as main deployment infrastructure and Spring Cloud / Spring Boot along with Docker for containerization of these components.
  • Activiti Core: which is a set of API designed to run the BPMN 2.0 plarform in a Java standalone application / Spring Boot.

In this tutorial we will learn how to design a simple BPMN 2.0 process and use Activiti Core to run it in a Java application.

Installing the Activiti Process Designer

In order to design the BPMB 2.0 processes we will install the Activiti Eclipse plugin so that we can design our process from a Development IDE.

From the Eclipse upper menu, select Help | Install New Software. Choose to add the following Repository:

Next, check Activiti BPMN Designer as displayed by the following picture:

Click on Next and Finish the installation. You will need restarting Eclipse at the end of it.

Create a simple Standalone Project

Ok. Now let’s create a standalone application which uses Activiti API to start process instances and generates a Task list. To include the Activiti JAR and its dependent libraries, we advise using Maven as it simplifies dependency management on both our and your side a lot. Hence create a new Maven project at first:

$ mvn archetype:generate -DgroupId=com.mastertheboss.activiti -DartifactId=activitiDemo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Now we will need to include Activiti core libraries and some dependencies in the pom.xml file. Here is the list of dependencies we will add:


Done with the setup, we will now create a simple Process using the BPMN Designer.

Create a Process Diagram

Now Add an Activiti Diagram to your process from the menu File | New | Other | Activiti | Activiti Diagram.

Create a sample process in the resources folder of your Project. In our case, we will name the process MyProcess and we will save it in resources/DemoProcess.bpmn.
By clicking on it, the visual editor of Eclipse will appear. We will create a simple process definition which contains a ServiceTask, an Exclusive Gateway and two User Tasks. Here’s a picture of our process:

Now you need to configure each node. Select the Properties tab. We will configure first  the ServiceTask which simply recalls a callback method of a Java class implementing the JavaDelegate interface.

The Class we will simulate the choice between a Simple Task and a Complex Task which should be assigned to different actors:

package com.mastertheboss.task;

import org.activiti.engine.delegate.DelegateExecution;

public class JavaService1 implements org.activiti.engine.delegate.JavaDelegate {

	public void execute(DelegateExecution arg0) {

		if (isComplexTask()) {
			System.out.println("This is a complex task!");
			arg0.setVariable("result", "1");
		else  {
			System.out.println("This is a simple task!");			
		    arg0.setVariable("result", "0");


	private boolean isComplexTask() {
		return Math.random() < 0.5;


As you can see, this project contains two Tasks: we will assign each of them to a different Actor. Say, we will assign the first one to kermit and the second one to gonzo. Here’s the Properties for the first Task:

And, in turn for the second Task:

Finally we will configure the exclusiveGateway which can be seen as a Decision node. Depending on the value of “result” it will lead the process definition to two different Tasks. On each sequence flow choose a condition Expression: for example in upper Flow we will set the following condition:

Conversely, the lower Flow will capture the condition where result = 0:

Great, you are done with building your first Activiti Process.

Write a simple Activiti Client

Ok. Now the process is completed. We will add a minimal API to start the Process and claim the Tasks generated. 

package com.mastertheboss.activiti.main;

import org.activiti.engine.*;
import org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration;
import org.activiti.engine.repository.Deployment;
import org.activiti.engine.repository.ProcessDefinition;
import org.activiti.engine.runtime.ProcessInstance;
import org.activiti.engine.task.Task;

import java.util.List;
import java.util.Map;
import java.util.HashMap;

public class App
    public static void main( String[] args ) throws Exception

        ProcessEngineConfiguration cfg = new StandaloneProcessEngineConfiguration()
        ProcessEngine processEngine = cfg.buildProcessEngine();
        String pName = processEngine.getName();
        String ver = ProcessEngine.VERSION;
        System.out.println("ProcessEngine [" + pName + "] Version: [" + ver + "]");

        RepositoryService repositoryService = processEngine.getRepositoryService();
        Deployment deployment = repositoryService.createDeployment()
        ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
                "Found process definition ["
                        + processDefinition.getName() + "] with id ["
                        + processDefinition.getId() + "]");

        final Map<String, Object> variables = new HashMap<String, Object>();
        final RuntimeService runtimeService = processEngine.getRuntimeService();

        ProcessInstance id = runtimeService.startProcessInstanceByKey("myProcess", variables);
        System.out.println("Started Process Id: "+id.getId());

        try {
            final TaskService taskService = processEngine.getTaskService();
            final List tasksSenior = taskService.createTaskQuery().taskAssignee("kermit").list();
            final List tasksJunior = taskService.createTaskQuery().taskAssignee("gonzo").list();

            if (tasksSenior.size() > 0) {
                System.out.println("Found task for Senior " +tasksSenior.get(0).getName() );
                taskService.claim(tasksSenior.get(0).getId(), "kermit");

                System.out.println("Task " +tasksSenior.get(0).getName() +" terminated");
            else if (tasksJunior.size() > 0) {
                System.out.println("Found task for Junior " +tasksJunior.get(0).getName() );
                taskService.claim(tasksJunior.get(0).getId(), "gonzo");

                System.out.println("Task " +tasksJunior.get(0).getName() +" terminated");

        } catch (Exception e) {
        } finally {



As you can see, the central starting point is the ProcessEngine. From the ProcessEngine, you can obtain the various services that contain the workflow/BPM methods.

Typically, there will be only one ProcessEngine instance needed in a end-user application. Building a ProcessEngine is done through a ProcessEngineBuilder instance and is a costly operation which should be avoided. For that purpose, it is advised to store it in a static field or JNDI location (or something similar).

Once started the class, an instance of the ProcessInstance will be created. The TaskService API is then used to retrieve the list of Tasks which can be claimed by the users “kermit” and “gonzo”. Depending on the Random number generated, the Task can be claimed by one of the two users, therefore a typical output of the execution would look like this:

This is a simple task!
Started Process Id: 5
Found task for Junior SimpleTask
Task SimpleTask terminated

You can download the source code for this article at:

jBPM vs Activiti: which to choose?

This tutorial has been written for an old version of jBPM which is now deprecated.

If you want to get started quickly with jBPM, we recommend the following quickstarts:

This is an update to my earlier article which was written in 2011 when jBPM 5 was still not available in its final release. We will try to compare the two process engines showing, besides the similarities, also the key differences between them.

jBPM€”is an open source process engine that initially (release 3.x) supported a custom language (named jPDL) to describe business processes. In the next release (4.x) jBPM offered both support for jPDL and the standard BPMN 2.0 which is the standard for business process modelling. The release 4.x of jBPM was never included into RedHat list of supported products and so was not clearly the choice for mission critical project.

The next version  5.x  of jBPM supports  BPMN   2.0, and the project  has  merged  with  the  JBoss  Drools  project  (an  open  source  business-rule  management  framework)  and  replaced  Drools  Flow  as  the  rule  flowlanguage for the Drools framework.

The key features of jBPM 5 are:  

  • Native BPMN2 execution
  • Highly configurable, embeddable, lightweight process engine using a generic process engine (PVM) underneath
  • Domain-specific processes and rule / event integration via the Drools Rule engine and Drools Flow workflow
  • Independent, human tasks service (using WS-HT)
  • Web tooling for things like BPMN2 process creation, deployment, management, reporting (with BIRT) and human tasks
  • Migration capabilities from jBPM 3 and 4 (jPDL 3, 4 to BPMN2)

Activiti, like jBPM, is a business process framework designed around the concept of a state machine. Backed by Alfresco company, Activiti has also the collaboration of many talented people from SpringSource as well.

Some differences do exist, in particular:

  • Activiti has native Spring support which allows using Spring Beans in your process and in data persistence (JPA) as well.
  • Activiti has no native rule engine support but supports a basic integration with Drools to support the business Rule Task
  • Activiti is a bit more friendly for Java developers providing a rich set of BPMN extensions to decorate the process
  • Provides an advanced Web interface (Activiti Explorer) which can be used to start/manage processes and ad hoc task and forms support. 

So, in terms of comparison, we can argue that Activiti looks like the logical continuation of jBPM 3(and in fact was developer by the same jBPM 3 guys T. Baeyens, J. Barrez). It has a lower learning curve also due to a very well done documentation, including a quick start tutorial. Activiti platform is completely dedicated to process and workflow management and has some integration support with Rules systems (Drools Expert) and enterprise integration capabilities (Apache Camel and Mule ESB modules).

On the other hand, jBPM 5 has a native built-in business Rules engine therefore, the process and workflow management and rule management capabilities are tightly integrated. In the latest (5.3) release the Eclipse editor has improved a lot its BPMN 2.0 process designer capabilities and a first release of the form editor has been released.