This article aims to set up a complete Activiti development environment and perform the two exercises. The first exercise is just a hello world, useful only to setup an Eclipse project. The second one is a more complete test, very interesting for the Activiti beginners.
Introduction
In my everyday job as a software developer, I'm always enthusiastic when I have to deal with new technologies, toolkits and frameworks. Luckily, my company satisfies me in this, and so often I find myself with a new huge book or manual to study. This is the reason why I came across Activiti.
Activiti in Action [1] is a great book, but I had some problems in performing the two simple exercises of the first chapter due (IMHO) to the lack of some information. I discovered that other people have the same problem.
If you have encountered problems in carrying out the exercises in the first chapter of the book Activiti in Ation, this article is for you.
This article is a walkthrough of the mentioned chapter with the aim to set up a complete Activiti development environment and perform the first two exercises. The first exercise is just a hello world, useful only to setup an Eclipse project. The second one is a more complete test, very interesting for the Activiti beginners.
Ingredients
- Java JDK SE 1.7.4x (the 1.6.x series is also good, and maybe other previous series)
- Apache Tomcat
- Activiti 5.13
- Eclipse Indigo (no other, only Indigo!)
- H2 database
Install the Tools
I assume that you know what Java JDK SE is, and how to install it. After the installation, you have to set the JAVA_HOME environment variable in a persistent way. Tomcat is a Java program, so the installation is simply the unzip of the package in a folder of your choice.
Scripts to start and stop Tomcat are in the bin folder, the XML config file for the Tomcat users is in the conf folder. Other information about Tomcats are out of the scope of this article, but you can easily find a lot of stuff about Tomcat throughout the net. Activiti pack is not a program, it's a collection of libraries. Unzip the pack in a folder of your choice.
Then, in the <activitipack>/wars folder, copy activitiexplorer.war file and paste it into the webapps folder of Tomcat. In this way, you've installed the activiti-explorer application. H2 database is a Java program. Unzip the pack in a folder of your choice. In the bin folder, there's the script to launch the DBMS process.
Eclipse is a Java program. Unzip the pack in a folder of your choice. Once Eclipse is launched, you can install the Activiti plugin for eclipse. Instruction about the plugin installation are here: http://www.activiti.org/userguide/#activitiDesigner. Hereafter, I will suppose you have installed the activiti eclipse plugin.
Test the Tools
Start Tomcat. During the startup, Tomcat unpacks and deploys the activiti-explorer webapp. By default, the app uses an in memory H2 database.
Go with a browser to http://localhost:8080/activiti-explorer/. You should see the activiti-explorer page as in Figure 1. You can login this page with the username kermit and password kermit.
Figure 1 - The Activiti Explorer page
Start H2 database. As it starts, H2 tries to launch the browser with the H2 web console. If the browser will not start, you can start it manually. The page URL is http://localhost:8082/. You should see the following page:
Figure 2 – The H2 DB console page
In the JDBC URL line, type: jdbc:h2:tcp://localhost/activiti (see the figure) and then push the Connect button. You should see the H2 console DB page for the jdbc:h2:tcp://localhost/activiti DB. In the left column, you can see that the DB is empty, no tables are contained, refer to Fig. 3.
[EDIT: On Activiti 5.17.0, the default JDBC url for the H2 instance is jdbc:h2:tcp://localhost/~/activiti and not jdbc:h2:tcp://localhost/activiti thanks to pozzad member for the information.]
Figure 3 – The H2 DB page, for an empty DB
Well, now shutdown the H2 DBMS and shutdown Tomcat.
Configure Activiti Explorer for the H2 Database
We want the Activiti Explorer application to not use the in memory database any longer, and use the H2 instance active on the host. In order to do this, edit the <tomcatinstalldir>\webapps\activitiexplorer\WEBINF\classes\db.properties file.
Change the line:
jdbc.url=jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000
in the following way:
jdbc.url=jdbc:h2:tcp://localhost/activiti
Now, first start H2 RDBMS, and then start Tomcat. When Tomcat is up, try to connect to the Activitiexplorer page and login. If the login succedes, the Activiti-explorer is connected to the H2 instance. Go to the H2 web console page as seen before, and connect to the database, you should find what reported in Figure 4.
Figure 4 – The H2 DB populated with some Activiti tables
Now the database is populated with several tables. With the H2 web console page, you can explore the tables and their content.
The Eclipse Project
Our goal is to run the two exercises in the first chapter of the Activiti in Action book. In this section, we'll do this by scratch, that is, we're not using the book source code available from http://www.bpmnwithactiviti.org/book_sourcecode.html.
Nevertheless, I suggest to download the source code pack because we will start a new project and copypaste some files and/or code snippets. Let's start. From Eclipse, start a new Activiti project with the File/New/Other command.
Figure 5 – Eclipse wizard for a new Activiti project
In the dialog window (see Fig. 5), select Activiti Project. Follow the wizard and complete the project creation. In my example, the project name is StartWithActiviti. You should see the new project in the Eclipse workspace explorer, the project's structure should be as depicted in Figure 6.
Figure 6 – Activiti project's structure
In the figure, you can see the pom.xml file, but in this article, we don't care about maven (and everything will work), so please ignore it. Now we have to populate the Activiti project with the files. All the needed files can be copy-pasted from the book's source code pack, in this mentioned pack, you shall find the files (with a find tool) starting only from the bpmnexamples folder.
Files are:
- bookorder.bpmn20.xml
- bookorder.simple.bpmn20.xml
- log4j.xml
- BookOrderTest.java
- SimpleProcessTest.java
- activiti.cfg.xml
Files 1, 2 and 3 shall be placed into src/main/resources, files 4 and 5 shall be placed into src/test/java, file 6 shall be placed into src/test/resources. After have imported these files (through the copy-paste), your project's structure should look like this (Figure 7):
Figure 7 – Project populated with files
Configure Eclipse for the Test
Be sure that JUnit 4 is added to the project. In order to do this, right click on the project and select Properties, the project properties dialog box appears, see figure 8.
Figure 8 - Project's properties for Eclipse
On the left list, select Java Build Path and on the right pane select the Libraries tab, as reported in the image. In the list, you should see JUnit 4. If not, push on the Add Library button on the right. A miniwizard will guide you to add the library and obtain the result reported in the library.
Now we have to add the Activiti libraries to the project. You should be in:
- project's properties dialog box
- Java Build Path pane
- Libraries tab
Push the Add External JARs button and select and import all the libraries in the <activitipack>/libs folder. Then, push again the Add External JARs button and select and import all the libraries in the <tomcatinstalldir>\webapps\activitiexplorer\WEBINF\lib folder, except all file whose name starts for activitiin order to avoid duplications. If you import all jars in the last mentioned folder, you will have a warning for the duplicated jars, NOT a blocking error.
Finally, a little hack on the java files, if you imported them as described up to now. In both files, comment the line:
package org.bpmnwithactiviti.chapter1;
in order to obtain:
// package org.bpmnwithactiviti.chapter1;
In the SimpleProcessTest.java file, change the
repositoryService.createDeployment()
.addClasspathResource("chapter1/bookorder.simple.bpmn20.xml")
.deploy();
fragment in:
repositoryService.createDeployment()
.addClasspathResource("bookorder.simple.bpmn20.xml")
.deploy();
We have changed the XML file path to adapt it to our project. Do the same adaption (remove the "chapter1/" substring) to the BookOrderTest.java file. Now your two Java files should appear in the Eclipse editor with no errors, as in Figure 9.
Figure 9 – Project's structure with no errors
Run the SimpleProcessTest File
All is ready for the first exercise test. Right click on the SimpleProcessTest.java file and then select Run As/JUnit Test. You should see the successful result as in figures 10 and 11.
Fig. 10 – Console output for the Junit test
Figure 11 – Junit console output
What's happening up to now? This test has been executed using an in memory H2 database, not the H2 instance active on the host, so no matter if the H2 DBMS is active or not. We can see this in memory choice by this instruction in the code:
@Test
public void startBookOrder() {
ProcessEngine processEngine = ProcessEngineConfiguration
.createStandaloneInMemProcessEngineConfiguration()
.buildProcessEngine();
Run the BookOrderTest File
The second exercise test does not use the in-memory DB, so we will experience the complete path proposed by the first chapter of Activiti in action. Be sure that H2 DBMS and Tomcat are running (start first H2 and then Tomcat), right click on the BookOrderTest.java file, select Run As/JUnit Test, wait some seconds. You should see the successful result as for the previous test.
Go to the Activiti Explorer page http://localhost:8080/activiti-explorer/ and log in as kermit user. You should see the user page, with something waiting in the user queue, as reported in Figure 12.
Figure 12 – Activiti Explorer with a queued task
Click on the Queued link, then click on Sales and you will see your task. That's all.
Conclusions
Don't hesitate to contact me on the forum below for any kind of feedback about this article. I apologize for my limited communication capabilities, as I'm not a native English speaker, I'm Italian. But I care about the quality of the explanation, so please give me feedback also for the linguistic point of view.
[1] Activiti in Action, Executable business processes in BPMN 2.0. Tijs Rademakers – Mannings 2012
History
- 19th December, 2013: Initial version
