1. What is camunda-bpm-spring-boot-starter?

Spring starters allow to enable behavior of your spring-boot application by adding dependencies to the classpath.

These starters will pre-configure camunda process engine, rest-api and webapp so they can easily be used in a standalone process application.

2. Known issues

  • The camunda-bpm-spring-boot-starter-test used to also reference camunda-bpm-assert.
    After switching to spring-boot v1.5.2, this was not possible because v1.5.2 brings a dependency
    to assertj-core 2.6.0 which is no longer compatible to the outdated version used in the test-extension.
    That’s why we now include the bpm-assert classes directly and compile them with the starter.

    Attention: This means you must not add an additional dependency on camunda-bpm-assert when you
    use the camunda-bpm-spring-boot-starter-test in your test scope! This hopefully will change with following versions.

3. Getting started

If you are not familiar with Spring Boot read the reference documentation getting started guide.

To enable camunda bpm auto configuration add the following dependency:


This will add the camunda version 7.7.0 to your dependencies. If you want to override the version add camunda.version property with the camunda version you want to use and add the camunda bom to the dependency management:


      <!-- Import dependency management from camunda -->

3.1. Examples

You can find examples to learn the usage of the camunda bpm starter here:

4. Process engine configuration

The auto starter uses the org.camunda.bpm.engine.impl.cfg.ProcessEnginePlugin mechanism to configure the engine.

The configuration is divided into sections. These sections are represented by the marker interfaces:

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaProcessEngineConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaDatasourceConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaHistoryConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaHistoryLevelAutoHandlingConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaJobConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaDeploymentConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaJpaConfiguration

  • org.camunda.bpm.spring.boot.starter.configuration.CamundaAuthorizationConfiguration

4.1. Default configurations

The following default and best practice configurations are provided by the starter and can be customized or overridden if you like to.

4.1.1. DefaultProcessEngineConfiguration

Sets the process engine name and automatically adds all ProcessEnginePlugin beans to the configuration.

4.1.2. DefaultDatasourceConfiguration

Applies the datasource and transaction management configurations to the process engine. If you want to configure more than one datasource and don’t want to use the @Primary one for the process engine then name the one you want to use as camundaBpmDataSource.

