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

1. For administrators and developers: Database updates
2. For administrators and developers: Full distribution update
3. For developers: Add Default History Time To Live to BPMN Fluent API
4. For administrators: Spring Boot Starter and Run logs admin user information on DEBUG level
5. For administrators and developers: External Task Client Java
6. For developers: Changed trigger order of built-in task listeners
7. For administrators and developers: Cockpit’s process definition like search changed to case-insensitive
8. For developers: External MDC properties are isolated from the engine’s processing
9. For developers: FEEL Engine 1.17.x Upgrade

This guide covers mandatory migration steps and optional considerations for the initial configuration of new functionality included in Camunda 7.21.

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.21 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.

Add Default History Time To Live to BPMN Fluent API

Starting with this release, the BPMN Fluent API Builder assigns by default a history time to live of 6 months to processes. You can change this default or pass null to remove the attribute using the #setCamundaHistoryTimeToLive or #setCamundaHistoryTimeToLiveString API.

Spring Boot Starter and Run logs admin user information on DEBUG level

In previous releases, when configuring Camunda’s admin user in the Spring Boot Starter or Run via camunda.bpm.admin-user, information about the admin user appeared in the logs on log level INFO on startup. With this release, the log level for the logs STARTER-SB010 and STARTER-SB011 was changed to DEBUG.

External Task Client Java

Update the client’s Apache HttpClient to version 5

We have updated the internal Apache HttpClient in our Java External Task Client from version 4.5.x to the more recent version 5.3.

Version 5 is the latest major version of HttpClient, and it offers many new features including the support for the latest HTTP/2 standards. Additionally, it also provides synchronous, asynchronous and reactive APIs, as well. For a complete list about features, see the official page about HttpCore 5.2 and HttpClient 5.3.

The classic API of the HttpClient 5 shares many similarities with the predecessor version 4, but it’s not backward compatible. This means an update to this version requires code and configuration adjustments.

Apache has an official migration guide, which should make the switch easier.

Update the client’s dependencies

The External Task Client Java has been migrated to the Jakarta namespace. In case you use the default data format providers (e.g.: DomXmlDataFormatProvider), you need to update the version of com.sun.xml.bind:jaxb-impl dependency to a version >= 4.0.x.

Complete example of the External Task Client Java can be found here.

Changed trigger order of built-in task listeners

Built-in task listeners are used internally by the engine and not intended to be used by the user. User-defined task listeners are handled separately. Before this release, the order in which builtin task listeners were executed could depend on how the task was executed. This bug report describes a scenario where after a process instance modification, the order of the builtin task listeners was reversed. With this release for both, regular process execution and process instance modification, the engine ensures the following:

1. Built-in task listeners are executed before user-defined task listeners.
2. Built-in task listeners are executed in the order in which they were registered.
3. User-defined task listeners are executed in the order in which they were registered.

Previously, only 1. and 3. were ensured.

Cockpit’s process definition like search changed to case-insensitive

The Cockpit/Processes’s page Process Definition search component allows for name and key search with equals and like operators. With this recent change, per customer feedback, we modified the like search to case-insensitive. This will allow a better experience when looking for process definitions.

The change also affects the API that provides the data for the search component. This API is an internal API, which means it’s not part of the public REST API, so the change should not affect any customers.

External MDC properties are isolated from engine processing

The previous behavior of clearing the MDC tuples associated with Logging Context Parameters has been changed in this release. Starting from 7.21, the new behavior preserves any logging context parameter entries found in the MDC to better isolate the engine processing from any external MDC user configuration.

Use cases that require the legacy behaviour (clearing of the MDC logging context parameter tuples after the engine processing) can opt for clearing the MDC programmatically.

FEEL Engine 1.17 Upgrade

The 7.21 release now supports FEEL Engine 1.17.x. This upgrade introduces breaking changes such as:

• The invocation of a non-existing function returns null (#692)
• Comparing different datatypes is now handled gracefully and can return false or null instead of throwing exception (#582)

For a detailed view of the change logs, check out the FEEL Engine 1.17.0 Release notes.