Process Engine Configuration

The process engine configuration can be placed in both processes.xml and the bpm-platform.xml files. If the process engine is configured in either or both of those files, it will be bootstrapped by the Camunda Platform infrastructure and be made available through BpmPlatform.getProcessEngineService().getProcessEngine("name of process engine").

Example

The following example shows an XML snippet which can be placed in both processes.xml and/or bpm-platform.xml.

<process-engine name="default">
  <job-acquisition>default</job-acquisition>
  <configuration>org.camunda.bpm.engine.impl.cfg.StandaloneProcessEngineConfiguration</configuration>
  <datasource>java:jdbc/ProcessEngine</datasource>

  <properties>
    <property name="history">full</property>
    <property name="databaseSchemaUpdate">true</property>
    <property name="authorizationEnabled">true</property>
  </properties>

</process-engine>

Syntax Reference

Tag name Parent tag name Required? Description
<process-engine> <process-application> or <bpm-platform> true Container element for the configuration of a process engine.

Attributes:

  • name: allows you to define the name of the process engine (Required).

Text Content: None.

<job-acquisition> <process-engine> true Assign the process engine to a job acquisition.

Attributes: None.

Text Content: The name of the job acquisition to be used for this process engine. Job acquisitions are configured in the bpm-platform.xml file.

Example: <job-acquisition>default</job-acquisition>

<configuration> <process-engine> false Provide the name of the process engine configuration class.

Attributes: None.

Text Content: The fully qualified classname of the Process Engine Configuration class to be used for this process engine. The class must be a subclass of ProcessEngineConfigurationImpl ".

Default Value: StandaloneProcessEngineConfiguration

Example:
<configuration>
  my.custom.ProcessEngineConfiguration
</configuration>

<datasource> <process-engine> false Provide the JDBC name of the datasource to use for the process engine.

Attributes: None.

Text Content: JDBC name of the datasource to use for this process engine.

Default Value: null.

Example: <datasource>java:jdbc/ProcessEngine</datasource>

<properties> <process-engine>, <plugin> false Container element for providing a set of process engine configuration (or plugin) properties.

Attributes: None.

Text Content: None.

<property> <properties> false Set value for process engine configuration property or of a process engine plugin.

Attributes:

  • name: The name of the property to be set (Required). The process engine configuration (or plugin) class must provide a setter method setXXX() for the property name.

Text Content: The value of the property to be set. Property values are converted into String, Integer or Boolean values, depending on the type of the setter in the process engine configuration (or plugin) class.

Example:
true

<plugins> <process-engine> false Container element for providing a set of process engine plugin configurations.

Attributes: None.

Text Content: None.

<plugin> <plugins> false Container element for providing an individual process engine plugin configuration.

Attributes: None.

Text Content: None.

<class> <plugin> false Sets the classname of a process engine plugin.

Attributes: None.

Text Content: The fully qualified classname of a process engine plugin. Must be an implementation of ProcessEnginePlugin

Configuration Properties

The following is a list with the most commonly used process engine configuration properties, along with some explanations. The properties can be used in the <property name="foo">bar</property> tag, where foo is the name of the property and bar is the value of the property.

Property name Type Description
authorizationEnabled Boolean Activates authorization checks.
autoStoreScriptVariables Boolean Controls whether all global script variables should be automatically stored as process variables or not. Default value is false.

Values: true, false (Boolean).

cmmnEnabled Boolean When set to false, the following behavior changes:
  • The automated schema maintenance (creating and dropping tables, see property databaseSchemaUpdate) does not cover the tables required for CMMN execution.
  • CMMN resources are not deployed as case definitions to the engine.
  • Tasks from CMMN cases are not returned by the task query.
Default value is true.

Values: true, false (Boolean).

databaseSchemaUpdate String Sets the value for process engine database schema creation.

Values: false, create-drop, true.

databaseTablePrefix String Specifies a prefix for any table name included in SQL statements made by the process engine. Can be used to point the engine to a specific schema by setting the value to MY_SCHEMA. or tables with a naming pattern by setting the value to MY_TABLE_PREFIX_PATTERN_.
defaultNumberOfRetries Integer Specifies how many times a job will be executed before an incident is raised. Default value: 3
commandRetries Integer Only used with CockroachDB. Specifies how many times a Command will be retried before a CrdbTransactionRetryException is reported to the caller (more details here). Default value: 0
defaultUserPermissionNameForTask String Set the default permisson to work on a task. Allowed values are UPDATE or TASK_WORK. Default value: UPDATE.
disabledPermissions List Define a list of Permissions' names. These permissions will be not taken into account whenever authorization check is performed.
dmnEnabled Boolean When set to false, the following behavior changes:
  • The automated schema maintenance (creating and dropping tables, see property databaseSchemaUpdate) does not cover the tables required for DMN execution.
  • DMN resources are not deployed as decision definitions or decision requirements definitions to the engine.
