Update from 7.3 to 7.4
This document guides you through the update from Camunda BPM
7.4.0. It covers these use cases:
- For administrators and developers: Database Updates
- For administrators and developers: Full Distribution Update
- For administrators and developers: Application with Embedded Process Engine Update
This guide covers mandatory migration steps as well as optional considerations for initial configuration of new functionality included in Camunda BPM 7.4.
Noteworthy new Features and Changes in 7.4:
- DMN 1.1: Decision Model And Notation is a standard for defining and executing business rules in the form of decisions and integrates with BPMN and CMMN. Camunda BPM 7.4 implements this standard for decision tables and therefore introduces new artifacts and extends the database schema during upgrade. If you do not plan to use DMN, the DMN-related tables will stay empty.
- CMMN 1.1: In addition to the already implemented version 1.0, the new version 1.1 of Case Management Model And Notation (CMMN) is supported with Camunda BPM 7.4. The execution of CMMN 1.0 models is still supported by Camunda BPM.
- Logging: Camunda 7.4 uses SLF4J as a logging API instead of JDK logging as before. This introduces the SLF4J API as a core dependency for the process engine. Please refer to the application server-specific sub-chapters of this document for implications on updating a full distribution installation. Also see the User Guide for information on how to set up logging.
- Changed URL of BPMN Extensions Namespace: With 7.4 the namespace URL for BPMN extensions is changed. See last section on this page for details.
No Rolling Upgrades
It is not possible to migrate process engines from Camunda 7.3 to 7.4 in a rolling fashion. This means, it is not possible to run process engines of version 7.3 and 7.4 in parallel with the same database configuration. The reason is that a 7.3 engine may not be able to execute process instances that have been previously executed by a 7.4 engine, as these may use features that were not available yet in 7.3.
Every Camunda installation requires a database schema upgrade.
Check for available database patch scripts for your database that are within the bounds of your upgrade path. Locate the scripts at
$DISTRIBUTION_PATH/sql/upgradein the pre-packaged distribution (where
$DISTRIBUTION_PATHis the path of an unpacked distribution) or in the Camunda Nexus. We highly recommend to execute these patches before upgrading. Execute them in ascending order by version number. The naming pattern is
Execute the corresponding upgrade scripts named
The scripts update the database from one minor version to the next one and change the underlying database structure, so make sure to backup your database in case there are any failures during the upgrade process.
We highly recommend to also check for any existing patch scripts for your database that are within the bounds of the new minor version you are upgrading to. Execute them in ascending order by version number. Attention: This step is only relevant when you are using an enterprise version of the Camunda BPM platform, e.g.,
X > 0. The procedure is the same as in step 1, only for the new minor version.
If you previously migrated from 7.2 to 7.3 you may have already executed the patch script
This script is the same as patch
$DATABASE_engine_7.3_patch_7.3.2_to_7.3.3_2.sql which need not be executed then.
This section is applicable if you installed the Full Distribution with a shared process engine.
The following steps are required:
- Upgrade Camunda Libraries and Applications inside the application server
- Migrate custom Process Applications
Before starting, make sure that you have downloaded the Camunda BPM 7.4 distribution for the application server you use. It contains the SQL scripts and libraries required for upgrade. 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.
Application with Embedded Process Engine
This section is applicable if you have a custom application with an embedded process engine.
Upgrade the dependencies declared in your application’s
pom.xml file to the new version. Which dependencies you have is application-specific. Typically, the dependencies consist of any of the following:
There are no new mandatory dependencies but some artifacts have new transitive dependencies. For example
camunda-engine depends on
camunda-engine-dmn. In order to pull these new dependencies into your application artifact, upgrading the version in your build tool and rebuilding the application is recommended.
This section describes changes in the engine’s default behavior. While the changes are reasonable, your implementation may rely on the previous default behavior. Thus, the previous behavior can be restored by explicitly setting a configuration option. Accordingly, this section applies to any embedded process engine but is not required for a successful upgrade.
As of 7.4 the process engine uses SLF4J for logging. The SLF4J API is pulled in transitively by the process engine maven module. However, in order for any actual logging to occur, you need to add an slf4j compatible logging backend. Please refer to the user guide for Information on how to setup logging.
Task Query Expressions
As of 7.4, the default handling of expressions submitted as parameters of task queries has changed. Passing EL expressions in a task query enables execution of arbitrary code when the query is evaluated. The process engine no longer evaluates these expressions by default and throws an exception instead. This behavior can be toggled in the process engine configuration using the properties
true). To restore the engine’s previous behavior, set both flags to
true. See the user guide on security considerations for custom code for details.
This is already the default for Camunda BPM versions after and including 7.3.3 and 7.2.8.
User Operation Log
The behavior of the user operation log has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property
true). To restore the engine’s prior behavior, i.e., to write log entries regardless of user context, set the flag to
Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API
TaskService#getTaskEvents. If you rely on this API method, the previous behavior can be restored by setting the flag
CMMN Model API
As a consequence of supporting CMMN 1.1, the CMMN model API is now based on the schema of CMMN 1.1. This leads to limitations when editing CMMN 1.0 models. We therefore recommend to migrate your CMMN 1.0 models to CMMN 1.1.
Changed URL of BPMN Extensions Namespace
With Camunda 7.4 the default namespace URL of BPMN extensions is changed from
http://activiti.org/bpmn (referred to as legacy namespace)
This section explains the implications of this change for the different components of Camunda.
Implications by Component
There is a new version of the eclipse plugin available (3.0.0) which supports the new namespace. It does not fully support the legacy namespace anymore.
If you use a 3.0.0+ version of the plugin,
- all newly created bpmn processes use the new namespace url.
- If you open an existing model which uses the legacy namespace, a warning dialog is shown asking you to update the namespace URL. If you click “yes”, the plugin automatically migrates the legacy namespace to the new URL.
If you do not upgrade the Eclipse plugin, the old version of the plugin continues to work with the legacy namespace. Since the process engine maintains backwards compatibility with the legacy namespace, this is fine. It is only a problem if you want to roundtrip models with the new Camunda Modeler.
The process engine maintains backwards compatibility with the legacy namespace. This means that if a BPMN process using the legacy namespace is deployed, the process engine is able to parse and execute it.
BPMN Model API
The BPMN model API maintains backwards compatibility with the legacy namespace for reading usecases. This means that if the model API is used for reading properties from the model, both namespaces can be used interchangeably without problems.
When creating new models with the model API, the new namespace is used.
Editing existing models using the legacy namespace with the model API and then adding new extensions is not supported. You need to update the namespace to the new namespace manually.
Camunda Modeler (New)
The new Camunda Modeler is based on bpmn.io. It is a desktop application editing files stored on the local file system.
The Camunda Modeler exclusively works with the new namespace. If you open an existing model which uses the legacy namespace, a warning dialog is shown asking you to update the namespace URL. If you click “yes”, the modeler automatically migrates the legacy namespace to the new URL. If you click “No”, the modeler does not migrate the namespace and you will not be able to edit the existing extension elements in the model.