Sunday, October 17, 2010

BPMN 2.0 with Activiti - book order tutorial (2)

Step 2 - Adding a start form to the process

In a small series of posts we will show how to get started with Activiti BPMS by getting a simple book order process running on Activiti Engine. All the BPMN 2.0 constructs that the Activiti Engine currently supports will be addressed in the coming few weeks.

In the process model below you can see the Java Service Task that was implemented in the previous post. That time the 'bookTitle' variable was set from within a unit test, today we will add a start form to the process which lets a user fill in a book title in the Activiti Explorer.

Before we start working with eclipse, to define the process and the form, install Activiti. In this example the beta 2 release of Activiti is used. Download it and unzip the file in a directory. Check out the user guide for more information, but for now it is enough to run the ant demo.setup task to get the engine running. When ant is all done a Tomcat distribution is downloaded and started and the Activiti apps are installed.

With Tomcat running silently in the background it is time to open eclipse. Since the BPMN 2.0 spec does not specify how task forms should be rendered, forms are defined in the bpmn xml file using Activiti specific constructs. The xml below shows how to add the bookorder.form to the start event in the book order process.
<process id="bookorder">
<startEvent id="theStart" activiti:form="bookorder.form"/>
<sequenceFlow id="flow1" sourceRef="theStart"
targetRef="checkAvailability" />
<serviceTask id="checkAvailability"
name="Availability Check"
activiti:class="org.bpmnwithactiviti.CheckAvailability" />
<sequenceFlow id="flow2" sourceRef="checkAvailability"
targetRef="waitState" />
<receiveTask id="waitState" />
<sequenceFlow id="flow3" sourceRef="waitState"
targetRef="theEnd" />
<endEvent id="theEnd" />
The task forms that can be rendered by the Activiti Explorer are just plain html files. By convention they have the .form extension. The form that we are going to use is very simple and just has an inputfield to enter the title of the book that we want to order. The variable in the form, in this case the 'bookTitle' variable, will be stored as process variables after completion of the task. The variables must be camel-cased. Currently supported are String, Integer, Boolean and Date, String is the default type.
<h1>Book Order</h1>
<label>Book title:
<input type="text" name="bookTitle" value="" />
<input type="hidden" name="bookTitle_required" value="true" />
<input type="hidden" name="bookTitle_type" value="String" />
Now that the form and the bpmn xml is ready we can package these files in a business archive, the deployable unit on Activiti Engine. This you can do by exporting the eclipse project with the jar file export wizard. Select only the bpmn xml file and the form and name the file To deploy the archive we will create a simple J2SE class with a main method.
public class BarDeployer {
public static void main(String[] args) throws Exception {
ProcessEngine processEngine = new ProcessEngineBuilder()
RepositoryService repositoryService = processEngine.getRepositoryService();
String barFileName = "";
ZipInputStream inputStream = new ZipInputStream(new FileInputStream(barFileName));
Note that we now use a different file to build the process engine. Since deployment will take place on the Activiti Engine installation running on Tomcat a different config is needed than the one used in our previous unit test.

Now that the bar file is deployed you can see the installed bookorder process with Activiti Explorer on http://localhost:8080/activiti-explorer/. Login as kermit with password kermit and take a look at the processes he can start. On the top of the list you see the Book Order process.

Before you can start the process you need to deploy a jar file that contains the CheckAvailability class file in the Tomcat lib directory and restart Tomcat, otherwise the engine can't find the class that implements the Java Service Task we build in the previous post.

Note that the Action behind the Book Order process is not 'Start Process' but 'Start Form'. Only when we have put in a book title in the form and pressed the 'Ok' button a process instance is created and the 'bookTitle' variable is set.

When you submit the form you can see some logging appearing in de Tomcat log file telling you whether the book is available or not. The code of the BookOrder project, including the bar and jar file, can be checked out from the Google Code repository.

That was it for now, next time we will take a look at gateways!


  1. Can you post a Screen Shot of your Eclipse project hier please? And what does it mean "we now use a different". What is the deferent ans where should i place it?

  2. Hi Alexej, When I referred to 'a different' file I meant different in relation to the earlier post with the Java Service Task example. There we used an in-memory database and in this example you need the regular one:


    I will publish a new post in a few days and make sure then that the google code repository has all the code you need.

  3. Hi. I have this problem I´m using external form and when I put this formKey in the same doesn´t work. What is the problem? Kind regards, Pablo.

  4. Hi,

    With the new releases of Activiti the external form file is succeeded by defining form properties in the process definition itself. This is described in the Activiti user guide.

    Best regards,


  5. Thanks for the help! I have also found a BPMN 2.0 Tutorial for Beginners that is very user friendly through lucidchart!