camunda BPM and the Spring Framework

What will you learn?

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

Set up
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 to resolve 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.

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-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 repository.

Set up your Project

We will start by setting up a Spring web application as an 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 the web.xml file for bootstrapping the Spring container
  4. Add a Spring application context XML configuration file

In the following sections, 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 to the left illustrates the settings we choose. As we are deploying a web application, make sure to select Packaging: war.

If you are unfamiliar with setting up a Maven project, read the Set up your Project section of the 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 of 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 the camunda BPM and the 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 (preexisting) src/main/webapp folder of your 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:

Set up complete!

Congratulations, you have completed the project setup. Your project should now look as depicted in the screenshot to 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 set up 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 cloned the repository yet, 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 cloned the repository yet, 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

  1. Model an executable BPMN 2.0 process.
  2. Use Spring auto-deployment for BPMN 2.0 processes.
  3. Start a process instance from a Spring bean.
  4. Invoke a Spring bean from a BPMN 2.0 Service task.

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 to the left.

If you are unfamiliar with modeling an executable process, you can read the Model a Process section of the Developing Process Applications tutorial.

When you are done, save the process model.

Use Spring auto-deployment for BPMN 2.0 processes

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 provide 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 SpringProcessApplication. This feature works with both the embedded process engine (as used in this tutorial) as well as the shared process engine. In order to use the META-INF/processes.xml based deployment, you must make the following changes in 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 of starting a process instance from a Spring Bean. We will simply add a Spring Bean to the application context which injects to 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 to 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 cloned the repository yet, 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 explore how to set up an embedded process engine inside a web application using the Spring Framework. You can also use the Spring Framework to develop 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 so 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 cloned the repository yet, 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.