Default value is true.

Values: true, false (Boolean).

enableExceptionsAfterUnhandledBpmnError Boolean If set to true, Process Engine Exception is thrown when unhandled BPMN Error occurs. Default value: false

Values: true, false (Boolean).

enableExpressionsInAdhocQueries Boolean If set to true, expressions can be used when creating and executing adhoc queries. For details, see the section on security considerations for custom code in the user guide. Default value is false.

Values: true, false (Boolean).

enableExpressionsInStoredQueries Boolean If set to true, expressions can be used when creating and executing stored queries. For details, see the section on security considerations for custom code in the user guide. Default value is true.

Values: true, false (Boolean).

enableFetchProcessDefinitionDescription Boolean If set to false, Bpmn Model Instance is not fetched and cached whenever a process definition query is performed and thus the returned process definition does not contain the description. Default value is true.

Values: true, false (Boolean).

enableXxeProcessing Boolean If set to true, enables XML eXternal Entity (XXE) Processing. When disabled, it provides protection against XXE Processing attacks. Default value is false.

Values: true, false (Boolean).

enableScriptCompilation Boolean Controls whether the process engine should attempt to compile script sources and cache the compilation result or not. Default value is true.

Values: true, false (Boolean).

forceCloseMybatisConnectionPool Boolean Controls whether a Mybatis-managed database connection pool is force closed when the process engine is closed. Closing the pool closes all active and idle database connections.

Values: true (default), false.

failedJobRetryTimeCycle String Sets how often a job is retried after a fail and how long the engine should wait until it tries to execute a job again. See the user guide for more details on this setting.
ensureJobDueDateNotNull Boolean Ensures that each job has it's DueDate property set. If the Job DueDate property hasn't been explicitly set, the current time is added. Default value is true.

Values: true, false (Boolean).

enableHistoricInstancePermissions Boolean If the value of this flag is set to true, Historic Instance Permissions are enabled. Default value is false.

Values: true, false (Boolean).

enforceSpecificVariablePermission Boolean If the value of this flag is set to true, the default permissions to see/read variables are:
  • READ_INSTANCE_VARIABLE, READ_HISTORY_VARIABLE, and READ_TASK_VARIABLE on Process Definition resource, and READ_VARIABLE on Task resource
  • READ_VARIABLE on Historic Task resource
Default value is false.

Values: true, false (Boolean).

history String Sets the level of the process engine history.

Values: none, activity, audit, full.

enableDefaultDbHistoryEventHandler Boolean If the value of this flag is true, an instance of the default DbHistoryEventHandler class is included in the collection of History Events Handlers. This flag should be used in conjunction with the customHistoryEventHandlers List property when defining custom History Event Handlers. The default value is true.

Values: true, false (Boolean).

historyRemovalTimeStrategy String Controls if and when the removal time of an historic instance is set. The default value is end.
Please also see the historyCleanupStrategy configuration parameter.

Values: start, end, none (String).
hostname String Sets the name of the host on which the Process Engine will run. The hostname property is also used as the Metrics Reporter identifier.

A custom hostname can be generated by providing an implementation of the HostnameProvider interface and and setting the engine property `hostnameProvider` to an instance of that class.

jdbcDriver String Sets the fully qualified classname of the JDBC driver to use.

This is usually used if the process engine is NOT configured using a <datasource> (see above) but using the built-in mybatis connection pool instead.

jdbcPassword String Sets the password of the JDBC connection.

This is usually used if the process engine is NOT configured using a <datasource> (see above) but using the built-in mybatis connection pool instead.

jdbcUrl String Sets the JDBC url for the database connection.

This is usually used if the process engine is NOT configured using a <datasource> (see above) but using the built-in mybatis connection pool instead.

jdbcUsername String Sets the username of the JDBC connection.

This is usually used if the process engine is NOT configured using a <datasource> (see above) but using the built-in mybatis connection pool instead.

