Getting started with Activiti framework


Activiti is an open source framework which provides a complete Business Process Management solution. In laymen’s terms, activiti allows you to create automated processes where tasks get assigned to the intended users and emails/notifications are sent when required and much much more. This is all configured while creating the process and once tested and deployed, it can greatly reduce the errors due to human ignorance.

This post focuses on setting it up on our local computer and enable us to harness it using Eclipse IDE.

First, we will create a very simple process to print “Hello Activiti!” on the console to verify that our setup works. Then, we will create an advanced process which assigns a task to the user and we will see how that user can see the task on the activiti-explorer UI.


  1.  Download and install Java.
  2.  Download Tomcat (any web container is also fine).
  3.  Download Eclipse (or any IDE of your choice).
  4.  Download and configure maven.
  5.  Download PostgreSQL. By default, the activiti uses an in memory H2 database but we will use Postgres in this tutorial. But it is just a matter of choice. I use postgres all the time for my personal and professional projects, you can use MySQL, MongoDB or even the default H2 DB.
  6. Download Activiti.
  • Copy the downloaded activiti-explorer.war to the webapps directory of Tomcat.
  • Start Tomcat by running the startup.bat or scripts in the bin folder of Tomcat
  • When Tomcat is started open your browser and go to http://localhost:8080/activiti-explorer. Login with kermit/kermit.

when you run the app, tomcat expands the activiti-explorer.war and you can find h2 jar here: ../apache-tomcat/webapps/activiti-explorer/WEB-INF/lib/h2-1.3.176.jar. You can double click this jar to run H2 DB, if you choose to stick with the default database.

Activiti Plugin For Eclipse

Go to Help → Install New Software. In the following panel, click on Add button and fill in the following fields:

Name: Activiti designer (or whatever you please)


Follow the instructions, select  Activiti BPMN designer

and agree to the terms and you are done.

*As per the official documentation Eclipse Helios is NOT supported.

New Activiti Project

Go to File → New → Project and create an Activiti project



Now, right click the project  Properties → Java Build Path → select Libraries tab and make sure it looks like this: 

Now we need to tell eclipse about Activiti specific dependencies. Is f you look at the pom.xml in your newly created project you will see that everything is already there but if you start writing a test case right away you will notice errors on activiti classes/annotations and you won’t be able to import them as the jars are missing.


What’s going on here?

Well, since you created the activiti project using eclipse’s New Project wizard, eclipse created everything for you but since it is not a maven project, eclipse didn’t know what to do with the pom file.

So, we need to mavenize the project or say convert the project to a maven project.
It is pretty simple – right click on the project  Configure  Convert to maven project.

And while you are at it add postgres dependency in your pom file:


Now, you can import ProcessEngine in the code snippet above. You can also see that the Maven Dependencies folder is now filled with the jars specifies in the pom.xml

Activiti configuration

We will now configure our database setting in the activiti configuration file (activiti.cfg.xml) and make sure it is present in the project class-path. We will paste it at java/test/resources folder and write a simple JUnit test case to ensure that everything works.



BPMN file

You also need to paste myProcess.bpmn20.xml file into your src/test/resources folder as shown in the image below.

Unit Test


Project Hierarchy

Your project hierarchy should look like this:


Run →  right click → Run As → Junit test.


On the console you should see:

and a lot of activiti specific tables will be generated in the DBThis confirms that everything is working perfect and since setup is out of the way we can now focus on the real stuff i.e, learning one of the coolest Business Process Management tool, Activiti.

But before I leave you to explore activiti lets deploy one more process which is a bit advanced as compared to the one we just used to test our setup.

Exploring Activiti-explorer

Let’s create a Laptop order workflow and see how a user receives the order and can work on it. This simulates the real life scenario and also lets us take a look at the working of activiti-explorer UI. After this, we should be able to start using activiti for any real world project. Think all those online shopping websites. They might be using something very similar :).

So, the first step is to create a process file.

This process has three sequences. 1. Start 2. User Task 2. End. Once this process runs we should be able to see the user task at the activiti-explorer UI, we setup at the starting of the post.

The test case is pretty similar to the one we saw above but this time we use IdentityService to assign the task to the user (“kermit”). The code is fairly simple to understand.

Now, before you fire up the activiti UI, there are some settings that need to be done in tomcat.

Tomcat configuration

  1. We need to paste the postgres jar, we downloaded via maven into ../apache-tomcat/webapps/activiti-explorer/WEB-INF/lib
  2. We need to replace the contents of file present at ../apache-tomcat/webapps/activiti-explorer/WEB-INF/classes with

                  jdbc.url=jdbc:postgresql://localhost:5432/<your DB name>
                  jdbc.username=<your DB usrname>
                  jdbc.password=<your DB password>

Run the test case and you should get the console output as:


Now, log into activiti-explorer http://localhost:8080/activiti-explorer/. If you are already logged-in, log out and then log in again.

You (logged in as the user Kermit) can now finish the task.

Possible Exception

Please note, that in some cases you might get a weird looking exception when you run the unit test for the second time i.e, for the first time everything works perfect but when to run the test case again later you might get:

This happens when you are using different versions of the Activity database and the Activity Engine.

When I created the project using Eclipse, by default, I got Activiti Engine 5.18.0 and then I downloaded the latest version of Activiti from the website i.e, 5.22.0 which created the DB with schema version

Here is the snapshot of one of the activiti specific table – act_ge_property

You need to browse the internet or activiti forum for next couple of minutes to figure out the correct version or you can do this:
I just fixed the schema version to match the one initially created i.e,


I hope it was easy to follow and absolutely painless.

Source Code

You can download the full source code of the project and import it to your IDE as existing maven project to run directly without going into any details.

Thanks for stopping by!!