Update from 7.12 to 7.13
This document guides you through the update from Camunda BPM
7.13.0. It covers these use cases:
- For administrators and developers: Database Updates
- For administrators and developers: Full Distribution Update
- For administrators: Standalone Web Application
- For developers: Spring Boot Starter Update
- For developers: External Task Client Update
- For developers: Identity Service Queries
- For developers: MetricsReporterIdProvider interface Deprecation
- For administrators and developers: New Version of Templating Engines (Freemarker, Velocity)
- For developers: Entirely Replaced FEEL Engine
This guide covers mandatory migration steps as well as optional considerations for the initial configuration of new functionality included in Camunda BPM 7.13.
Every Camunda installation requires a database schema update.
Check for available database patch scripts for your database that are within the bounds of your update path. Locate the scripts at
$DISTRIBUTION_PATH/sql/upgradein the pre-packaged distribution (where
$DISTRIBUTION_PATHis the path of an unpacked distribution) or in the Camunda Nexus. We highly recommend executing these patches before updating. Execute them in ascending order by version number. The naming pattern is
Execute the corresponding update scripts named
The scripts update the database from one minor version to the next, and change the underlying database structure. So make sure to backup your database in case there are any failures during the update process.
We highly recommend to also check for any existing patch scripts for your database that are within the bounds of the new minor version you are updating to. Execute them in ascending order by version number. Attention: This step is only relevant when you are using an enterprise version of the Camunda BPM platform, e.g.,
X > 0. The procedure is the same as in step 1, only for the new minor version.
This section is applicable if you installed the Full Distribution with a shared process engine.
The following steps are required:
- Update the Camunda libraries and applications inside the application server
- Migrate custom process applications
Before starting, make sure that you have downloaded the Camunda BPM 7.13 distribution for the application server you use. It contains the SQL scripts and libraries required for the update. This guide assumes you have unpacked the distribution to a path named
Camunda Libraries and Applications
Please choose the application server you are working with from the following list:
Custom Process Applications
For every process application, the Camunda dependencies should be updated to the new version. Which dependencies you have is application- and server-specific. Typically, the dependencies consist of any of the following:
There are no new mandatory dependencies for process applications.
Standalone Web Application
If the standalone web application is in use, the current
war artifact must be replaced by its new version.
If a database other than the default H2 database is used, the following steps must be taken:
- Undeploy the current version of the standalone web application
- Update the database to the new schema as described in the database update section
- Reconfigure the database as described in the installation section
- Deploy the new and configured standalone web application to the server
Spring Boot Starter Update
Starting with version 7.13, the
camunda-bpm-spring-boot-starter library has been migrated into the
The library version has therefore changed from Camunda Spring Boot Starter (currently at 3.4.x) to the Camunda BPM Platform version (7.13.0).
The Maven coordinates have not changed otherwise.
Overriding the Camunda version used by the Spring Boot Starter is not necessary anymore. Pick the version of the Starter that resembles the version of Camunda BPM you would like to use.
If you are using Camunda Spring Boot Starter within your Spring Boot application, then you need to:
- Check Version Compatibility Matrix
- Update Spring Boot Starter and, when required, Spring Boot versions in your
- Remove the Camunda BPM version from your
pom.xmlin case you overrode it before (e.g. when using the enterprise version or a patch release).
External Task Client Update
If you are using the Camunda External Task Client, please make sure to:
- Check out the Version Compatibility Matrix
- Update the version in your
Identity Service Queries
When you provide …
- a custom identity provider implementation by implementing the interface
- AND a dedicated implementation of Identity Service Queries (e. g.
With this release, you need to implement a new API method
so that the REST API works appropriately.
Please read more about it in the User Guide.
MetricsReporterIdProvider interface Deprecation
As of version 7.13, the
MetricsReporterIdProvider interface has been deprecated. By default, the
Metrics Reporter identifier now uses the
SimpleIpBasedProvider class, which was ported to
implement the new
HostnameProvider interface. The
HostnameProvider interface, and it’s default
SimpleIpBasedProvider implementation, are used to generate
hostname information for the Historic
Job Logs as well.
In case a custom implementation of the
MetricsReporterIdProvider interface is used, it is
recommended to port it to the new
HostnameProvider interface and set it to the appropriate Process
Engine Configuration property (read more about it here).
Otherwise, different values will be provided for the Metrics Reporter identifier and the Historic
Job Logs hostname information.
New Version of Templating Engines (Freemarker, Velocity)
Camunda 7.13 includes version 2.0.0 of the
org.camunda.template-engines artifacts, in particular
This updates the following template engine versions:
- Apache Freemarker
- Old version: 2.3.20 (Release date: June 2013)
- New version: 2.3.29 (Release date: August 2019)
- Change log: https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-
- Apache Velocity
- Old version: 1.7 (Release date: November 2010)
- New version: 2.2 (Release date: January 2020)
- Change log: https://velocity.apache.org/engine/2.2/upgrading.html
Please note that the new versions of Freemarker and Velocity contain changes that are not compatible with the previous versions. We strongly recommend to test the execution of your templates before applying the update. In addition, you can replace the artifacts of version 2.0.0 by the old artifacts in version 1.1.0 to continue using the old versions of Freemarker and Velocity.
Entirely Replaced FEEL Engine
With this release, we replaced the old FEEL Engine completely. From now on, Camunda BPM uses the FEEL Scala Engine (opens external link) by default. You can restore the legacy behavior via a configuration property.
New Custom Function Mechanism
The FEEL Engine provides an all-new Custom Function mechanism. It is now possible to register Custom Functions programmatically. Please read all about it in the documentation about Custom FEEL Functions. The old way to register a Custom Function is not supported with the new FEEL Engine.
New Default Expression Languages
The FEEL Engine changes the default Expression Languages for certain DMN Notation Elements:
|DMN Notation Element||Old||New|
Expression languages defined in the DMN Model (*.dmn file) will override the defaults.
New Logger Category
The new FEEL Engine uses the slf4j logging “facade”, as defined in the Camunda docs.
However, since the new FEEL Engine is an independently maintained project,
it defines its own logger category. Users that filter the old FEEL Engine logs will need to update
their configurations by adding a configuration for the new FEEL Engine logger category
For the Camunda-related integration code of the Scala FEEL Engine, the new,
org.camunda.bpm.dmn.feel.scala logger category was added. The logs under this category will
cover only the “Scala FEEL Engine”-related operations. For a more general configuration, the old
org.camunda.bpm.dmn.feel can still be used. If a more fine-grained configuration is needed, the
new logger category can be utilized.
Differences in the Expression Language
Make sure to migrate your Expressions to FEEL 1.2 when using the new FEEL Engine. The legacy FEEL Engine has a partial coverage of FEEL 1.1.
Additionally, make sure your FEEL expressions respect the following breaking changes.
Objects Cannot Be Compared
Previously it was possible to compare objects when the class of the respective objects implements
java.lang.Comparable. Objects cannot be compared with the new FEEL Engine.
Spin Java API Cannot Be Called
The handling of Spin-based JSON & XML variables has changed fundamentally. For more information, please see the documentation about FEEL Engine Spin Integration. The Spin Java API cannot be called directly in FEEL Expressions with the new FEEL Engine.
Beans Are Not Automatically Resolved
Previously, the FEEL Engine took care of resolving beans automatically. Beans are not automatically resolved with the new FEEL Engine.
Changed Exception Classes
The following exception classes were consolidated to
Single-Quoted String Literals Not Allowed
Previously, double-quoted as well as single-quoted string literals were allowed. The new FEEL Engine is more strict on the specification here. Use single quotes for string literals in expressions.
Example: Migrate ‘foo’ to “foo”
Single-quoted string literals are considered as a bug in the old FEEL Engine.
Timezone Information Is Respected
From now on, an exception is thrown when a variable of type
java.util.Date is compared with the
date and time("2019-09-12T13:00:00@Europe/Berlin").
Ignoring the timezone information is considered as a bug in the old FEEL Engine.
Known Issues in the New FEEL Engine
Please also check out the status of the following known issues when migrating your FEEL Expressions: