Getting Started

With camunda BPM and the Spring Framework

What will you learn?

This tutorial guides you through your first steps in using camunda BPM in a Spring Web application.

Setup
A Spring Web application project as an Apache Maven project.
Configure
The camunda process engine and embed it inside your application.
Deploy
Your project to a vanilla Apache Tomcat server.
Add Spring Task
Learn how to use UEL Expressions for resolving Spring Beans from the BPMN 2.0 process.
Adapt
Your project to use a Shared Process Engine and deploy it to the camunda BPM enhanced Tomcat server.

Before you start
In this tutorial we assume that you are familiar with the Basics of Java Web application development and the Spring Framework. We also assume that you have installed an eclipse distribution and the camunda modeler.

Join in: Get the Sources for this guide.

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

Additionally to this guide is the source code of the example project 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-spring.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 repositiory.

Setup your Project

We will start with setting up a Spring Web application as Apache Maven Project inside Eclipse. This consists of four steps:

  1. Create a new Maven Project in Eclipse
  2. Add the camunda & Spring framework dependencies
  3. Add web.xml file for bootstrapping the Spring container
  4. Add a Spring application context XML configuration file

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

Create a new Maven Project in Eclipse

First, we set up a new Apache Maven based project in eclipse. Let's call it loanapproval-spring. The screenshot on the left illustrates the settings we choose. Since we deploy a Web application, make sure to select Packaging: war.

If you are unfamiliar with setting up a Maven project, read the Setup your Project Section in the Getting started developing process applications tutorial.

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

Add camunda BPM & Spring Framework dependencies

The next step consists in setting up the Maven dependencies for the new project. Maven dependencies need to be added to the pom.xml file of the project. We add both camunda BPM and Spring Framework dependencies:

Add web.xml file for bootstrapping the Spring container

Next, we add a web.xml file for bootstrapping the spring container. In order to do so, first add a folder named WEB-INF to the (already existing) src/main/webapp folder of you Maven project. Inside this folder, add a file named web.xml:

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

Add a Spring application context XML configuration file

Next, we add a Spring ApplicationContext XML file to the same src/main/webapp/WEB-INF folder. The file must be named applicationContext.xml. We start with an empty file:

Setup complete!

Congratulation, you have completed the project setup. Your project should now look as depicted in the screenshot on the left.

You can now perform a full Maven build and deploy the project to a vanilla Apache Tomcat server. You should see the following log output:

28.04.2013 15:11:02 org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive C:\demo\apache-tomcat-7.0.39\webapps\loanapproval-spring-0.0.1-SNAPSHOT.war
28.04.2013 15:11:03 org.springframework.web.context.ContextLoader initWebApplicationContext
INFO: Root WebApplicationContext: initialization started
28.04.2013 15:11:03 org.springframework.context.support.AbstractApplicationContext prepareRefresh
INFO: Refreshing Root WebApplicationContext: startup date [Sun Apr 28 15:11:03 CEST 2013]; root of context hierarchy
28.04.2013 15:11:03 org.springframework.beans.factory.xml.XmlBeanDefinitionReader loadBeanDefinitions
INFO: Loading XML bean definitions from ServletContext resource [/WEB-INF/applicationContext.xml]
28.04.2013 15:11:03 org.springframework.beans.factory.support.DefaultListableBeanFactory preInstantiateSingletons
INFO: Pre-instantiating singletons in org.springframework.beans.factory.support.DefaultListableBeanFactory@1a8dfb3: defining beans []; root of factory hierarchy
28.04.2013 15:11:03 org.springframework.web.context.ContextLoader initWebApplicationContext
INFO: Root WebApplicationContext: initialization completed in 170 ms
    

This means that you have setup your Spring web application correctly.

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 already cloned the repository please execute the following command:

git clone https://github.com/camunda/camunda-get-started-spring.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.

Configure an Embedded Process Engine

Now that you have set up the project with the correct Maven dependencies, we can start configuring the process engine. Add the following Spring beans configuration to the src/main/webapp/WEB-INF/applicationContext.xml file:

After you added these definitions to the Spring Application context, perform a full Maven build and redeploy the application. In the logfile of the Apache Tomcat server you should be able to see the initialization of the process-engine:

28.04.2013 15:33:04 org.camunda.bpm.engine.impl.db.DbSqlSession executeSchemaResource
INFO: performing create on engine with resource org/camunda/bpm/engine/db/create/activiti.h2.create.engine.sql
28.04.2013 15:33:04 org.camunda.bpm.engine.impl.db.DbSqlSession executeSchemaResource
INFO: performing create on history with resource org/camunda/bpm/engine/db/create/activiti.h2.create.history.sql
28.04.2013 15:33:04 org.camunda.bpm.engine.impl.db.DbSqlSession executeSchemaResource
INFO: performing create on identity with resource org/camunda/bpm/engine/db/create/activiti.h2.create.identity.sql
28.04.2013 15:33:04 org.camunda.bpm.engine.impl.ProcessEngineImpl 
  INFO: ProcessEngine default created

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 already cloned the repository please execute the following command:

git clone https://github.com/camunda/camunda-get-started-spring.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.

Add a Spring Bean Service Task

Now that we know how to bootstrap the process engine in a Spring Application context, we can add a BPMN 2.0 process model and interact with the process form inside our Spring beans. In this section we will

Model an executable BPMN 2.0 process

We start by modeling an executable process using the camunda modeler. The process should look as depicted in the screenshot on the left.

If you are unfamiliar with modeling an executable process, you can read the section named Model a Process in the Getting started developing process applications tutorial.

When you are done, save the process model.

Use Spring auto-deployment for BPMN 2.0 processes

In order for the process to be deployed, we use the auto-deployment feature provided by the camunda engine Spring integration. In order to use this feature, modify the definition of the processEngineConfiguration bean inside your src/main/webapp/WEB-INF/applicationContext.xml file:

If you redeploy the application, you should see the following message in the logfile, meaning that the process definition has been picked up and deployed:

INFO: ProcessEngine default created
28.04.2013 16:01:00 org.camunda.bpm.engine.impl.bpmn.deployer.BpmnDeployer deploy
INFO: Processing resource C:\demo\apache-tomcat-7.0.39\webapps\loanapproval-spring-0.0.1-SNAPSHOT\WEB-INF\classes\loanApproval.bpmn
28.04.2013 16:01:01 org.springframework.web.context.ContextLoader initWebApplicationContext
          

The deploymentResources provides basic auto-deployment features. If you need more control over the deployment process, you can use the processes.xml based deployment options in combination with a SpringProcessApplication. This feature works with both the Embedded Process Engine (as used in this tutorial) and a Shared Process Engine. In order to use META-INF/processes.xml based deployment, you must make the following changes to the application context file:

Now you can add a META-INF/processes.xml file:

Start a process instance from a Spring bean

The next step consists in starting a process instance from a Spring Bean. We will simply add a Spring Bean to the application context which injects the process engine and starts a single process instance from an afterPropertiesSet() Method:

We add the Spring bean to the applicationContext.xml file:

Invoke a Spring bean from a BPMN 2.0 Service task

Referencing a Spring Bean from a BPMN 2.0 Service Task is simple. As shown in the screenshot on the left, we have to select the service task in the camunda modeler and provide an expression in the Expression Delegate Field. We type ${calculateInterestService}.

Finally we add the Java class implementing the JavaDelegate interface.

And register it as a Spring Bean in the application context.

If you redeploy the application, you should see the following message in the logfile, meaning that the service task was executed.

INFO: Processing resource C:\demo\apache-tomcat-7.0.39\webapps\loanapproval-spring-0.0.1-SNAPSHOT\WEB-INF\classes\loanApproval.bpmn
Spring Bean invoked
28.04.2013 16:01:01 org.springframework.web.context.ContextLoader initWebApplicationContext
  

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 already cloned the repository please execute the following command:

git clone https://github.com/camunda/camunda-get-started-spring.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.

Done!

This marks the end of this tutorial. You have successfully set up a Spring Application with an embedded process engine. You can deploy this project to virtually any application server.

Where to go from here?

Use shared Process Engine on Apache Tomcat

In this tutorial we explored how to setup an embedded process engine inside a Web application using the Spring Framework. You can also use the Spring Framework for developing applications that use a Shared Process engine. As opposed to the Embedded Process engine, the Shared Process engine is controlled independently from an application and is started / stopped by the runtime container (like Apache Tomcat). This allows multiple applications (or a single modular application) to use the same process engine. You can also re-deploy individual applications independently from the process engine.

In order to configure the loanapproval-spring example to work with an embedded process engine, you have to change three things:

First, we need to set the scope of the Maven dependency of the camunda-engine dependency to provided. On the camunda BPM platform the process engine library is provided as a shared library and does not need to be bundled with the application:

Furthermore, you can delete the dependencies org.springframework:spring-jdbc and com.h2database:h2.

Second, you need to add a META-INF/processes.xml file to your application.

And third, the applicationContext.xml file is adjusted such that the shared process engine is looked up and a SpringServletProcessApplication is bootstrapped:

Catch up: Get the Sources of Bonus.

Download as .zip or checkout the corresponding tag with

You can checkout the current state from the GitHub repository.

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

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

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

git checkout -f Bonus
Or download as archive from here.

We are hiring!