This document guides you through the update from Camunda 7.21.x to 7.22.0 and covers the following use cases:

1. For administrators and developers: Database updates
2. For administrators and developers: Full distribution update
3. For administrators and developers: Camunda Spin
4. For developers: Camunda Commons
5. For developers: Camunda Template Engines FreeMarker
6. For developers: Camunda Connect
7. For developers: Camunda Connect dependency removed from camunda-engine
8. For administrators and developers: Update to JBoss EAP 8.0
9. For administrators and developers: Update to Tomcat 10 Server
10. For administrators and developers: Camunda Run and Swagger Update
11. For administrators and developers: Update to Groovy 4.0
12. For administrators and developers: Sending telemetry feature removed
13. For administrators: Database transaction isolation level READ_COMMITTED is enforced
14. For developers: Quarkus 3.14 Extension Update
15. For administrators and developers: Process Instance Modification Filter Changes

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:

1. Update the Camunda libraries and applications inside the application server.
2. 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
• 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.* to jakarta.* for future compatibility.
• Enhanced Security: Improved security features and fixes.
• Modern Features: Supports Servlet 6.0, JSP 3.1, and WebSocket 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
• 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:

• CallActivityContextSwitchTest
• CdiBeanCallActivityResolutionTest

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:

• Groovy 2.5
• Groovy 3.0
• Groovy 4.0

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 and groovy-datetime-4.0.x.jar.
• Replace groovy-4.0.x.jar, groovy-json-4.0.x.jar, groovy-xml-4.0.x.jar, and groovy-templates-4.0.x.jar libraries with groovy-{GROOVY-VERSION}.jar, groovy-json-{GROOVY-VERSION}.jar, groovy-xml-{GROOVY-VERSION}.jar, and groovy-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 returns false)
  • ManagementService#toggleTelemetry(boolean)
• REST API
  • Fetch Telemetry Configuration (always returns false)
  • Configure Telemetry

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 becomes quarkus.camunda.generic-config.enforce-history-time-to-live

• quarkus.camunda.dmn-enabled becomes quarkus.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.

Process Instance Modification Filter Changes

The Process Definition View dialog of Camunda Cockpit has been updated to use the Historic API. With this change, the start date filter is now available within the workflow.

Saved Filters are Now Isolated

Filters saved in the Modify Process Instance workflow were previously shared across other pages. With this update, the filters of Modify Process Instance workflow and other pages are isolated and independent of each other.

Edge Cases with Behavioral Changes

• Tokens on Async Tasks: Tokens sitting on an asyncBefore/asyncAfter task will not yield process instances when using the activityIdIn filter, as no history has been produced yet. Filtering here is effectively racing against the job executor. Given the job executor usually processes faster than a user can apply filters, state changes can impact query results. This filter is most applicable for true wait states (e.g., user tasks, external tasks, timers) rather than transaction boundaries.

• Compensation Scenarios: It is no longer possible to retrieve process instances with the activityIdIn filter on the subprocess “activity”. When using activityIdIn filter for compensation scenarios, users need to filter by specific flow nodes rather than the broader subprocess activities.

• Incident Deletion: When an incident is deleted, the incident filters will still return the process instances that previously had an incident. This behavior aligns with the standalone batch operation page and ensures consistency across the application.