This tutorial guides you through your first steps in using camunda BPM in a Spring Web application.
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.
We will start with setting up a Spring Web application as Apache Maven Project inside Eclipse. This consists of four steps:
In the following, we go through this process step by step.
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
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.
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:
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
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
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:
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.
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
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
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
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.
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
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
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
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
We add the Spring bean to the applicationContext.xml file:
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
Finally we add the Java class implementing the
And register it as a Spring Bean in the application context.
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.
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 dependency
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: