Deployment Descriptor Reference

This reference explains the syntax of the camunda BPM deployment descriptors. The deployment descriptors are xml configuration files which allow configuration of the camunda BPM platform and declaratively specify the BPMN 2.0 deployments to the process engine.

camunda BPM provides the following deployment descriptors:

bpm-platform.xml: packaged as part of the camunda BPM platform and allows configuration of shared process engines and the job executor.
processes.xml: packaged as part of a process application and allows configuration of additional process engines and BPMN 2.0 process deployments.

Syntax Reference

This guide is a syntax reference for the above mentioned files. The User Guide explains when and how to use the deployment descriptors.

bpm-platform.xml

The bpm-platform.xml file is part of the camunda BPM platform distribution and can be used for configuration of process engines and the job executor.

It is used to configure the camunda BPM platform in the following distributions:

JBoss Application Server 7 / Wildfly 8

The bpm-platform.xml file is not used in the camunda BPM distribution for JBoss Application Server 7 / Wildfly 8. There, the configuration is added to the central application server configuration file (standalone.xml or domain.xml). The XML schema is the same (i.e. the same elements and properties can be used). See the The camunda JBoss Subsystem section of the User Guide for more details.

Xml Schema Namespace

The namespace for the bpm-platform.xml file is http://www.camunda.org/schema/1.0/BpmPlatform. The XSD file can be found in the camunda-engine.jar file.

Example

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform xmlns="http://www.camunda.org/schema/1.0/BpmPlatform"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.camunda.org/schema/1.0/BpmPlatform http://www.camunda.org/schema/1.0/BpmPlatform ">

  <job-executor>
    <job-acquisition name="default" />
  </job-executor>

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

    <properties>
      <property name="history">full</property>
      <property name="databaseSchemaUpdate">true</property>
      <property name="transactionManagerJndiName">java:appserver/TransactionManager</property>
      <property name="authorizationEnabled">true</property>
    </properties>

  </process-engine>

</bpm-platform>

Syntax Reference

Tag name	Parent tag name	Required?	Description
`<bpm-platform>`	None.	true	Root element of the bpm-platform.xml file.
`<job-executor>`	`<bpm-platform>`	true	See job-executor Reference
`<process-engine>`	`<bpm-platform>`	false	See process-engine Reference

Configure location of the bpm-platform.xml file

You can configure the location of the bpm-platform.xml, so the file can be stored externally to allow an easy upgrade path of camunda-bpm-platform.ear. This negates the work of unpacking / repackaging the ear when you need to change the configuration.

This feature is available for:

It is not available for the JBoss AS 7 / Wildfly 8 subsystem implementation, because the subsystem implementation uses the JBoss specific standalone.xml to configure the platform.

To specify the location you have to provide an absolute path or an http/https url pointing to the bpm-platform.xml file, e.g '/home/camunda/.camunda/bpm-platform.xml' or 'http://camunda.org/bpm-platform.xml'.

During startup of the camunda-bpm-platform, it tries to discover the location of the bpm-platform.xml file from the following sources in the listed order:

JNDI entry is available at java:/comp/env/bpm-platform-xml
Environment variable BPM_PLATFORM_XML is set
System property bpm.platform.xml is set, e.g when starting the server JVM it is appended as -Dbpm.platform.xml on the command line
META-INF/bpm-platform.xml exists on the classpath
(For Tomcat only): checks if there is a bpm-platform.xml inside the folder specified by ${CATALINA_BASE} || ${CATALINA_HOME} + /conf/

The discovery stops when one of the above mentioned sources is found or, in case none is found, it falls back to the bpm-platform.xml on the classpath, respectively ${CATALINA_BASE} || ${CATALINA_HOME} + /conf/ for Tomcat. We ship a default bpm-platform.xml file inside the camunda-bpm-platform.ear, except when you use the Tomcat or JBoss version of the platform.

Using system properties

