Developing Process Applications

What will you learn

This tutorial guides you through setting up camunda BPM and developing your first process application. You will learn to

Install
the camunda BPM platform and camunda Modeler on your machine. In this tutorial we use the Apache Tomcat based distribution.
Set up
an Apache Maven-based process application inside eclipse and deploy it to the camunda BPM platform.
Model
We cover the basics of handling the camunda modeler for eclipse and you will learn how to model and configure a fully executable process.
Create Task Forms
We will explore the simplest possible kind of task forms available in camunda BPM. This will give you a jump start for bootstrapping simple processes.
Add Java Services
You will learn how to add a Java class to your process application and reference it from a BPMN Service Task in the process.

Download and Installation

Before you start
Make sure you have the following set of tools installed:

  • Java JDK 1.6+
  • Apache Maven (optional, if not installed you can use embedded Maven inside eclipse.)
  • A modern Web browser (recent Firefox, Chrome, or Internet Explorer 9+ will work fine)

Install camunda BPM platform

First, download a distribution of the camunda BPM platform. You can choose from different distrubitions for various application servers. In this tutorial, we will use the Apache Tomcat 7 based distribution. Download it here.

After having downloaded the distribution, unpack it inside a directory of your choice. We will call that directory $CAMUNDA_HOME.

After you have successfully unpacked your distribution of the camunda BPM platform, execute the script named start-camunda.bat (for Windows users), respectively start-camunda.sh (for Unix users).

This script will start the application server and open a welcome screen in your Web browser. If the page does not open, go to http://localhost:8080/camunda-welcome/index.html.

Getting Help: If you have trouble setting up the camunda BPM platform, you can ask for assistance in the Process Application Development Forum.

Install the camunda Modeler

Follow the instructions in the camunda Modeler section.

Join in: Get the Sources for this guide.

Download as .zip or checkout the corresponding tag with Git.

In addition to this guide, the source code of the example project is also available on GitHub. You can directly download the whole project or clone it with git:
git clone https://github.com/camunda/camunda-get-started.git
To follow this guide, download the initial state or checkout the tag in the git repositiory:
git checkout -f Start
or every step in between:
git checkout -f Step-X
After every section in this guide you will find a box which contains a download link to the current state of the project and git instructions to checkout the current version of the repository.

Set up your project

Now you are ready to set up your first process application project in eclipse. Setting up a process application project consists of 4 steps:

  1. Create a new Maven Project in Eclipse
  2. Add the camunda dependencies
  3. Add a @ProcessApplication class
  4. Add a META-INF/processes.xml deployment descriptor

In the following sections, we go through this process step by step.

Create a new Maven Project in Eclipse

In eclipse, go to File / New / Other .... This opens the New Project Wizard. In the New Project Wizard select Maven / Maven Project. Click Next.

On the first page of the New Maven Project Wizard select "Create a simple project (skip archetype selection)". Click Next.

On the second page (see screenshot), configure the Maven coordinates for the project.

Since we are setting up a WAR Project, make sure to select Packaging: war.

When you are done, click Finish. Eclipse sets up a new Maven project. The project appears in the Project Explorer View.

Add camunda Maven Dependencies

The next step consists of setting up the Maven dependencies for your new process application. Add the following dependencies to the pom.xml file of your project:

Now you can perform the first build. Select the pom.xml in the Package Explorer, perform a right-click and select Run As / Maven Install

Catch up: Get the Sources of Step-1.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

If you have not cloned the repository yet, please execute the following command:

git clone https://github.com/camunda/camunda-get-started.git

To checkout the current state of the process application please execute the following command:

git checkout -f Step-1
Or download as archive from here.

Add a Process Application Class

Next, you need to create a package, e.g. org.camunda.bpm.getstarted.loanapproval and add a Process Application class to it. The Process Application class constitutes the interface between your application and the process engine.

In an EJB Container, use an EJB Process Application:

Add a META-INF/processes.xml deployment descriptor

The last step to set up the process application is to add the META-INF/processes.xml deployment descriptor file. This file allows us to provide a declarative configuration of the deployment(s) this process application makes to the process engine.

