Update from 7.15 to 7.16
This document guides you through the update from Camunda Platform
7.16.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 administrators: Set Variables on Process Instance Migration
- For administrators: Upcoming Liquibase support
- For administrators and developers: New Version of Templating Engines (Freemarker, Velocity)
This guide covers mandatory migration steps as well as optional considerations for the initial configuration of new functionality included in Camunda Platform 7.16.
Every Camunda installation requires a database schema update. Check our database schema update guide for further instructions.
Note: Updating to Camunda Platform
7.16 from any version prior to
7.16 requires using the manual update approach.
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 Platform 7.16 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 you use a standalone web application, replace the current
war artifact by its new version.
Take the following steps to complete the update:
- Undeploy the current version of the standalone web application.
- Update the database to the new schema as described in the database update section.
- Configure the database as described in the installation
section. Note that with 7.16 the standalone web applications use HikariCP for data sources instead of Apache Commons DBCP. Replace the
targetDataSource’s bean class to
com.zaxxer.hikari.HikariDataSourceand rename the
urlparameter of the data source to
- Deploy the new and configured standalone web application to the server.
Set Variables on Process Instance Migration
We have extended the Process Instance Migration Batch Operation to set variables into the process instances’ scope. Please bear in mind that the usage of new features during a rolling update leads to unexpected behavior and therefore must be avoided: When a migration batch with variables is created during a rolling update, variables might or might not be set depending on the executing engine (old/new engine), and batch variables might not be removed when an old engine executes the monitor job.
Java 15 migration
With Nashorn not included in Java 15 anymore, you can move forward with any of the following:
Choose the section that fits your setup best to read on from the following:
- Embedded Process Engine / Spring Boot (Starter) Application
- Shared, Container-Managed Process Engine (with our without custom process applications)
- Standalone (Remote) Process Engine Server (e.g., using Camunda Run)
Embedded Process Engine
Please make sure you use the same version for both dependencies to ensure compatibility.
Shared Process Engine
Remote Process Engine
If you run those distributions on any Java version prior to Java 15, the JVM also includes the Nashorn scripting engine by default.
In order to provide a reliable behavior on those platforms, the Camunda Platform preferrably executes code for languages
- Camunda Platform Run
- JBoss AS / Wildfly
All other Camunda distributions consider this script engine as optional. If you do not add it when updating your distribution, it will not be available.
In this case, the Camunda Platform executes scripts with languages
ecmascript as it did before.
The Camunda Platform executes scripts with languages
ecmascriptas it did before. Note that this is not possible on JBoss AS/Wildfly and Camunda Platform Run without further adjustments.
- Set the engine configuration option
ecmascript. Setting this option to
nashornenables the previous execution behavior. Note that this is not possible out-of-the-box anymore starting with Java 15. The Nashorn scripting engine is not included there anymore.
- Set script language of your scripts to a script engine-specific value per script, for example
Camunda Form Definition parsing
The 7.16.0 release introduces a new database entity called Camunda Form Definition. After Process, Decision, and Case Definition, this is the fourth definition entity in the engine. Camunda Form Definitions represent a Camunda Form and introduce versioning and more powerful ways of referencing Camunda Forms from other deployments.
To create Camunda Form Definitions, the engine will parse the form JSON when it is deployed. All files with the
.form file ending will be treated as Camunda Form Definitions. This
might lead to unwanted behavior in cases where files with the
.form ending that are not Camunda Forms already exist or are deployed to the engine. In those cases, the parser will throw
an exception as the definition could not be parsed correctly.
Upcoming Liquibase support
Starting with Camunda Platform
7.16.0, Liquibase can be used to install the database schema and keep track of necessary changes to it.
However, Liquibase can NOT be used to update from
7.16. Please use the manual update approach for that.
Nonetheless, you can already migrate to Liquibase as soon as you updated to
7.16.0 and prepare your installation for any future updates.
New Version of Templating Engines (Freemarker, Velocity)
Camunda 7.16 includes version 2.1.0 of the
org.camunda.template-engines artifacts, in particular
This updates the following template engine versions:
- Apache Freemarker
- Old version: 2.3.29 (Release date: August 2019)
- New version: 2.3.31 (Release date: February 2021)
- Change log: https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-
- Apache Velocity
- Old version: 2.2 (Release date: January 2020)
- New version: 2.3 (Release date: March 2021)
- Change log: https://velocity.apache.org/engine/2.3/upgrading.html
Please note that the new version of Freemarker contains changes that are not compatible with the previous version. We strongly recommend to test the execution of your templates before applying the update. In addition, you can replace the artifacts of version 2.1.0 by the old artifacts in version 2.0.0 to continue using the old versions of Freemarker and Velocity.