public DataSource primaryDataSource() {
  return DataSourceBuilder.create().build();

public DataSource secondaryDataSource() {
  return DataSourceBuilder.create().build();
When using history-level auto with more then one database and camunda version < 7.4 you have to provide a JdbcTemplate bean as camundaBpmJdbcTemplate corresponding to the camundaBpmDataSource.

4.1.3. DefaultHistoryConfiguration

Applies the history configuration to the process engine. If not configured the camunda default level will be used. If you want to use a custom HistoryEventHandler you just have to provide a bean implementing the interface.

public HistoryEventHandler customHistoryEventHandler() {
  return new CustomHistoryEventHanlder();

4.1.4. DefaultHistoryLevelAutoHandlingConfiguration

As camunda version >= 7.4 supports history-level auto this configuration adds support for versions < = 7.3.

To have more control about the handling you can provide your own

  • org.camunda.bpm.spring.boot.starter.jdbc.HistoryLevelDeterminator with name historyLevelDeterminator

The default configuration is applied after all other default configurations using the ordering mechanism.

4.1.5. DefaultJobConfiguration

Applies the job execution properties to the process engine.

To have more control about the execution itself you can provide your own

  • org.camunda.bpm.engine.impl.jobexecutor.JobExecutor

  • org.springframework.core.task.TaskExecutor named camundaTaskExecutor


The job executor is not enabled in the configuration. This is done after the spring context successfully loaded (see org.camunda.bpm.spring.boot.starter.runlistener).

4.1.6. DefaultDeploymentConfiguration

If auto deployment is enabled (this is by default) all process found in the classpath will be deployed. The resource pattern can be changed using properties (see Camunda application properties).

4.1.7. DefaultJpaConfiguration

If JPA is enabled and a entityManagerFactory bean is configured the process engine will be enabled to use JPA (see Camunda application properties).

4.1.8. DefaultAuthorizationConfiguration

Applies the authorization configuration to the process engine. If not configured the camunda default values will be used (see Camunda application properties).

4.2. Overriding a default configuration

Provide a bean implementing one of the marker interfaces. For example to customize the datasource configuration:

public class MyCamundaConfiguration {

        public static CamundaDatasourceConfiguration camundaDatasourceConfiguration() {
                return new MyCamundaDatasourceConfiguration();


4.3. Adding additional configurations

You just have to provide one or more beans implementing the org.camunda.bpm.engine.impl.cfg.ProcessEnginePlugin interface (or extend from org.camunda.bpm.spring.boot.starter.configuration.impl.AbstractCamundaConfiguration). The configurations are applied ordered using the spring ordering mechanism (@Order annotation and Ordered interface). So if you want that your configuration is applied before the default configurations add a @Order(Ordering.DEFAULT_ORDER - 1) annotation to your class. If you want that your configuration is applied after the default configurations add a @Order(Ordering.DEFAULT_ORDER + 1) annotation to your class.

public class MyCamundaConfiguration {

        @Order(Ordering.DEFAULT_ORDER + 1)
        public static ProcessEnginePlugin myCustomConfiguration() {
                return new MyCustomConfiguration();


Or if you have component scan enabled:

@Order(Ordering.DEFAULT_ORDER + 1)
public class MyCustomConfiguration implements ProcessEnginePlugin {

        public void preInit(ProcessEngineConfigurationImpl processEngineConfiguration) {




@Order(Ordering.DEFAULT_ORDER + 1)
public class MyCustomConfiguration extends AbstractCamundaConfiguration {

        public void preInit(SpringProcessEngineConfiguration springProcessEngineConfiguration) {




To enable REST API you can use


By default the application path is rest, so without any further configuration you can access the api at http://localhost:8080/rest/engine

Because we are using jersey one can use spring boot’s common application properties. For example to change the application path use spring.jersey.application-path=myapplicationpath.

To modify the configuration or register additional resources one can provide a bean which extends from org.camunda.bpm.spring.boot.starter.rest.CamundaJerseyResourceConfig:

public class JerseyConfig extends CamundaJerseyResourceConfig {

  protected void registerAdditionalResources() {


6. Web Applications

To enable Web Applications (Admin, Cockpit and Tasklist for now) you can use

This feature depends on camunda bpm version >= 7.4!

By default the starter registers a controller to redirect / to camundas bundled index.html. To disable this you have to add camunda.bpm.webapp.index-redirect-enabled=false to your application properties.

The default camunda URLs are:

Webapp URL









6.1. Using the ProcessApplication

By default, the camunda-spring-boot-starter is configured to use the SpringProcessEngineConfiguration auto deployment feature. Since 1.2.0 you also have the possibility to do so via SpringBootProcessApplication. This disables the SpringProcessEngineConfiguration auto-deploy feature and instead uses the required "META-INF/processes.xml" as an indicator for resource scanning. This also allows all processes.xml configuration features described here.

To use it, extend the ProcessApplication with your main application class:

public class MyApplication extends SpringBootProcessApplication{



6.1.1. @EnableProcessApplication

With 2.0.0, you can now use the @EnableProcessApplication annotation and do not need to extend a configuration manually:

public class MyApplication {



6.1.2. Using deployment callbacks

As when using @EnableProcessApplication we don’t extend ProcessApplication class, we can’t use @PostDeploy and @PreUndeploy method annotations. Instead these callbacks are provided via Spring event publishing mechanism. So you can use the following event listeners:

public void onPostDeploy(PostDeployEvent event) {

public void onPreUndeploy(PreUndeployEvent event) {

6.2. Using camunda enterprise

With 2.0.0 some enhancements for usage of camunda-spring-boot-starter and the camunda enterprise webapp.

6.2.1. Maven

To enable the project, run maven with the -Penterprise flag.

6.2.2. Gradle

Have a look at the example-webapp-ee-gradle.

If using enterprise, you can also use the camunda.bpm.license-file property to provide a license file that is inserted on application start. Or copy your license file under the name camunda-license.txt to your src/main/resources.

6.3. Camunda application properties

Prefix Property name Description Default value




switch to disable the camunda auto-configuration. Use to exclude camunda in integration tests.



name of the process engine

camunda default value


default serialization format

camunda default value


camunda history level

camunda default value


camunda history level to use when history-level is auto but the level can not determined automatically

default value from history-level


if processes should be auto deployed. This is disabled when using the SpringBootProcessApplication



Provide an URL to your camunda license file and is automatically inserted to the DB when the application starts (but only if no license key is found in the DB).



configure idGenerator. Allowed values: simple, strong



version of the process engine

read only value e.g. 7.4.0


formatted version of the process engine

read only value e.g. (v7.4.0)

Job Execution



activate job execution after successful startup



if set to false, no JobExecutor bean is created at all. Maybe used for testing.



if job executor is deployment aware



location for auto deployment

classpath*:/.bpmn, classpath:/.bpmn20.xml, classpath:/.dmn, classpath:/.dmn11.xml, classpath:/.cmmn, classpath:/.cmmn10.xml, classpath:*/.cmmn11.xml


set to value > 1 to activate parallel job execution.





if automatic schema update should be applied, use one of [true, false, create, create-drop, drop-create]



type of the underlying database

'h2', 'oracle', …​


prefix of the camunda database tables. Attention: The table prefix will not be applied if you are using schema-update!

camunda default value


the dataBase schema name

camunda default value




enables jpa configuration

true. Depends on entityManagerFactory bean.


JPA persistence unit name



close JPA entity manager



JPA handle transaction





enables default camunda health indicators





enables metrics reporting



enables db metrics reporting





registers a redirect from / to camundas bundled index.html





enables authorization

camunda default value


enables authorization for custom code

camunda default value


configures authorization check revokes

camunda default value


Performs tenant checks to ensure that an authenticated user can only access data that belongs to one of his tenants.


Admin User



the username (e.g. 'admin')



the initial password


.firstName, .lastName, .email

additional (optional) user attributes

defaults to value of 'id'




name of a "show all filter". If set, on start a new filter will be created that displayes all tasks. Useful for testing on h2 db.


7. Changelog

7.1. 2.2.0


  • native support for camunda 7.7

  • subscribe to PostDeploy/PreUndeploy events


  • clean up webapp

  • databaseSchema support

7.2. 2.1.2


  • Default configuration works as expected, fixed serialization format and id generator.

  • correct gradle ee plugin

7.3. 2.1.0

Version 2.1.0 requires:

  • Java 8

  • Spring Boot 1.5.x (1.4 supported)

  • Camunda 7.6.0


  • configurable idGenerators

  • support of spring boot 1.5.x

  • create default filter only if it does not exist

  • webapp-ee plugin for gradle


  • Init only custom collections in processengineConfiguration to avoid breaking default behavior

  • remove lombok

7.4. 2.0.0

Version 2.0.0 requires:

  • Java 8

  • Spring Boot 1.4.x

  • Camunda 7.6.0

Migration Hints:

  • change the groupId to org.camunda.bpm.extension.springboot

  • consider using the BOM