In order to externalize environment specific parts of the configuration, it is possible to reference system properties using Ant-style expressions (i.e. ${PROPERTY_KEY}). Expression resolution is supported within the property elements only. System properties may be set via command line (-Doption) or in an implementation specific manner (Apache Tomcat's catalina.properties for example). Complex operations are not supported, but you may combine more than one expression in a single property element (e.g. ${ldap.host}:${ldap.port}).

Example:

<!-- ... -->
<plugin>
  <class>org.camunda.bpm.engine.impl.plugin.AdministratorAuthorizationPlugin</class>
  <properties>
    <property name="administratorUserName">${camunda.administratorUserName}</property>
  </properties>
</plugin>
<!-- ... -->

processes.xml

The processes.xml file is deployed as part of a process application and is used for configuration of the deployment of BPMN 2.0 resource files. Additionally, it can be used to configure process engines which are started / stopped with the deployment of the application.

See the processes.xml section of the User Guide for more details..

Xml Schema Namespace

The namespace for the processes.xml file is http://www.camunda.org/schema/1.0/ProcessApplication. The XSD file can be found in the camunda-engine.jar file.

Empty processes.xml

The processes.xml may be left blank (can be empty). In this case, default values are used. See the Empty processes.xml section of the User Guide for more details.

Example

<process-application
  xmlns="http://www.camunda.org/schema/1.0/ProcessApplication"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <process-archive name="loan-approval">
    <process-engine>default</process-engine>
    <properties>
      <property name="isDeleteUponUndeploy">false</property>
      <property name="isScanForProcessDefinitions">true</property>
    </properties>
  </process-archive>

</process-application>

Syntax Reference

Tag name	Parent tag name	Required?	Description
`<process-application>`	None.	true	Root element of the processes.xml file.
`<process-engine>`	`<process-application>`	false	See process-engine Reference
`<process-archive>`	`<process-application>`	false	See process-archive Reference

Job Executor Configuration

The job executor tag is used to configure the job executor and can be placed in the bpm-platform.xml file.

Example

The following example shows a job executor XML snippet:

<job-executor>
  <job-acquisition name="default">
    <properties>
      <property name="maxJobsPerAcquisition">5</property>
      <property name="waitTimeInMillis">8000</property>
      <property name="lockTimeInMillis">400000</property>
    </properties>
  </job-acquisition>
  <properties>
    <!-- Note: the following properties only take effect in a Tomcat environment -->
    <property name="queueSize">3</property>
    <property name="corePoolSize">5</property>
    <property name="maxPoolSize">10</property>
    <property name="keepAliveTime">0</property>
  </properties>
</job-executor>

Syntax Reference

Tag name	Parent tag name	Required?	Description
`<job-executor>`	`<bpm-platform>`	true	Container element for the configuration of a job executor. Attributes: None. Text Content: None.
`<job-acquisition>`	`<job-executor>`	true	Specifies a job acquisition thread. Attributes: `name`: allows you to define the name of the job acquisition thread. Text Content: None.
`<job-executor-class>`	`<job-acquisition>`	false	Specifies the fully qualified classname of the job executor. Attributes: None. Text Content: None. Example: `<job-executor-class>org.camunda.bpm.example.MyJobExecutor</job-executor-class>`
`<properties>`	`<job-acquisition>` or `<job-executor>`	false	Container element for providing a set of thread configuration properties. Attributes: None. Text Content: None.
`<property>`	`<properties>`	false	Set value for job acquisition configuration property. Attributes: `name`: The name of the property. Text Content: The value of the property to be set.

Job-Executor Configuration Properties

The following is a list with the available job acquisition thread 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.

Limitation:

This properties only take effect in a Tomcat environment.

Property name	Type	Description
`queueSize`	Integer	Sets the size of the queue which is used for holding tasks to be executed. Default Value: 3
`corePoolSize`	Integer	Sets the size of the core pool in the thread pool. This number of threads will always be present and wait to execute tasks. Default Value: 3
`maxPoolSize`	Integer	Sets the maximum number of threads that can be present in the thread pool. Default Value: 10
`keepAliveTime`	Long	Specify the time in milliseconds threads will be kept alive when there are no tasks present before threads are terminated until the core pool size is reached. Default Value: 0

Job-Acquisition Configuration Properties

Property name	Type	Description
`maxJobsPerAcquisition`	Integer	Sets the maximal number of jobs to be acquired at once. Default Value: 3
`waitTimeInMillis`	Integer	Specify the wait time of the job acquisition thread in milliseconds. This value can be used to define how often the job acquisition thread should poll the database for jobs. Default Value: 5000
`lockTimeInMillis`	Integer	Specify the lock time of an acquired job in milliseconds. Default Value: 300000

Process Archive Configuration

The process archive tag allows configuration of a process engine deployment and can be used in the processes.xml file.

See the processes.xml section of the User Guide for more details.

Example

The following example shows a process-archive XML snippet:

<process-archive name="loan-approval">
  <process-engine>my-engine</process-engine>
  <resource>bpmn/invoice.bpmn</resource>
  <resource>bpmn/order-resource.bpmn</resource>
  <properties>
    <property name="isDeleteUponUndeploy">false</property>
    <property name="isScanForProcessDefinitions">true</property>
    <property name="additionalResourceSuffixes">groovy,py</property>
  </properties>
</process-archive>

Syntax Reference

Tag name	Parent tag name	Required?	Description
`<process-archive>`	`<process-application>`	true	Container element for the configuration of a process archive (deployment). Attributes: `name`: Allows you to define the name of the process archive (Required). The name will be used for the process engine deployment. Text Content: None.
`<process-engine>`	`<process-archive>`	false	Specifies the name of the process engine to which the deployment is performed. If the element is not provided, the default process engine is used. Attributes: None. Text Content: The name of the process engine to which the deployment should be performed.
`<resource>`	`<process-archive>`	false	Can be used to explicitly list the paths to resources that are part of this deployment. These can be process or case definitions but also additional files like script files. Attributes: None. Text Content: The path to the resource that is part of this deployment. The resource is loaded with the classloader of the process application and therefore must be relative to the process application classloader root(s).
`<properties>`	`<process-engine>`, `<plugin>`	false	Container element for providing a set of process archive configuration properties. Attributes: None. Text Content: None.
`<property>`	`<properties>`	false	Set value for process archive configuration property Attributes: `name`: The name of the property. Text Content: The value of the property to be set.

Configuration Properties

The following is a list of all supported configuration properties.

Property name	Type	Description
`isDeleteUponUndeploy`	boolean	If true, the process engine deployment will be deleted (cascade = true) when the process application is undeployed. Default value: false.
`isScanForProcessDefinitions`	boolean	If true, the process application will be scanned for process definitions (bpmn20 and bpmn20.xml files). Default value: true.
`isResumePreviousVersions`	boolean	If true, previous versions of the deployment are automatically resumed. See the Process Application Deployment section of the User Guide for more details. Default value: true.
`isDeployChangedOnly`	boolean	If true, only resources that have changed become part of the deployment. This check is performed against previous deployments of the same name. Every resource contained in the process archive is compared to the most recent resource of the same name that is part of one of the previous deployments. Activating this setting does not automatically resume previous versions of the deployment. Default value: false. Note: It is not advised to use this setting when process elements are bound against resources of the same deployment. A binding is required when resources like a process definition from a call activity or an external script are referenced (see the BPMN implementation reference). For example, if a call activity uses the binding `deployment` and a certain process definition key, whether the process can be resolved depends on whether it was deployed. Thus it is recommended to use the binding `latest` or `version` when activating this setting.
`resourceRootPath`	string	The resource root of the process archive. This property is used when scanning for process definitions (if `isScanForProcessDefinitions` is set to true). The path is interpreted as local to the root of the classpath. By default or if the prefix `classpath:` is used, the path is interpreted as relative to the root of the classloader. Example: `path/to/my/processes` or `classpath:path/to/my/processes`) relative to the parent folder of the process archive's deployment descriptor file (processes.xml). If the prefix `pa:` is used, the path is interpreted as relative to the deployment descriptor defining the process archive. Consider the situation of a process application packaged as a WAR file: The deployment structure could look like this: \|-- My-Application.war \|-- WEB-INF \|-- lib/ \|-- Sales-Processes.jar \|-- META-INF/processes.xml (1) \|-- opps/openOpportunity.bpmn \|-- leads/openLead.bpmn \|-- Invoice-Processes.jar \|-- META-INF/processes.xml (2) If the process archive(s) defined in (1) uses a path prefixed with `pa:`, like for instance `pa:opps/`, only the `opps/`-folder of sales-processes.jar is scanned. More precisely, a "pa-local path", is resolved relative to the the parent directory of the META-INF-directory containing the defining processes.xml file. This implies that when using a pa-local path in (1), no processes from (2) are visible.
`additionalResourceSuffixes`	comma-seperated list	Specifies a list of additional suffixes which are considered as deployment resource if the `isScanForProcessDefinitions` property is set to `true`. It can be used to deploy additional resources beside process and case definitions, for example to add a script to the deployment and reference it as an external source (see the documentation about script source for more information). To specify multiple suffixes, a comma is used as seperator, ie. `py,groovy,rb`.

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 BPM 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	Turns on authorization checks.
`databaseSchemaUpdate`	String	Sets the value for process engine database schema creation. Values: `false`, `create-drop`, `true`.
`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`.
`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.
`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.
`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.
`history`	String	Sets the level of the process engine history. Values: `none`, `activity`, `audit`, `full`.
`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).
`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).
`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).
`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).
`defaultNumberOfRetries`	Integer	Controls how many retries should be accomplished for a failed job. Default value: `3`
`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_`.
`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).

Deployment Descriptor Reference

Overview