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.CamundaAuthorizationConfiguration
• org.camunda.bpm.spring.boot.starter.configuration.CamundaFailedJobConfiguration
• org.camunda.bpm.spring.boot.starter.configuration.CamundaMetricsConfiguration

Default Configurations

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

DefaultProcessEngineConfiguration

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

DefaultDatasourceConfiguration

Configures the Camunda data source and enables transaction integration. By default, the primary DataSource and PlatformTransactionManager beans are wired with the process engine configuration.

If you want to configure more than one datasource and don’t want to use the @Primary one for the process engine, then you can create a separate data source with name camundaBpmDataSource that will be automatically wired with Camunda instead.

@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();
}

If you don’t want to use the @Primary transaction manager, it is possible to create a separate transaction manager with the name camundaBpmTransactionManager that will be wired with the data source used for Camunda (either @Primary or camundaBpmDataSource):

@Bean
@Primary
public PlatformTransactionManager primaryTransactionManager() {
  return new JpaTransactionManager();
}

@Bean(name="camundaBpmTransactionManager")
public PlatformTransactionManager camundaTransactionManager(@Qualifier("camundaBpmDataSource") DataSource dataSource) {
  return new DataSourceTransactionManager(dataSource);
}

DefaultHistoryConfiguration

Applies the history configuration to the process engine. If not configured, the history level FULL is 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();
}

DefaultHistoryLevelAutoHandlingConfiguration

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

To have more control over 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.

DefaultJobConfiguration

Applies the job execution properties to the process engine.

To have more control over 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).

DefaultDeploymentConfiguration

If auto deployment is enabled (this is the case by default), all processes found in the classpath are deployed. The resource pattern can be changed using properties (see properties).

DefaultAuthorizationConfiguration

Applies the authorization configuration to the process engine. If not configured, the camunda default values are used (see properties).

Overriding the 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();
	}

}

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 your configuration to be applied before the default configurations, add a @Order(Ordering.DEFAULT_ORDER - 1) annotation to your class. If you want your configuration to be 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) {
		//...
	}

	...

}

CIB seven engine Properties

In addition to the bean-based way of overriding process engine configuration properties, it is also possible to set those properties via an application.yaml configuration file. Instructions on how to use it can be found in the Spring Boot Starter Guide.

The available properties are as follows:

Generic Properties

The method of configuration described above does not cover all process engine properties available. To override any process engine configuration property that is not exposed (i.e. listed above) you can use generic-properties.

camunda:
  bpm:
    generic-properties:
      properties:
        ...

Examples

Override configuration using exposed properties:

camunda.bpm:
  admin-user:
    id: kermit
    password: superSecret
    firstName: Kermit
  filter:
    create: All tasks

Override configuration using generic properties:

camunda:
  bpm:
    generic-properties:
      properties:
        enable-password-policy: true

Session Cookie

You can configure the Session Cookie for the Spring Boot application via the application.yaml configuration file.

Camunda Spring Boot Starter versions <= 2.3 (Spring Boot version 1.x)

server:
  session:
    cookie:
      secure: true
      http-only: true # Not possible for versions before 1.5.14

Camunda Spring Boot Starter versions >= 3.0 (Spring Boot version 2.x)

server:
  servlet:
    session:
      cookie:
        secure: true
        http-only: true # Not possible for versions before 2.0.3

Further details of the session cookie like the SameSite flag can be configured via camunda.bpm.webapp.session-cookie in the application.yaml.

Configuring Spin DataFormats

The Camunda Spring Boot Starter auto-configures the Spin Jackson Json DataFormat when the camunda-spin-dataformat-json-jackson dependency is detected on the classpath. To include a DataFormatConfigurator for the desired Jackson Java 8 module, the appropriate dependency needs to be included on the classpath as well. Note that camunda-engine-plugin-spin needs to be included as a dependency as well for the auto-configurators to work.

Auto-configuration is currently supported for the following Jackson Java 8 modules:

1. Parameter names (jackson-module-parameter-names)
2. Java 8 Date/time (jackson-datatype-jdk8)
3. Java 8 Datatypes (jackson-datatype-jsr310)

For example, to provide support for Java 8 Date/time types in Spin, the following dependencies, with their appropriate version tags, will need to be added in the Spring Boot Application’s pom.xml file:

<dependencies>
   <dependency>
     <groupId>org.camunda.bpm</groupId>
     <artifactId>camunda-engine-plugin-spin</artifactId>
   </dependency>
   <dependency>
     <groupId>org.camunda.spin</groupId>
     <artifactId>camunda-spin-dataformat-json-jackson</artifactId>
   </dependency>
   <dependency>
     <groupId>com.fasterxml.jackson.datatype</groupId>
     <artifactId>jackson-datatype-jdk8</artifactId>
   </dependency>
</dependencies>

Spring Boot also provides some nice configuration properties, to further configure the Jackson ObjectMapper. They can be found here.

To provide additional configurations, the following actions need to be performed:

1. Provide a custom implementation of org.camunda.spin.spi.DataFormatConfigurator;
2. Add the appropriate key-value pair of the fully qualified classnames of the interface and the implementation to the META-INF/spring.factories file;
3. Ensure that the artifact containing the configurator is reachable from Spin’s classloader.