Update from 7.21 to 7.22
This document guides you through the update from Camunda 7.21.x
to 7.22.0
and covers the following use cases:
- For administrators and developers: Database updates
- For administrators and developers: Full distribution update
- For administrators and developers: Camunda Spin
- For developers: Camunda Commons
- For developers: Camunda Template Engines FreeMarker
- For developers: Camunda Connect
- For developers: Camunda Connect dependency removed from
camunda-engine
- For administrators and developers: Update to JBoss EAP 8.0
- For administrators and developers: Update to Tomcat 10 Server
- For administrators and developers: Camunda Run and Swagger Update
- For administrators and developers: Update to Groovy 4.0
- For administrators and developers: Sending telemetry feature removed
- For administrators: Database transaction isolation level
READ_COMMITTED
is enforced - For developers: Quarkus 3.14 Extension Update
This guide covers mandatory migration steps and optional considerations for the initial configuration of new functionality included in Camunda 7.22.
Database updates
Every Camunda installation requires a database schema update. Check our database schema update guide for further instructions.
Full distribution
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 7.22 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 $DISTRIBUTION_PATH
.
Camunda Spin
We’ve moved the camunda-spin
project from its previous location into the mono repository. We’re no longer versioning it independently. Instead, we’ve integrated it into the 7.X.Y versioning scheme, so you can conveniently declare Camunda 7.22.0-alpha1
to use the latest release of Camunda Spin.
Camunda Commons
We’ve moved the camunda-commons
project from its previous location into the mono repository. We’re no longer versioning it independently. Instead, we’ve integrated it into the 7.X.Y versioning scheme, so you can conveniently declare Camunda 7.22.0-alpha1
to use the latest release of Camunda Commons.
We’ve also updated the camunda-commons-bom
to include camunda-commons-typed-values
. Now, you can manage all Camunda commons dependency versions directly through the camunda-commons-bom
.
Camunda Template Engines FreeMarker
We’ve moved the camunda-template-engines-freemarker
project from its previous location into the mono repository. We’re no longer versioning it independently. Instead, we’ve integrated it into the 7.X.Y versioning scheme, so you can conveniently declare Camunda 7.22.0-alpha2
to use the latest release of Camunda Template Engines FreeMarker.
Camunda Connect
We’ve moved the camunda-connect
project from its previous location into the mono repository. We’re no longer versioning it independently. Instead, we’ve integrated it into the 7.X.Y versioning scheme, so you can conveniently declare Camunda 7.22.0-alpha2
to use the latest release of Camunda Connect.
Camunda Connect dependency removed from camunda-engine
camunda-connect
is no longer dependency to camunda-engine
and respectively in pre-packaged distributions (Tomcat, WildFly).
If you use Camunda Connect functionality, check if you need to re-introduce the following dependencies to your project:
camunda-connect-core
camunda-connect-connectors-all
camunda-connect-http-client
camunda-connect-soap-http-client
Update to JBoss EAP 8
With this release, we support JBoss EAP 8.0, it’s Jakarta EE compliant platform. The artifacts are shipped with the latest pre-packaged Camunda 7 WildFly distribution. If you prefer to stay on JBoss EAP 7, you can still download the Java EE compliant modules, web application, and REST API.
To work with JBoss EAP 8, consider the following when migrating your process applications and replacing artifacts on the application server:
Migrate process applications
- Replace Java EE class references (
javax.*
) with Jakarta class references (jakarta.*
)- You might have a look at
org.eclipse.transformer:transformer-maven-plugin
- You might have a look at
- Replace Camunda class references:
org.camunda.bpm.application.impl.EjbProcessApplication
→org.camunda.bpm.application.impl.JakartaEjbProcessApplication
org.camunda.bpm.application.impl.ServletProcessApplicationDeployer
→org.camunda.bpm.application.impl.JakartaServletProcessApplicationDeployer
org.camunda.bpm.application.impl.ServletProcessApplication
→org.camunda.bpm.application.impl.JakartaServletProcessApplication
org.camunda.bpm.engine.impl.cfg.jta.JtaTransactionContext
→org.camunda.bpm.engine.impl.cfg.jta.JakartaTransactionContext
org.camunda.bpm.engine.impl.cfg.jta.JtaTransactionContextFactory
→org.camunda.bpm.engine.impl.cfg.jta.JakartaTransactionContextFactory
org.camunda.bpm.engine.impl.cfg.JtaProcessEngineConfiguration
→org.camunda.bpm.engine.impl.cfg.JakartaTransactionProcessEngineConfiguration
org.camunda.bpm.engine.impl.interceptor.JtaTransactionInterceptor
→org.camunda.bpm.engine.impl.interceptor.JakartaTransactionInterceptor
- Replace Camunda Maven dependencies:
org.camunda.bpm.javaee:camunda-ejb-client
→org.camunda.bpm.javaee:camunda-ejb-client-jakarta
org.camunda.bpm:camunda-engine-cdi
→org.camunda.bpm:camunda-engine-cdi-jakarta
Replace artifacts on the application server
You can find the new artifacts either in the current WildFly distribution or in the camunda-wildfly-modules
.
Replace modules
$WILDFLY_HOME/modules/org/camunda/spin/camunda-spin-dataformat-xml-dom
→$WILDFLY_HOME/modules/org/camunda/spin/camunda-spin-dataformat-xml-dom-jakarta
- Camunda WildFly Subsystem under
$JBOSS_HOME/modules/org/camunda/bpm/$APP_SERVER/camunda-wildfly-subsystem
Replace web application (Cockpit, Admin, Tasklist, Welcome) deployment
Replace the artifact camunda-webapp-jboss-$PLATFORM_VERSION.war
with camunda-webapp-wildfly-$PLATFORM_VERSION.war
under $JBOSS_HOME/standalone/deployments
.
Replace REST API deployment
Replace the artifact camunda-engine-rest-$PLATFORM_VERSION-wildfly.war
with camunda-engine-rest-jakarta-$PLATFORM_VERSION-wildfly.war
under $JBOSS_HOME/standalone/deployments
.
Update to Tomcat 10 Server
This version brings support for Tomcat 10.1
. A few reasons to upgrade are:
- Namespace Change: Switch from
javax.*
tojakarta.*
for future compatibility. - Enhanced Security: Improved security features and fixes.
- Modern Features: Supports
Servlet 6.0
,JSP 3.1
, andWebSocket 2.1
. - Performance Improvements: Faster response times and better resource efficiency.
- Simplified Migration: Tools and documentation for easier transition from earlier versions.
- Better Integration: Enhanced compatibility with
Jakarta EE
components and third-party libraries.
From now on, our pre-packaged Tomcat distribution is built with Tomcat 10.1
.
Additionally, the Tomcat Docker image will, from now on, utilize Tomcat 10.1
.
If you prefer to stay on Tomcat 9
, you can still download the Java EE
compliant web application, and REST API.
To work with Tomcat 10
, consider the following when migrating your process applications and replacing artifacts on the application server:
Migrate process applications
- Replace Java EE class references (
javax.*
) with Jakarta class references (jakarta.*
)- You might have a look at
org.eclipse.transformer:transformer-maven-plugin
- You might have a look at
- Replace Camunda class references:
org.camunda.bpm.application.impl.EjbProcessApplication
→org.camunda.bpm.application.impl.JakartaEjbProcessApplication
org.camunda.bpm.application.impl.ServletProcessApplicationDeployer
→org.camunda.bpm.application.impl.JakartaServletProcessApplicationDeployer
org.camunda.bpm.application.impl.ServletProcessApplication
→org.camunda.bpm.application.impl.JakartaServletProcessApplication
org.camunda.bpm.engine.impl.cfg.jta.JtaTransactionContext
→org.camunda.bpm.engine.impl.cfg.jta.JakartaTransactionContext
org.camunda.bpm.engine.impl.cfg.jta.JtaTransactionContextFactory
→org.camunda.bpm.engine.impl.cfg.jta.JakartaTransactionContextFactory
org.camunda.bpm.engine.impl.cfg.JtaProcessEngineConfiguration
→org.camunda.bpm.engine.impl.cfg.JakartaTransactionProcessEngineConfiguration
org.camunda.bpm.engine.impl.interceptor.JtaTransactionInterceptor
→org.camunda.bpm.engine.impl.interceptor.JakartaTransactionInterceptor
- Replace Camunda Maven dependencies:
org.camunda.bpm.javaee:camunda-ejb-client
→org.camunda.bpm.javaee:camunda-ejb-client-jakarta
org.camunda.bpm:camunda-engine-cdi
→org.camunda.bpm:camunda-engine-cdi-jakarta
Migrate Java webapp plugins
Replace Java EE class references (javax.*
) with Jakarta class references (jakarta.*
)
Replace web application (Cockpit, Admin, Tasklist, Welcome) deployment
Replace the artifact camunda-webapp-tomcat-$PLATFORM_VERSION.war
with camunda-webapp-tomcat-jakarta-$PLATFORM_VERSION.war
under $CATALINA_HOME/webapps
.
Replace REST API deployment
Replace the artifact camunda-engine-rest-$PLATFORM_VERSION-tomcat.war
with camunda-engine-rest-jakarta-$PLATFORM_VERSION-tomcat.war
under $CATALINA_HOME/webapps
.
Migrating to the Tomcat 10 Docker Image
If your application uses a Docker image based on Tomcat 9
, you need to perform the above migration steps yourself before your application is compatible with the jakarta
namespace changes the new Tomcat version introduces.
If your application uses a Docker image based on Tomcat 9
, you need to perform the above migration steps yourself before your application is compatible with the jakarta
namespace changes the new Tomcat version introduces.
Weld Class Loading Issues
In deployment scenarios involving one or more process applications with managed beans, classloading issues may occur if the WELD library is directly embedded in the WAR’s /WEB-INF/lib
folder.
To resolve this, move the weld library away from the war and place it into the $CATALINA_HOME/lib
folder.
The above workaround is not guaranteed to work for cases with bean references between WAR deployments (WAR A referencing a bean from WAR B).
The following test scenarios fail on Tomcat 10:
Camunda Run and Swagger Update
Swagger UI was included in Camunda Run distros for a long time. Unfortunately, maintaining Swagger for Run was a lot of work. Other tools (like Postman or Swagger Editor) provide the same functionality outside of Camunda run. That is why we decided to discontinue Swagger in camunda-run
to reduce maintenance efforts.
From now on, the --swaggerui
argument is not available for Camunda Run start scripts, and the Swagger artifacts are not included in the Camunda Run distros anymore.
Instead, you can always use open-api in conjunction with a REST
client of your choice such as POSTMAN to achieve similar results.
Update to Groovy 4
We have updated the Groovy version from 2.4
to 4.0
.
Migrate your scripts
To continue running your Groovy scripts in the Camunda Engine, please read and act on the following release notes, especially the breaking changes:
To make the migration process easier, we have included the groovy-dateutil
and groovy-datetime
libraries in the Camunda Platform release. groovy-dateutil
contains the extension methods for the java.util.Date
class, while groovy-datetime
allows using operator overloading, closures, and Groovy’s dynamic methods on java.time
.
What if I can’t migrate my scripts?
It is possible to keep using Camunda Platform with a lower version of Groovy if GROOVY-VERSION is the desired version.
If using a full distribution of Camunda:
- Remove
groovy-dateutil-4.0.x.jar
andgroovy-datetime-4.0.x.jar
. - Replace
groovy-4.0.x.jar
,groovy-json-4.0.x.jar
,groovy-xml-4.0.x.jar
, andgroovy-templates-4.0.x.jar
libraries withgroovy-{GROOVY-VERSION}.jar
,groovy-json-{GROOVY-VERSION}.jar
,groovy-xml-{GROOVY-VERSION}.jar
, andgroovy-templates-{GROOVY-VERSION}.jar
.
If using Embedded Engine:
- You can keep using your Groovy version without any extra effort.
Sending telemetry feature removed
Sending telemetry data has been introduced in Camunda 7.14.0+
(and 7.13.7
, 7.12.12
, 7.11.19
)
and removed in Camunda 7.22.0
. The public API is marked as deprecated and emptied out.
The telemetry reporter and scheduled timer and all related process engine configuration properties are removed.
The diagnostic data is still being collected but not sent by any mean.
You can decide to share it with Camunda if requested in tickets or use it for your diagnostic purposes.
In previous Camunda versions - 7.21.0+
, 7.20.8+
, 7.19.15+
, reporting telemetry data is disabled by default.
Configuration properties removed
To clean up and refactor our source code, the following process engine configuration properties have been removed. Please remove all of the occurrences of those properties, regardless of the setup that you are using (share or embedded process engine, pre-packaged or other distribution). You need to remove the properties from your tests as well.
initializeTelemetry
telemetryReporterActivate
telemetryReportingPeriod
telemetryReporterActivate
telemetryRequestRetries
telemetryRequestTimeout
Public API deprecation
The public API for configuring telemetry and fetching the telemetry configuration have been emptied out and marked as deprecated. We recommend to remove the usage of the following API as the endpoints no longer do anything and their usage is unnecessary.
- Java API
ManagementService#isTelemetryEnabled()
(always returnsfalse
)ManagementService#toggleTelemetry(boolean)
- REST API
- Fetch Telemetry Configuration (always returns
false
) - Configure Telemetry
- Fetch Telemetry Configuration (always returns
Database transaction isolation level READ_COMMITTED
is enforced
When starting the engine, a check is performed in order to determine if the transaction isolation level set for the database is different from the recommended one READ_COMMITTED
. If it is, an exception will be thrown.
This behaviour can be disabled by setting the skipIsolationLevelCheck
flag to true
. Doing this will prevent an exception from being thrown and a warning message will be logged instead.
See here for more details about this and other properties.
Quarkus 3.15 Extension Update
The Camunda Quarkus Extension has been updated to use Quarkus 3.15
. This version brings its own features and changes.
For a complete list, see the Quarkus 3.15 LTS Release blog post.
Breaking Changes
Quarkus 3.15
and previous versions extensions introduce breaking changes in the way the Quarkus runtime treats configuration.
A configuration migration is required to remain consistent with the new behavior of the framework (see property examples below).
The config properties now follow a similar scheme to the Camunda Spring Boot Starter Configuration.
The change affects the configuration of the process engine and the job executor.
Reason for Change: The Quarkus migration guide encourages using named ConfigMappings
, and we chose to adopt it to future-proof the extension.
This requires using the new namespace generic-config
.
quarkus.camunda.enforce-history-time-to-live
becomesquarkus.camunda.generic-config.enforce-history-time-to-live
quarkus.camunda.dmn-enabled
becomesquarkus.camunda.generic-config.dmn-enabled
Non-generic properties such as
quarkus.camunda.job-executor.thread-pool.max-pool-size
remain the same.
For a detailed guide on the new Quarkus properties, visit the updated Quarkus Configuration page.
To read more on how Quarkus extensions treat configuration differently, see this Quarkus Migration Guide and the Mapping Configuration to Objects Guide.