Camunda SpringBoot Starter -1

Published in

turkcell

4 min readAug 22, 2021

Introduction

Camunda is one of the most popular BPMN Engine which is developed with Java. It offers a Bpmn Engine, Web Interface and the Rest API as a whole product. You can even develop bpmn flows without coding any Java, but when it comes to do more complex applications, it’s better to use it in a SpringBoot project because it already has a spring boot starter package to support all these features.

Add Dependency

What I like with camunda springboot starter is that you don’t have to import all packages and can choose between them depending on your needs. The requirement I had in my project was only to use the bpmn engine and the rest api. So in pom.xml file, I only included rest api dependency. Bpmn engine comes together with the rest api.

It is also possible to include the webapp dependency which starts you a web application where you can easily develop form-based flows and manage them. Please note that webapp is out of scope for the whole series of these articles.

How to use Rest API

When the spring boot application starts up, you will have a rest api provided by camunda where you can have access to it with below url.

http://localhost:8080/engine-rest

There is a detailed documentation about the provided rest methods in the camunda official website. Basically, you can deploy bpmn files, start new process instance, complete user interaction tasks and achieve much more tasks by using the rest api. If you don’t have complex requirements, I believe rest api is more than enough for you.

Documentation says that the REST API ships with an implementation of HTTP Basic Authentication. By default it is switched off, but can be activated by adding a servlet filter. You can simply add below security configuration filter class to enable it.

Then what you have to do is to add below parameters into your application.properties file.

camunda.bpm.admin-user.id=admin
camunda.bpm.admin-user.password=pazzword

Now you will need to use these credentials in an http basic authentication method along with your rest calls.

For instance, you can get a count for deployed process definitions with below rest api call.

curl -u admin:pazzword -H “Accept: application/json” -H “Content-Type: application/json” http://localhost:8080/engine-rest/process-definition/count
{“count”:1}

Database Configuration

Camunda heavily depends on database because all information related to process definitions and running process instances is stored in the database. It is important to use process variables and transactions wisely not to have any performance issues.

On the other hand, because all transaction is persisted into database, camunda can work in a stateless manner which makes it possible to be used without any issues in a containerized structure inside any cloud environment such as Kubernetes, Azure or AWS.

Camunda uses the primary datasource in spring context as its database connection provider. So basically you don’t need to do anything else but just configure a datasource in the application.properties file.

spring.datasource.url= jdbc:mysql://127.0.0.1:3306/myapp
spring.datasource.username=root
spring.datasource.password=pass1234

Camunda is already compatible with almost all popular databases (oracle, mysql, maria, postgresql, mssql, db2, h2). So you can simply enable schema update property to true and camunda creates the required tables in the database on application start.

camunda.bpm.database.schema-update=true

If you need to use a different schema name for the tables, then you have to manually create the tables under this schema and set below parameters.

camunda.bpm.database.table-prefix=myschema.
camunda.bpm.database.schema-name=myschema

At the time of this article being written, camunda does not support schema name change and schema update properties together.

How to deploy BPMN files

There are 2 ways to deploy a bpmn file.

First way is to have EnableProcessApplication annotation in your springboot main class. You also need to have a META-INF/processes.xml file in your resources in your classpath. By doing so, camunda will scan your classpath and look for bpmn files to deploy on application start.

processes.xml file might even be empty, but has to be there without a doubt. If it is empty, camunda uses default values for auto-deploy. Defaults values are as below.

This method of deployment requires a server restart and doesn’t sound very pleasant if you update your bpmn files too often.

Second way to deploy a bpmn file is to use the rest api. Rest api offers a method to deploy bpmn files on the fly which means you don’t need to restart the server. Below is a sample curl command shows how to use it.

curl -u admin:pazzword -H “Content-Type: multipart/form-data” -H “Connection: keep-alive” -F “deployment-name=mySampleBpmn” -F “deployment-source=mySampleBpmn” -F “*=@sample.bpmn” http://localhost:8080/engine-rest/deployment/create

Camunda Service Beans

The best thing when using camunda with spring boot is to be able to customize the configuration and use autowired service beans as you like, so that you can develop your own methods to accomplish something when the camunda rest api does not meet your requirement.

You can easily have access to TaskService, RuntimeService, FormService or RepositoryService of camunda by autowiring them in your service class.

There are more services attached to camunda’s ProcessEngine bean.

This is a big opportunity to develop your own methods on top of camunda engine. See an example below which gives the list of running process instance list. This method uses camunda’s runtimeService.

Another example which starts a process instance by key is as below.

Sum Up

Here is the github link where you can find the project covering all the content mentioned in this post. You can check my following posts related to camunda and springboot.