This document guides you through the update from Camunda BPM 7.9.x to 7.10.0. It covers these use cases:

1. For administrators and developers: Database Updates
2. For administrators and developers: Full Distribution Update
3. For administrators: Standalone Web Application
4. For developers: Spring Boot Starter Update
5. For developers: External Task Client Update
6. For administrators: CSRF Prevention in the Webapps
7. For administrators: Whitelist Pattern for User, Group and Tenant IDs
8. For administrators and developers: Support for JDK 9 / 10 / 11
9. For administrators: History Related Changes
10. For developers: Changed Webjar Structure
11. For administrators and developers: Changed Permissions for Starting Process In Tasklist
12. 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 BPM 7.10.

Noteworthy new Features and Changes in 7.10:

• Startable in Tasklist
• Set Business Key from Delegation Code
• Extending the BPMN Viewer in Cockpit

Database Updates

Every Camunda installation requires a database schema update.

Procedure

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

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

3. 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 BPM platform, e.g., 7.10.X where X > 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:

1. Update the Camunda libraries and applications inside the application server
2. Migrate custom process applications

Before starting, make sure that you have downloaded the Camunda BPM 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 BPM 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:

• Apache Tomcat
• JBoss AS/Wildfly
• IBM WebSphere
• Oracle WebLogic

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:

1. Undeploy the current version of the standalone web application
2. Update the database to the new schema as described in the database update section
3. Reconfigure the database as described in the installation section
4. 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:

1. Check Version Compatibility Matrix
2. Update Spring Boot Starter and, when required, Spring Boot versions in your pom.xml.
3. Update the Camunda BPM 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:

1. Check out the Version Compatibility Matrix
2. Update the version in your pom.xml (Java) or package.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 BPM Webapps.

Please also see the documentation about CSRF Prevention.

Whitelist Pattern for User, Group and Tenant IDs

With Camunda BPM 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 BPM 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.

History Related Changes

Skipped Optimistic Locking Exceptions

Starting with 7.10, by default the occurrence of OptimisticLockingExceptions 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 BPM 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.

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 and READ permissions at process definition level and
• CREATE 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.