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


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


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


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.

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


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.


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


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


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


If JPA is enabled and a entityManagerFactory bean is configured, the process engine is enabled to use JPA (see properties).


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:

public class MyCamundaConfiguration {

	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.

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



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

Prefix Property name Description Default value
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
.generate-unique-process-engine-name Generate a unique name for the process engine (format: 'processEngine' + 10 random alphanumeric characters) false
.generate-unique-process-application-name Generate a unique Process Application name for every Process Application deployment (format: 'processApplication' + 10 random alphanumeric characters) false
.default-serialization-format Default serialization format Camunda default value
.history-level Camunda history level FULL
.history-level-default Camunda history level to use when history-level is auto, but the level can not determined automatically FULL
.auto-deployment-enabled If processes should be auto deployed. This is disabled when using the SpringBootProcessApplication true
.default-number-of-retries Specifies how many times a job will be executed before an incident is raised 3
.job-executor-acquire-by-priority If set to true, the job executor will acquire the jobs with the highest priorities false
.license-file Provides an URL to your Camunda license file and is automatically inserted into the DB when the application starts (but only if no license key is found in the DB). By default, the license key will be loaded:
  1. from the file with the name camunda-license.txt from classpath (if present)
  2. from path ${user.home}/.camunda/license.txt (if present)
The license must be exactly in the format as we sent it to you including the header and footer line.
.id-generator Configure idGenerator. Allowed values: simple, strong, prefixed. prefixed id generator is like strong, but uses a Spring application name (${}) as the prefix for each id. strong
.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)
.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
Process application
camunda.bpm.application .delete-upon-undeploy Indicates whether the undeployment of the process archive should trigger deleting the process engine deployment. If the process engine deployment is deleted, all running and historic process instances are removed as well. false
.scan-for-process-definitions Indicates whether the classloader should be scanned for process definitions. true
.deploy-changed-only Indicates whether only changed resources should be part of the deployment. This is independent of the setting that if no resources change, no deployment takes place but the previous deployment is resumed. false
.resume-previous-versions Indicates whether old versions of the deployment should be resumed. false
.resume-previous-by Indicates which previous deployments should be resumed by this deployment. process-definition-key
Job Execution
camunda.bpm.job-execution .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
.core-pool-size Set to value > 1 to activate parallel job execution. 3
.keep-alive-seconds Specifies the time, in milliseconds, for which threads are kept alive when there are no more tasks present. When the time expires, threads are terminated so that the core pool size is reached. 0
.lock-time-in-millis Specifies the time in milliseconds an acquired job is locked for execution. During that time, no other job executor can acquire the job. 300000
.max-jobs-per-acquisition Sets the maximal number of jobs to be acquired at once. 3
.max-pool-size Maximum number of parallel threads executing jobs. 10
.queue-capacity Sets the size of the queue which is used for holding tasks to be executed. 3
.wait-time-in-millis Specifies the wait time of the job acquisition thread in milliseconds in case there are less jobs available for execution than requested during acquisition. If this is repeatedly the case, the wait time is increased exponentially by the factor waitIncreaseFactor. The wait time is capped by maxWait. 5000
.max-wait Specifies the maximum wait time of the job acquisition thread in milliseconds in case there are less jobs available for execution than requested during acquisition. 60000
.backoff-time-in-millis Specifies the wait time of the job acquisition thread in milliseconds in case jobs were acquired but could not be locked. This condition indicates that there are other job acquisition threads acquiring jobs in parallel. If this is repeatedly the case, the backoff time is increased exponentially by the factor waitIncreaseFactor. The time is capped by maxBackoff. With every increase in backoff time, the number of jobs acquired increases by waitIncreaseFactor as well. 0
.max-backoff Specifies the maximum wait time of the job acquisition thread in milliseconds in case jobs were acquired but could not be locked. 0
.backoff-decrease-threshold Specifies the number of successful job acquisition cycles without a job locking failure before the backoff time is decreased again. In that case, the backoff time is reduced by waitIncreaseFactor. 100
.wait-increase-factor Specifies the factor by which wait and backoff time are increased in case their activation conditions are repeatedly met. 2
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. Possible values: h2, mysql, mariadb, oracle, postgres, mssql, db2. Will be automatically determined from datasource
.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
.jdbc-batch-processing Controls if the engine executes the jdbc statements as Batch or not. It has to be disabled for some databases. See the user guide for further details. Camunda default value: true
camunda.bpm.eventing .execution Enables eventing of delegate execution events. See the user guide for further details. true
.history Enables eventing of history events. See the user guide for further details. true
.task Enables eventing of task events. See the user guide for further details. true
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 .health.camunda.enabled Enables default camunda health indicators true
camunda.bpm.metrics .enabled Enables metrics reporting Camunda default value
.db-reporter-activate Enables db metrics reporting Camunda default value
camunda.bpm.webapp .index-redirect-enabled Registers a redirect from / to camunda's bundled index.html.
If this property is set to false, the default Spring Boot behaviour is taken into account.
.targetOrigin Sets the application expected deployment domain. See the user guide for details. Not set
.denyStatus Sets the HTTP response status code used for a denied request. See the user guide for details. 403
.randomClass Sets the name of the class used to generate tokens. See the user guide for details.
.entryPoints Sets additional URLs that will not be tested for the presence of a valid token. See the user guide for details. Not set
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'
camunda.bpm.filter .create Name of a "show all" filter. If set, a new filter is created on start that displays all tasks. Useful for testing on h2 db. -

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.



Overriding an already exposed property using the generic-properties keyword does not effect the process engine configuration. All exposed properties can only be overridden with their exposed identifier.


Override configuration using exposed properties:

    id: kermit
    password: superSecret
    firstName: Kermit
    create: All tasks

Override configuration using generic properties:

        enable-password-policy: true

On this Page: