Running Spring Boot Applications with the Embedded Camunda Engine

1. Overview

The workflow engine plays an important role in business process automation. Camunda platform is an open-source workflow and Business Process Management System (BPMS) that provides a process engine for Business Process Modeling. Spring Boot has good integration with the Camunda platform. In this tutorial, we’re going to look at how we can leverage the embedded Camunda engine into the Spring Boot application.

2. Camunda Workflow Engine

The Camunda workflow engine is a fork of Activiti and provides a workflow and simulation engine based on the Business Process Modelling Notation 2.0 (BPMN 2.0) standard. Moreover, it consists of tools and APIs for modeling, execution, and monitoring. Firstly, we can model our end-to-end business processes using Modeler. The Camunda provides the Modeler for designing BPMN workflows. The Modeler runs locally as a desktop application. Then, we deploy the business process model to the workflow engine and execute it. We can execute a business process in different ways using the REST APIs and provided Web Applications (Cockpit, Tasklist, and Admin). The Camunda engine can be used in different ways: SaaS, Self-Managed, and Embeddable library. In this tutorial, we focus on the Camunda embedded engine in a Spring Boot application.

3. Creating a Spring Boot Application with Embedded Camunda Engine

In this section, we will create and configure the Spring Boot application with an embedded Camunda engine using the Camunda Platform Initializr.

3.1. Camunda Platform Initializr

We can create a Spring Boot application integrated with the Camunda engine using the Camunda Platform Initializr. It is a web-application tool that is provided by Camunda, similar to Spring Initializr. Let’s create the application with the following information in the Camunda Platform Initializr: The tool lets us add our project metadata, including Group, Artifact, Camunda BPM Version, H2 Database, and Java Version. Also, we can add Camunda BPM Modules for supporting Camunda REST APIs or Camunda Webapps in our Spring Boot application. In addition, we can add Spring Boot Web and Security modules. The other option we have is to set Admin Username and Password, which is required for use in a Camunda Webapps such as Cockpit application login. Now, we click Generate Project to download the project template as a .zip file. Finally, we extract the files and open pom.xml in our IDE.

3.2. Camunda Configuration

The generated project is a regular Spring Boot application with extra Camunda dependencies and configurations. The directory structure is depicted in below figure:

There is a simple workflow diagram process.bpmn in the resources directory. It starts executing the process using the start node. After that, it’ll proceed with the Say hello to demo task. On the completion of this task, the execution stops upon encountering the final node. The Camunda properties exist in application.yaml. Let’s take a look at the generated default Camunda property in the application.yaml:

camunda.bpm.admin-user:
  id: demo
  password: demo

We can change the admin username and password using camunda.bpm.admin-user property.

4. Creating the Application with Spring Boot

Another way of creating the Spring Boot application with an embedded Camunda engine is by using Spring Boot from scratch and adding the Camunda library to it.

4.1. Maven Dependencies

Let’s start by declaring the camunda-bpm-spring-boot-starter-webapp dependency in our pom.xml:

<dependency>
    <groupId>org.camunda.bpm.springboot</groupId>
    <artifactId>camunda-bpm-spring-boot-starter-webapp</artifactId>
    <version>7.18.0</version>
</dependency>

We need a database to store the process definitions, process instances, history info, etc. In this tutorial, we use a file-based H2 database. Therefore, we need to add h2 and spring-boot-starter-jdbc dependencies:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

4.2. Sample Process Model

We use the Camunda Modeler to define a simple loan request workflow diagram loanProcess.bpmn. Here is a graphical flowchart of the execution order of the loanProcess.bpmn model to aid in our understanding:

We start executing the process using the start node. After that, the Calculate Interest task is executed. Next, we’ll proceed with the Approve Loan task. On the completion of this task, the execution stops upon encountering the final node. The Calculate Interest task is a service task and invokes the CalculateInterestService bean:

@Component
public class CalculateInterestService implements JavaDelegate {

    private static final Logger LOGGER = LoggerFactory.getLogger(CalculateInterestService.class);

    @Override
    public void execute(DelegateExecution execution) {
        LOGGER.info("calculating interest of the loan");
    }

}

We need to implement the JavaDelegate interface. This class can be used for both service tasks and event listeners. It provides the required logic in the execute() method to be called during process execution. Now, the application is ready to start.

5. Demonstration

Now let’s run the Spring Boot application. We open the browser and enter the URL http://localhost:8080/:

Let’s enter user credentials and access the Camunda web applications Cockpit, Tasklist, and Admin:  

5.1. Cockpit Application

The Camunda Cockpit web application provides the user’s facilities to monitor a real-time view of the implemented process and its operations. We can see the number of processes deployed automatically when the Spring Boot application is started:   As we can see, there is one deployed process (loanProcess.bpmn). We can view deployed process diagram by clicking on the deployed process:   Now, the process is not started. We can start it using the Tasklist application.

5.2. Tasklist Application

The Camunda Tasklist application is used to manage user interactions with their tasks. We can start our sample process by clicking the Start process menu item:   After starting the process, the Calculate Interest task is executed. It logs into the console:

2022-11-27 09:34:05.848  INFO 2748 --- [nio-8080-exec-3] c.e.c.task.CalculateInterestService      : calculating interest of the loan

Now, we can see the running process instance in the Cockpit application:   Note that the process is waiting for the Approve Loan user task. In this step, we assign the task to the demo user. So, the demo user can see the task in the Tasklist application: We can complete the task by clicking the Complete button. Finally, we can see the running process is completed in the Cockpit application.

5.3. Admin Application

The Camunda Admin application is used to manage the users and their access to the system. Also, we can manage the tenants and groups:

6. Conclusion

In this article, we discussed the basics of setting up a Spring Boot application with an embedded Camunda engine. We created the application using the Camunda Platform Initializr tool and Spring Boot from scratch. Also, we define a simple loan request process model using Camunda Modeler. Moreover, we start and explore this process model using the Camunda web applications.