This file needs to be added to the src/main/resources/META-INF folder of the Maven project.

You can leave the META-INF/processes.xml file empty. In that case, default values are used. See the Empty Processes.xml section of the User Guide for more information


At this point you have successfully set up the process application and you can start modeling the first process.

Catch up: Get the Sources of Step-2.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

If you have not cloned the repository yet, please execute the following command:

git clone https://github.com/camunda/camunda-get-started.git

To checkout the current state of the process application please execute the following command:

git checkout -f Step-2
Or download as archive from here.

Model a Process

In this section you learn how to create your first BPMN 2.0 process with the camunda Modeler.

Create a new BPMN 2.0 diagram

In the eclipse Package Explorer select the src/main/resources folder. Right-click and select New > Other .... Go to the folder Other and select BPMN 2.0 Diagram. Click Next.

On the second page, you must specify the file name of the process. Insert loan-approval.bpmn. Click Finish.

Start with a Simple Process

Start by modeling a simple process. From the Palette on the right hand side of the canvas, drag a Start Event onto the canvas.

Double-click on the label of the Start Event. A text box opens. Type "Loan Request Received".

When editing Labels, you can add line breaks by hitting Shift + Enter.

Add a User Task to the process. Name it "Approve Loan". Add an End Event named "Loan Request Approved".

Configure a User Task

Next, Open the properties view. If the properties view is not visible, select it from the menu: Window / Show View / Other ... This opens a dialog. From the dialog select Properties.

Select the User Task on the canvas. This updates the selection in the Properties View. Scroll to the Property named Assignee. Type "john".

When you are done, save your changes.

Configure an executable Process

Since we are modeling an executable process, we should give it an ID and set the isExecutable property to true. Open the properties view and click on a free spot of the modeling canvas. This displays the properties of the process itself.

  1. First, configure an ID for the process. Type "approve-loan" in the property field Process Id. The property ID is used by the process engine as identifier for the executable process and it is best practice to set it to a human-readable name.
  2. Second, configure the Name of the process. Type "Loan Approval" in the property field Name.
  3. Finally, check the box of the Is Executable property. If you do not check this box, the process definition is ignored by the process engine.

When you are done, save your changes.

Catch up: Get the Sources of Step-3.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

If you have not cloned the repository yet, please execute the following command:

git clone https://github.com/camunda/camunda-get-started.git

To checkout the current state of the process application please execute the following command:

git checkout -f Step-3
Or download as archive from here.

Deploy the Process Application

A Process Application is an ordinary Java Web Application and is deployed in exactly the same way.

Select the pom.xml in the Package Explorer, perform a right-click and select Run As / Maven Install. This will generate a WAR file named loan-approval-0.0.1-SNAPSHOT.war In the target/ folder of your Maven project.

If the loan-approval-0.0.1-SNAPSHOT.war file is not visible after having performed the Maven build, you need to refresh the project (F5) in eclipse.

Deploy to Apache Tomcat

In order to deploy the process application, copy-paste the loan-approval-0.0.1-SNAPSHOT.war from your Maven project to the $CAMUNDA_HOME/server/apache-tomcat/webapps folder.

Check the log file of the Apache Tomcat server. If you see the following log message, the deployment was successful:

      16.03.2013 22:42:11 org.camunda.bpm.application.impl.ServletProcessApplicationDeployer onStartup
      INFO: Detected @ProcessApplication class org.camunda.bpm.getstarted.loanapproval.LoanApprovalApplication
      16.03.2013 22:42:11 org.camunda.bpm.container.impl.jmx.deployment.ParseProcessesXmlStep performOperationStep
      INFO: Found META-INF/processes.xml file at ...webapps/loan-approval-0.0.1-SNAPSHOT/WEB-INF/classes/META-INF/processes.xml
      16.03.2013 22:42:11 org.camunda.bpm.container.impl.jmx.deployment.DeployProcessArchiveStep logDeploymentSummary
      INFO: Deployment summary for process archive 'loan-approval':

      loan-approval.bpmn

      16.03.2013 22:42:11 org.camunda.bpm.engine.impl.bpmn.deployer.BpmnDeployer deploy
      INFO: Processing resource loan-approval.bpmn
      16.03.2013 22:42:11 org.camunda.bpm.container.impl.jmx.JmxRuntimeContainerDelegate deployProcessApplication
      INFO: Process Application Loan Approval App successfully deployed.
    

