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:

pom.xml
<dependency>
  <groupId>org.camunda.bpm.extension.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter</artifactId>
  <version>2.2.0</version>
</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:

pom.xml
<properties>
  <camunda.version>7.7.0</camunda.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <!-- Import dependency management from camunda -->
      <groupId>org.camunda.bpm</groupId>
      <artifactId>camunda-bom</artifactId>
      <version>${camunda.version}</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

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.

@Bean
@Primary
@ConfigurationProperties(prefix="datasource.primary")
public DataSource primaryDataSource() {
  return DataSourceBuilder.create().build();
}

@Bean(name="camundaBpmDataSource")
@ConfigurationProperties(prefix="datasource.secondary")
public DataSource secondaryDataSource() {
  return DataSourceBuilder.create().build();
}
Important
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.

@Bean
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

Important
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

beans.

Important
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:

@Configuration
public class MyCamundaConfiguration {

        @Bean
        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.

@Configuration
public class MyCamundaConfiguration {

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

}

Or if you have component scan enabled:

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

        @Override
        public void preInit(ProcessEngineConfigurationImpl processEngineConfiguration) {
                //...
        }

        ...

}

or

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

        @Override
        public void preInit(SpringProcessEngineConfiguration springProcessEngineConfiguration) {
                //...
        }

        ...

}

5. REST API

To enable REST API you can use

pom.xml
<dependency>
  <groupId>org.camunda.bpm.extension.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-rest</artifactId>
  <version>2.2.0</version>
</dependency>

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:

@Component
@ApplicationPath("/rest")
public class JerseyConfig extends CamundaJerseyResourceConfig {

  @Override
  protected void registerAdditionalResources() {
    register(...);
  }

}

6. Web Applications

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

pom.xml
<dependency>
  <groupId>org.camunda.bpm.extension.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-webapp</artifactId>
  <version>2.2.0</version>
</dependency>
Important
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

default

http://localhost:8080

admin

http://localhost:8080/app/admin/index.html

tasklist

http://localhost:8080/app/tasklist/index.html

cockpit

http://localhost:8080/app/cockpit/index.html

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:

@SpringBootApplication
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:

@SpringBootApplication
@EnableProcessApplication("myProcessApplicationName")
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:

@EventListener
public void onPostDeploy(PostDeployEvent event) {
  ...
}

@EventListener
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

General

camunda.bpm

.enabled

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

true

.process-engine-name

name of the process engine

camunda default value

.default-serialization-format

default serialization format

camunda default value

.history-level

camunda history level

camunda default value

.history-level-default

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

default value from history-level

.auto-deployment-enabled

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

true

.license-file

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

-

.id-generator

configure idGenerator. Allowed values: simple, strong

simple

.version

version of the process engine

read only value e.g. 7.4.0

.formatted-version

formatted version of the process engine

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

Job Execution

camunda.bpm.job-execution

.active

activate job execution after successful startup

true

.enabled

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

true

.deployment-aware

if job executor is deployment aware

false

.deployment-resource-pattern

location for auto deployment

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

.core-pool-size

set to value > 1 to activate parallel job execution.

1

Datasource

camunda.bpm.database

.schema-update

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

true

.type

type of the underlying database

'h2', 'oracle', …​

.table-prefix

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

camunda default value

.schema-name

the dataBase schema name

camunda default value

JPA

camunda.bpm.jpa

.enabled

enables jpa configuration

true. Depends on entityManagerFactory bean.

.persistence-unit-name

JPA persistence unit name

-

.close-entity-manager

close JPA entity manager

true

.handle-transaction

JPA handle transaction

true

Management

camunda.bpm.management

.health.camunda.enabled

enables default camunda health indicators

true

Metrics

camunda.bpm.metrics

.enabled

enables metrics reporting

true

.db-reporter-activate

enables db metrics reporting

true

Webapp

camunda.bpm.webapp

.index-redirect-enabled

registers a redirect from / to camundas bundled index.html

true

Authorization

camunda.bpm.authorization

.enabled

enables authorization

camunda default value

.enabled-for-custom-code

enables authorization for custom code

camunda default value

.authorization-check-revokes

configures authorization check revokes

camunda default value

.tenant-check-enabled

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

true

Admin User

camunda.bpm.admin-user

.id

the username (e.g. 'admin')

-

.password

the initial password

id

.firstName, .lastName, .email

additional (optional) user attributes

defaults to value of 'id'

Filter

camunda.bpm.filter

.create

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

Features

  • native support for camunda 7.7

  • subscribe to PostDeploy/PreUndeploy events

Fixes

  • clean up webapp

  • databaseSchema support

7.2. 2.1.2

Fixes

  • 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

Features

  • configurable idGenerators

  • support of spring boot 1.5.x

  • create default filter only if it does not exist

  • webapp-ee plugin for gradle

Fixes

  • 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