Update from 7.9 to 7.10
This document guides you through the update from Camunda Platform 7.9.x
to 7.10.0
. It covers these use cases:
- For administrators and developers: Database Updates
- For administrators and developers: Full Distribution Update
- For administrators: Standalone Web Application
- For developers: Spring Boot Starter Update
- For developers: External Task Client Update
- For administrators: CSRF Prevention in the Webapps
- For administrators: Whitelist Pattern for User, Group and Tenant IDs
- For administrators and developers: Support for JDK 9 / 10 / 11
- For administrators: History Related Changes
- For developers: Changed Webjar Structure
- For administrators and developers: Changed Permissions for Starting Process In Tasklist
- For developers: Spin and JAXB
This guide covers mandatory migration steps as well as optional considerations for initial configuration of new functionality included in Camunda Platform 7.10.
Noteworthy new Features and Changes in 7.10:
Database Updates
Every Camunda installation requires a database schema update.
Procedure
Check for available database patch scripts for your database that are within the bounds of your update path. Locate the scripts at
$DISTRIBUTION_PATH/sql/upgrade
in the pre-packaged distribution (where$DISTRIBUTION_PATH
is the path of an unpacked distribution) or in the Camunda Nexus. We highly recommend to execute these patches before updating. Execute them in ascending order by version number. The naming pattern is$DATABASENAME_engine_7.9_patch_?.sql
.Execute the corresponding update scripts named
$DATABASENAME_engine_7.9_to_7.10.sql
The scripts update the database from one minor version to the next, and change the underlying database structure. So make sure to backup your database in case there are any failures during the update 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 updating 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 Platform, e.g.,
7.10.X
whereX > 0
. The procedure is the same as in step 1, only for the new minor version.
DB2 Specifics
Due to problems with DB2 databases the ACT_IDX_JOB_HANDLER
index has been removed. When applying the upgrade scripts
it might happen, that an error message occurs which points out, that the removed index is missing. If you should face this
error message, please ignore it and continue with the upgrade procedure.
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, make sure that you have downloaded the Camunda Platform 7.10 distribution for the application server you use. It contains the SQL scripts and libraries required for update. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH
.
Wildfly distribution
Starting from Camunda Platform 7.10, only a single WildFly distribution, packaged with the latest version of the WildFly application server will be provided. For WildFly 10+, the update process remains the same.
For WildFly 8 users, separate camunda-wildfly8-modules
and camunda-wildfly8-subsystem
archives have been provided.
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:
camunda-engine-spring
camunda-engine-cdi
camunda-ejb-client
- …
There are no new mandatory dependencies for process applications.
Standalone Web Application
If the standalone web application is in use, the current war
artifact must be replaced by its new version.
If a database other than the default H2 database is used, the following steps must be taken:
- Undeploy the current version of the standalone web application
- Update the database to the new schema as described in the database update section
- Reconfigure the database as described in the installation section
- Deploy the new and configured standalone web application to the server
Spring Boot Starter Update
If you are using Camunda Spring Boot Starter within you Spring Boot application, then you would need to:
- Check Version Compatibility Matrix
- Update Spring Boot Starter and, when required, Spring Boot versions in your
pom.xml
. - Update the Camunda Platform version in your
pom.xml
in case you override it before (e.g. when using the enterprise version or a patch releases)
External Task Client Update
If you are using the Camunda External Task Client, please make sure to:
- Check out the Version Compatibility Matrix
- Update the version in your
pom.xml
(Java) orpackage.json
(NodeJs)
CSRF Prevention in the Webapps
This release secures the Webapps with CSRF Prevention. If you want to make use of the newly introduced security enhancement,
please make sure to enable the CsrfPreventionFilter
when migrating to 7.10 by adjusting the web.xml
file of Camunda Platform Webapps.
Please also see the documentation about CSRF Prevention.
Whitelist Pattern for User, Group and Tenant IDs
With Camunda Platform 7.10 a whitelist pattern of User, Group and Tenant IDs has been introduced. By default, on creating or updating users, groups or tenants the ID is matched against the pattern “[a-zA-Z0-9]+|camunda-admin”. To disable or adjust the default pattern, please see the documentation under Identity Service in the User Guide.
Support for JDK 9 / 10 / 11
This release introduces support for JDK 9 / 10 / 11.
JRuby
The Camunda Platform supports scripting with JSR-223 compatible script engine implementations.
If the optional JRuby script engine implementation is used, the respective dependency needs to be updated to version 9.1.14.0 or higher to work properly in conjunction with the newly supported JDK versions.
Heads Up!
Please bear in mind, that the default language level of JRuby 9 is Ruby 2, whereas the default language level of the previous version (JRuby 1.7) is Ruby 1.9. Updating the JRuby version might break your scripts.
History Related Changes
Skipped Optimistic Locking Exceptions
Starting with 7.10, by default the occurrence of OptimisticLockingException
s
on UPDATE/DELETE operations for historic data is prevented. This allows to successfully complete process instances even
if the associated historic instances have been removed during execution.
There exist a process engine configuration flag to preserve the previous behavior.
Changed Default Cleanup Strategy
The default strategy of the History Cleanup feature has been changed. From now on, each historic instance related to processes, decisions or batches needs a removal time to be cleaned-up.
Historic instances which (1) have been produced by a Camunda Platform version prior to 7.10 and (2) belong to a top-level instance
which has been completed already cannot be cleaned-up after the migration took place. This is due to the reason, that a
removal time is missing for these historic instances. If you want to get rid of them anyway, please add a removal time
or switch the historyCleanupStrategy
to the endTimeBased
cleanup strategy via a
process engine configuration property.
Heads Up!
Starting with Camunda Platform 7.11 there exist several Batch Operations to set a removal time to historic processes, decisions and batches. This allows you to set a removal time via Camunda Cockpit as well as REST & Java API.
You can learn more about it in the User Guide.
To gain a better understanding of the new cleanup strategy, please see the updated documentation about the History Cleanup feature.
Custom History Level
If you have implemented a Custom History Level and you want to use it in conjunction with the removal time based cleanup strategy, please also see the documentation about Removal Time Inheritance.
Changed Webjar Structure
Structure of webjar
and webjar-ee
artifacts has changed related to adjustment of index.html path. The new structure is as follows:
/META-INF/resources
|--/plugin
| |--/admin
| |--/cockpit
| |--/tasklist
|--/webjars/camunda
|--/app
|--/lib
|--index.html
|--securityFilterRules.json
Changed Permissions for Starting Process In Tasklist
In order to start a process via Tasklist the user needs the following permissions:
CREATE_INSTANCE
andREAD
permissions at process definition level andCREATE
permission for all process instances.
Spin and JAXB
Since Java 9, the previously included module “JAXB” was marked as deprecated and with Java 11 the module was removed entirely from the JDK. To make sure that the camunda-spin-dataformat-all
artifact works seamlessly with Java 9 and versions above (i. e. without additional dependencies or configuration effort), from now on JAXB is directly included in the camunda-spin-dataformat-all
artifact.
Our recommendation is, instead of using the camunda-spin-dataformat-all
artifact, to use the camunda-spin-dataformat-xml-dom
artifact for the de/serialization of XML.
If you are using Java 9 or above, you additionally need a JAXB implementation. We recommend to use version 2.2.3
of com.sun.xml.bind:jaxb-impl
.