jdbcBatchProcessing Boolean Controls if the engine executes the jdbc statements as Batch or not.

Default is true, but this has to be disabled for some databases. See the user guide for further details.

jobExecutorAcquireByDueDate Boolean Controls whether the job executor acquires the next jobs to execute ordered by due date. Default value is false. See the user guide for more details on this setting.

Values: true, false (Boolean).

jobExecutorActivate Boolean Controls whether the process engine starts with an active job executor or not. For a shared process engine configuration, the default value is true. For an embedded process engine configuration, the default value is false. See the user guide for more details on this setting.

Values: true, false (Boolean).

jobExecutorDeploymentAware Boolean Controls whether the job executor is deployment aware or not.

Values: true, false (Boolean).

jobExecutorPreferTimerJobs Boolean Controls whether the job executor prefers due timer jobs over other job types. Default value is false. See the user guide for more details on this setting.

Values: true, false (Boolean).

skipHistoryOptimisticLockingExceptions Boolean Controls if the engine will throw OptimisticLockingExceptions on UPDATE or DELETE operations for historical data or not. The default is true. To preserve the previous behavior (≤ 7.9), the flag must be set to false.

Values: true, false (Boolean).
standaloneTasksEnabled Boolean When set to false, the following behavior changes:
  • Standalone tasks can no longer be created via API.
  • Standalone tasks are not returned by the TaskQuery.
Default value is true.

Values: true, false (Boolean).

tenantCheckEnabled Boolean Controls whether the process engine performs tenant checks to ensure that an authenticated user can only access data that belongs to one of his tenants. Default value is true. See the user guide for more details.

Values: true, false (Boolean).

batchJobsPerSeed Integer Sets the number of batch execution jobs created per batch seed job invocation. See the user guide for more information on batch execution. Default value: 100
invocationsPerBatchJob Integer Sets the number of invocations a single batch execution job executes. See the user guide for more information on batch execution. Default value: 1
invocationsPerBatchJobByBatchType Map Defines the invocations per batch job for each individual batch type. Unless specified in this map, the value of 'invocationsPerBatchJob' is used for batch operations.

Read more in the User Guide.
batchPollTime Integer Sets the poll interval of the batch monitor job to check for batch completion in seconds. See the user guide for more information on batch execution. Default value: 30
batchJobPriority Integer Sets the default batch job priority. See the user guide for more information on job prioritization. Default value: 0
deploymentLockUsed Boolean Sets if the process engine must acquire an exclusive lock when creating a deployment. Default value: true
deploymentSynchronized Boolean Sets if processing of the deployment must be synchronized. When true several deployments will be processed sequentially on one process engine node. When false, they may be processed in parallel, though depending of value of deploymentLockUsed they may still be synchronized using database pessimistic lock. Default value: true
javaSerializationFormatEnabled Boolean Sets if Java serialization format can be used, when setting variables by their serialized representation. Default value: false
deserializationTypeValidationEnabled Boolean Sets if validation of types should be performed before JSON and XML deserialization. See Security Instructions for further information. Default value: false
deserializationAllowedPackages String Sets the allowed package names of types that are analyzed before JSON and XML deserialization if deserializationTypeValidationEnabled is set to true. With the default validator, this can be a comma-separated list of allowed package names. Only the defined packages and their sub-packages will be allowed in conjunction with the deserializationAllowedClasses. Also, the default validator always allows types within the package "java.lang" and all sub-packages. See Security Instructions for further information. Default value: null
deserializationAllowedClasses String Sets the allowed class names of types that are analyzed before JSON and XML deserialization if deserializationTypeValidationEnabled is set to true. With the default validator, this can be a comma-separated list of class names. Only the defined class names will be allowed in conjunction with the deserializationAllowedPackages. Also, the default validator always allows the following types: java.util.ArrayList, java.util.Arrays$ArrayList, java.util.HashMap, java.util.HashSet, java.util.LinkedHashMap, java.util.LinkedHashSet, java.util.LinkedList, java.util.Properties, java.util.TreeMap, java.util.TreeSet. See Security Instructions for further information. Default value: null
enablePasswordPolicy Boolean Set to true, to enable a password policy for users that are managed by the engine. If a custom password policy is configured, it will be enabled. Otherwise the built-in password policy is activated.
enableCmdExceptionLogging Boolean Set to false, to disable logging of unhandled exceptions that occur during command execution. The default setting for this flag is true. Note: There might be duplicate log entries for command exceptions (e.g. when a job fails).
enableReducedJobExceptionLogging Boolean Set to true, to suppress logging of exceptions that occur during the execution of a job that has retries left. If the job does not have any retries left an exception will still be logged.
queryMaxResultsLimit Integer When defining a limit of maximum results, an authenticated user cannot perform a query with an unbounded number of results or a paginated query that exceeds the limit. Read more about it in the User Guide.

