Update from 7.19 to 7.20
This document guides you through the update from Camunda Platform
7.20.0 and covers the following use cases:
- For administrators and developers: Database updates
- For administrators and developers: Full distribution update
- For developers: Enforce History Time To Live
- For administrators: Explicit JUEL module on Jakarta Expression Language 4
- For developers: Explicit asset declaration in Java web app plugins
- For administrators: Optimistic Locking on PostgreSQL
- For developers: Changes on persistence connection exception logging of the REST API
- For developers: Spring Framework 6.0 support
- For developers: Upgrade to Spring Boot 3.1
- For developers: External Task Client Spring Boot Starter requires JDK 17
- For developers: Camunda Platform Run requires JDK 17
- For developers: Update Alpine Base Docker Image from version 3.15 to 3.18
- For developers: Quarkus 3 update
- For developers: Discontinued support for JDK 8
- For administrators: Discontinued support of Standalone web application
- For developers: Discontinued support for handling JPA entities as variables
- For developers: Discontinued support for Velocity, XSLT, and XQuery template engines
This guide covers mandatory migration steps and optional considerations for the initial configuration of new functionality included in Camunda Platform 7.20.
Every Camunda installation requires a database schema update. Check our database schema update guide for further instructions.
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, ensure you have downloaded the Camunda Platform 7.20 distribution for the application server you use. This 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
Removed support for WebSphere 9
Support for WebSphere 9 was discontinued with the Camunda Platform 7.20.0 release. Some of the artifacts that are compatible with WebSphere 9 have been renamed. See details in the dedicated IBM WebSphere Liberty guide.
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 the following:
There are no new mandatory dependencies for process applications.
Enforce History Time To Live
Many of our users have installations that contain model resources (BPMN, DMN, CMMN) with null historyTimeToLive. As a result, their historic data grow over time and remain uncleaned due to this configuration. The history data of your executed processes will clutter the database and eventually negatively impact the engine’s performance – even for runtime processes. Since the engine uses a relational database, only starting to clean up the history when a vast amount of data has been pilled up is very costly and time-consuming – in some situations, there is even no other solution than truncating tables and losing data. This is why with this release we decided to make the historyTimeToLive mandatory for new deployments or redeployments.
At the same time, we acknowledge there might be use cases (e.g. when there are no history events fired at all,
see history level configuration)
where our users might favour to keep the legacy behaviour despite our recommendation.
If that is the case, you can always turn off the feature by setting the feature flag
For more information, checkout the new parameter description under Configuration Properties.
Explicit JUEL module on Jakarta Expression Language 4
Camunda supports using small script-like expressions in many locations as described in our Expression Language guide. Up to version 7.19.x, this support is based on a JSP 2.1 standard-compliant implementation of the open source library JUEL. The source code of that library is embedded into and distributed with our core
With this version, we removed that source code from the core artifact and created a dedicated library called
camunda-juel. This library is based on the Jakarta Expression Language 4.0 specification, a successor of the JSP 2.1 standard. This allows us to benefit from the many improvements that have been incorporated into the expression language API since the creation of the JSP 2.1 standard. The new expression language API is integrated into the Camunda JUEL library and relocated inside it to avoid any classpath pollution related to the official Jakarta Expression Language API that might be present in your environment.
Our pre-packaged distributions all come with the new Camunda JUEL library by default. If you’re updating your distribution from 7.19.x or earlier, consult your environment-specific guide on how to add the library. If you’re relying on the
camunda-engine artifact itself in your application, the new module will come as a transitive dependency automatically.
If you are using any JUEL or expression language-related classes that formerly resided in the
camunda-engine artifact in your custom application, note that the package names change as follows:
- Classes from
org.camunda.bpm.engine.impl.javax.*now reside in
- Classes from
de.odysseus.el.*now reside in
Updating to a newer expression language standard comes with some behavioral changes, the most noteworthy ones being the following:
- Bean method invocation changes with regards to method parameters. All values, including
nullvalues, are converted as described in the EL API specification. As a result,
nullvalues will be coerced into the type defined by the method. For example, calling
myBean.setStringAttribute(null), requiring a
Stringparameter, now leads to
nullbeing coerced into an empty String
"". Previously, the
nullvalue was passed on as is.
- Method resolution is more reliable and supports overloaded methods. Method candidates are resolved by name and then matched by parameter count and types. If multiple candidates exist (overloaded methods), the most specific one is used. For example, method
Integeris chosen over method
Objectif the provided parameter is an
Integeror can be coerced into one. Previously, the first method candidate by name from the array returned by
Class#getMethodswas taken. However, the order of methods is not defined for that array. As a result, the wrong method was chosen and an exception was thrown due to an incompatible parameter in many cases.
- Method invocation only works with publicly accessible members to provide a more reliable security model and honor the accessibility contracts of classes. Protected methods, private methods, and methods of private, protected, or anonymous inner classes cannot be accessed. Previously, you could invoke non-public methods as well.
ElContextand its subclasses like
nullvalue is set to it using the
#putContextmethod. Previously, the context allowed to set
We recommend testing your existing expressions thoroughly before using version 7.20.x in production and adjusting them according to the beforementioned behavioral changes.
Explicit asset declaration in Java web app plugins
We introduced a change in the asset loading mechanism for Java web app plugins. Starting with this release,
plugin assets must be explicitly declared in the plugin root resource class.
You can declare your assets by overriding the
AbstractAppPluginRootResource#getAllowedAssets() method in your root resource.
The default implementation contains two predefined assets:
For many plugins this might be already sufficient and will require no further assets to be allowed.
Make sure to double-check and declare the required assets in your plugin root resource. Requests for undeclared assets will be rejected, and it will likely render your plugin unusable.
Optimistic Locking on PostgreSQL
With version 7.20.0, we adjusted the Optimistic Locking behavior on PostgreSQL in case of Foreign Key Constraint violations. Any violation of such a constraint in INSERT and UPDATE statements now leads to an OptimisticLockingException. In effect, the engine’s behavior on PostgreSQL in such scenarios is consistent with the other supported databases.
If you rely on the previous behavior, receiving
ProcessEngineExceptions with the related error code for foreign key constraint violations, you can restore it by disabling the engine configuration flag
enableOptimisticLockingOnForeignKeyViolation. As a result, jobs can also start failing due to those exceptions although they could be safely retried automatically to resolve the situation.
Changes on persistence connection exception logging of the REST API
All persistence connection exceptions will be logged with logging level ERROR instead of WARN from now on. You can read more about SQL connection exceptions & SQL classes here.
calling task service APIs like
#complete. You could handle these errors only by subscribing to a
global error handler.
With this release, the client re-throws errors, additionally directly on calling the respective task service APIs, and you can handle them directly. Adjust your custom business logic accordingly.
Spring Framework 6.0 support
The newly created
engine-spring-6 module provides support to Spring Framework 6.0 with the following maven coordinates:
<dependency> <groupId>org.camunda.bpm</groupId> <artifactId>camunda-engine-spring-6</artifactId> </dependency>
The most noteworthy changes from the new major version are JDK 17+ and Jakarta EE 9+ baseline. To adjust your applications, follow the Spring Framework upgrade guide and check the Spring Framework 6.0 goes GA blog post.
Camunda Platform introduces Spring Framework 6.0 support for:
- Spring Boot Starter
- WildFly Application Server 27
Upgrade to Spring Boot 3.1
The Camunda Engine now offers support for Spring Boot 3.1. The new major version builds on Spring Framework 6.0 and brings changes such as JDK 17 baseline and switching to the Jakarta namespace.
For a complete list of new features and changes, check the Spring Boot 3.0 and Spring Boot 3.1 release notes. Have a look at the Spring Boot update guide to migrate your applications from Spring Boot 2.7.
The switch to the Jakarta namespace requires the Spring Boot Starter and other modules to now rely on Camunda Platform modules that are created for this purpose. For example, if you want to build a custom webjar, keep the following changes in mind:
camunda-webapp-jakartafor building the Spring Boot webjar.
External Task Client Spring Boot Starter requires JDK 17
After adopting Spring Boot 3, the External Task Client Spring Boot Starter requires Java 17.
Camunda Platform Run requires JDK 17
Starting with Camunda Platform 7.20, the Camunda Platform Run distribution requires Java Runtime Environment 17 installed.
Update Alpine Base of Camunda Docker images from Version 3.15 to 3.18
The Camunda Docker images are based on Alpine. This release updates the Alpine base docker image from version 3.15 to 3.18. Please find the changes in detail at the official sources below:
Quarkus 3 update
We have updated our Quarkus Extension to the latest Quarkus 3 version. This version brings many new features and changes. For a complete list, see the Quarkus 3 major release blog post. From the extension’s perspective, the most important changes are the deprecation of Java 11 and the switch to Jakarta EE 10. With the update, the JSF Task Forms use case is not supported out of the box anymore in a Quarkus application.
Quarkus has a very comprehensive guide for updating and also offers an update tool.
You can find more details about the extension on our dedicated Quarkus Integration page.
Discontinued support for JDK 8
With version 7.20, we discontinue support for JDK 8 and require a minimum of Java Runtime Environment 11 for building and operating Camunda Platform. As mentioned above, Spring Boot-related applications already require Java Runtime Environment 17.
Discontinued support of Standalone web application
Camunda Automation Platform 7.19 is the last release providing support for Standalone Web Application Distribution. Version 7.20.0 no longer provides this distribution.
Discontinued support for handling JPA entities as variables
The process engine will no longer process JPA entities as variables affecting the following components:
- Process engine (
- Spring Framework integration (
- Spring Boot Starter (
In case your projects have used the removed JPA variable serializer, you must create custom JPA serializer logic for the variables that have been created already. Without providing a JPA variable serializer, when previously created JPA variable is retrieved, a
ProcessEngineException will be thrown for
ENGINE-03040 No serializer defined for variable instance. Futher ensure the serializer loads correctly already persisted entities before updating to 7.20 version.
You can re-create the removed logic in your project and register a JPA variables serializer as a process engine plugin. As a step by step guide how to achieve that, we created an example.
Discontinued support for Velocity, XSLT, and XQuery template engines
We discontinue support for template engines with the following Maven artifacts (groupId:artifactId):
We moved the source code of the template engines listed above over to Camunda’s Community Hub and released version 2.2.0, the first community release and last release triggered by us.
You can contribute to the GitHub repository if you require code changes, library updates, or bug fixes. Camunda doesn’t drive development for community extensions.
If you want to continue to use the community-maintained template engines, use the following Maven coordinates:
<dependency> <groupId>org.camunda.community.template.engine</groupId> <artifactId>camunda-7-template-engine-velocity</artifactId> <version>2.2.0</version> </dependency> <dependency> <groupId>org.camunda.community.template.engine</groupId> <artifactId>camunda-7-template-engine-xquery</artifactId> <version>2.2.0</version> </dependency> <dependency> <groupId>org.camunda.community.template.engine</groupId> <artifactId>camunda-7-template-engine-xslt</artifactId> <version>2.2.0</version> </dependency>
We are looking for maintainers for the template engine extensions. Feel free to reach out to us via the forum if you are interested.