Check with camunda Cockpit and Tasklist

Now use cockpit to check if the process is successfully deployed. Go to http://localhost:8080/camunda/app/cockpit. Your process is visible on the start screen.

Next, go to camunda Tasklist (http://localhost:8080/camunda/app/tasklist). Log in with demo / demo. After you have logged in, click on the button to start a process instance. Select Loan Approval from the list. This opens a page which explains that no form has been defined for starting the process. Click on Start process using generic form.

The generic form can be used whenever you have not added a dedicated form for a User Task or a Start Event. Click on the button to get a new row. Fill in the form as shown in the screenshot. When you are done, click .

If you now go back to camunda Cockpit, you see the newly created process instance that is waiting in the User Task.

Log out of the Tasklist and log back in with the user credentials "john / john". Now you see the Approve Loan task in your inbox. Click on the button. This displays the process diagram highlighting the User Task that is waiting for you to work on it.

To work on the task, click the button. Again, there is no task form associated with the process. Click on Work on task using generic form. This displays the variables you have put in in the first step.

Add Task Forms

In the next step, we want to add an actual Task Form.

Add a Start Form

Go back to eclipse and add a folder named src/main/webapp/forms. Inside this folder, add a file named request-loan.html. Add the following content:

Configure the Start Form in the Process

Open the process with the modeler plugin. Click on the start event. In the properties view, insert embedded:app:forms/request-loan.html into the Form Key property field. This means that we want to use an embedded form inside the Tasklist and that the form is loaded from the application.

Add a Task Form

The Task Form can be added and configured the same way. Add a file named approve-loan.html to the src/main/webapp/forms directory and add the following content:


After that, open the process with the modeler plugin again. Click on the user task. In the properties view, insert embedded:app:forms/approve-loan.html into the Form Key property field.

When you are done, save all resources, perform a Maven build and redeploy the process application.

Maven: It is best practice to perform a clean install build to make sure all resources are replaced with their newest version.

Now you can open the Tasklist and start a new process instance for the loan approval process. You will notice that the custom form is displayed.

Catch up: Get the Sources of Step-4.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

If you have not cloned the repository yet, please execute the following command:

git clone https://github.com/camunda/camunda-get-started.git

To checkout the current state of the process application please execute the following command:

git checkout -f Step-4
Or download as archive from here.

Add a Service Task

In the last section of this tutorial we add some code to the process.

Add a Service Task to the Process

Use the camunda modeler plugin in eclipse to add a service task after the user task. The service task can be dropped on a sequence flow (see screenshot).

Add a JavaDelegate Implementation

Now we need to add the actual service task implementation. Add a class named ProcessRequestDelegate implementing the JavaDelegate interface:

Configure the Class in the Process

Use the properties view to reference the Service Task in the process (see screenshot). You need to provide the fully qualified classname of your class in the class property field.

Build, deploy and execute the process. After completing the Approve Application step, check the logfile of the Apache Tomcat server:

17.03.2013 08:42:14 org.camunda.bpm.getstarted.loanapproval.ProcessRequestDelegate execute
INFO: Processing request by 'AC-343422'...
    

The process engine resolves the ProcessRequestDelegate class from the process application classloader. This allows you to

  • have a different classloader for each Process Application,
  • bundle libraries inside your application,
  • (re-)deploy the application at runtime (without stopping / restarting the process engine).

Catch up: Get the Sources of Step-5.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

If you have not cloned the repository yet, please execute the following command:

git clone https://github.com/camunda/camunda-get-started.git

To checkout the current state of the process application please execute the following command:

git checkout -f Step-5
Or download as archive from here.

You made it!

Congratulations, you have now successfully deployed your first Process Application!

Where to go from here?