Note: To gain the full feature set of the Webapps, and not suffer any UX degradation due to unavailable data, the queryMaxResultsLimit must be set to 2000. If you use Optimize it is recommended to set the value to 10 000, so the import of the data to Optimize works out of the box.

The default value is 231-1.
dmnFeelEnableLegacyBehavior Boolean Set to true to restore the legacy FEEL configuration of the DMN Engine. This will result in the usage of the old, Java-based FEEL Engine, as well as the usage of JUEL in DMN input expressions, output entries and literal expressions. When set to false, the new, Scala-based FEEL Engine is used, and FEEL is used as the default language for DMN input expressions, input and output entries, and literal expressions. Default value: false
dmnFeelCustomFunctionProviders List Define a list of instances of FeelCustomFunctionProvider.

Read more about it in the User Guide.
initializeTelemetry boolean

Sets the initial property value of telemetry configuration only once when it has never been enabled/disabled before. If enabled, information about the setup and usage of the process engine is sent to remote Camunda servers for the sake of analytical evaluation. It can be enabled/disabled later via Java/REST API.

For more information and a complete list of the data that is collected, please check the Telemetry page.

Legal note:

Before you install a Camunda Platform Runtime version >= 7.14.0-alpha1 (and 7.13.7+, 7.12.12+, 7.11.19+) or activate the telemetric functionality, please make sure that you are authorized to take this step, and that the installation or activation of the telemetric functionality is not in conflict with any internal company policies, compliance guidelines, any contractual or other provisions or obligations of your company.

Camunda can not be held responsible in the event of unauthorized installation or activation of this function.

telemetryReporterActivate Boolean

Activates the thread that periodically reports telemetry. Note that the thread only sends telemetry if telemetry is in addition enabled via API or by the initializeTelemetry property.

The reporter can for example be deactivated in unit testing setups to avoid any threads running besides the test thread.

Default value: true
telemetryReportingPeriod Long Sets the period in which telemetry requests are sent. Value must be in seconds. Default value: 86400 (one day)
telemetryRequestRetries Integer Sets the number of retries that are performed when a telemetry request fails. Default value: 2
telemetryRequestTimeout Integer Sets the request timeout configuration in millisecodns of the telemetry request. Default value: 15000 (15 s)

History cleanup configuration parameters

historyCleanupStrategy String Controls which History cleanup strategy is used. The default value is removalTimeBased.
Please also see the historyRemovalTimeStrategy configuration parameter.

Values: removalTimeBased, endTimeBased.
historyCleanupBatchWindowStartTime String History cleanup batch window start time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 20:00+0100 or 20:00. In case of null, no batch window is considered to be configured and history cleanup can only be called manually.
historyCleanupBatchWindowEndTime String History cleanup batch window end time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 23:00-0300 or 23:00. In case batchWindowEndTime exceeds batchWindowStartTime it is considered to be on the same date (e.g., cleanup runs each day between 20:00 and 23:00). Otherwise it is considered to be on the next calendar day (e.g., cleanup starts each day at 20:00 and finishes the next day at 01:00). Default value is `00:00`.
mondayHistoryCleanupBatchWindowStartTime String History cleanup batch window start time for Mondays. Requires the same format as historyCleanupBatchWindowStartTime. In case it is not configured, batch window configured with historyCleanupBatchWindowStartTime and historyCleanupBatchWindowEndTime will be used for this day of week.
mondayHistoryCleanupBatchWindowEndTime String History cleanup batch window end time for Mondays. Requires the same format and follows the same logic as historyCleanupBatchWindowEndTime.
tuesdayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Tuesdays.
tuesdayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Tuesdays.
wednesdayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Wednesdays.
wednesdayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Wednesdays.
thursdayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Thursdays.
thursdayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Thursdays.
fridayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Fridays.
fridayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Fridays.
saturdayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Saturdays.
saturdayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Saturdays.
sundayHistoryCleanupBatchWindowStartTime String Similar to mondayHistoryCleanupBatchWindowStartTime, but for Sundays.
sundayHistoryCleanupBatchWindowEndTime String Similar to mondayHistoryCleanupBatchWindowEndTime, but for Sundays.
historyCleanupBatchSize Integer Defines the amount of top-level objects (e.g., historic process instances) to be removed at once. Default and maximum value is 500.
historyCleanupBatchThreshold Integer Defines the minimum amount of top-level objects required for data to be removed. Default value is 10. Hint: if the value is too small and the process engine continues to be used during history cleanup, it can happen that real SQL delete statements are called very frequently for small amounts of data.

Note: This property cannot be used in conjunction with historyCleanupStrategy set to removalTimeBased.
historyCleanupDegreeOfParallelism Integer Defines the level of parallelism for history cleanup. Default value is 1 (no parallelism). Maximum allowed value is 8.
historyCleanupMetricsEnabled Boolean Activates metrics for history cleanup. Default value is true;.
historyCleanupEnabled Boolean Configures whether the engine participates in history cleanup or not. The default value is true. For more details, please see Cleanup Execution Participation per Node in the User Guide.
historyTimeToLive String Defines history time to live for process definitions if no other value is defined. The history time to live defines the number of days using a time specified by the ISO-8601 date format. The function only accepts the notation to define a number of days.
batchOperationHistoryTimeToLive String Defines history time to live for historic batch operations. The history time to live defines the number of days using a time specified by the ISO-8601 date format. The function only accepts the notation to define a number of days.
batchOperationsForHistoryCleanup Map Defines history time to live for each specific historic batch operation. The history time to live defines the number of days using a time specified by the ISO-8601 date format. The function only accepts the notation to define a number of days.
historyCleanupJobLogTimeToLive String Defines history time to live for history job log entries produced by history cleanup jobs. This works with the removalTimeBased history cleanup strategy. The history time to live defines the number of days using a time specified by the ISO-8601 date format. The function only accepts the notation to define a number of days.

Login parameters

loginMaxAttempts Integer Defines the maximum number of attempts a user can try to login before this user is locked. Default value: 10
loginDelayMaxTime Integer Defines the maximum amount of time (in seconds) for which a user must wait until they are able to try to login again. Default value: 60 seconds
loginDelayFactor Integer Defines the factor by which the delay is calculated after an unsuccessful login attempt. Default value: 2
loginDelayBase Integer Defines the base by which the delay is calculated after an unsuccessful login attempt. Default value: 3

Resource whitelist pattern parameters

generalResourceWhitelistPattern String Defines acceptable values for the User, Group and Tenant IDs. Can be defined by using the standard Java Regular Expression syntax. Default value: [a-zA-Z0-9]+|camunda-admin
userResourceWhitelistPattern String Defines acceptable values for the User IDs. Can be defined by using the standard Java Regular Expression syntax. Default value: a custom general whitelist pattern or the default [a-zA-Z0-9]+|camunda-admin (if nothing is defined)
groupResourceWhitelistPattern String Defines acceptable values for the Group IDs. Can be defined by using the standard Java Regular Expression syntax. Default value: a custom general whitelist pattern or the default [a-zA-Z0-9]+|camunda-admin (if nothing is defined)
tenantResourceWhitelistPattern String Defines acceptable values for the Tenant IDs. Can be defined by using the standard Java Regular Expression syntax. Default value: a custom general whitelist pattern or the default [a-zA-Z0-9]+|camunda-admin (if nothing is defined)

Logging context parameters

These parameters define the keys at which the specified data can be retrieved from the Mapped Diagnostic Context (MDC). See Logging for details. The specified data will only be put into the MDC if a key is defined. All parameters can be set to null or the empty String in order to disable their logging in the MDC.

loggingContextActivityId String Defines the key for the current activity id. Default value: activityId
loggingContextApplicationName String Defines the key for the current process application name. Default value: applicationName
loggingContextBusinessKey String Defines the key for the current business key. Default value: null (disabled by default since a lookup into the database might be necessary in case the business key needs to be fetched from the process instance)
loggingContextProcessDefinitionId String Defines the key for the current process definition id. Default value: processDefinitionId
loggingContextProcessInstanceId String Defines the key for the current process instance id. Default value: processInstanceId
loggingContextTenantId String Defines the key for the current tenant id. Default value: tenantId

On this Page: