Update from 7.9 to 7.10
This document guides you through the update from Camunda BPM
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
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:
Every Camunda installation requires a database schema update.
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/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 updating. Execute them in ascending order by version number. The naming pattern is
Execute the corresponding update scripts named
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 BPM platform, e.g.,
X > 0. The procedure is the same as in step 1, only for the new minor version.
Within this release the
ACT_IDX_JOB_HANDLER index is removed because causes problems on db2 databases. It could happen during applying the upgrade scripts an error message to occur which states that the index does not exist. This is not a real problem and you can continue with the upgrade procedure.
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 BPM 7.9 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
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:
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
Support for CSRF Prevention in the Webapps
The Webapps are more secure now. As of version 7.10, a CSRF filter is enabled by default, validating each modifying request performed through the webapps. The filter implements a (per-session) Synchronization Token method for CSRF validation with an optional Same Origin with Standard Headers verification.
If you would like to enable the additional Same Origin with Standard Headers verification, the
targetOrigin init-parameter should be set in the
web.xml file of your application. That, and some additional optional initialization parameters are:
<!-- CSRF Prevention filter --> <filter> <filter-name>CsrfPreventionFilter</filter-name> <filter-class>org.camunda.bpm.webapp.impl.security.filter.CsrfPreventionFilter</filter-class> <init-param> <param-name>targetOrigin</param-name> <param-value>http://example.com</param-value> </init-param> <init-param> <param-name>denyStatus</param-name> <param-value>404</param-value> </init-param> <init-param> <param-name>randomClass</param-name> <param-value>java.security.SecureRandom</param-value> </init-param> <init-param> <param-name>entryPoints</param-name> <param-value>/api/engine/engine/default/history/task/count, /api/engine/engine/default/history/variable/count</param-value> </init-param> </filter> <filter-mapping> <filter-name>CsrfPreventionFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
|targetOrigin||Application expected deployment domain: the domain name through which the webapps are accessed. If nothing is set, the _Same Origin with Standard Headers_ verification is not performed.|
|denyStatus||HTTP response status code that is used when rejecting denied request. The default value is 403.|
|randomClass||The name of the class to use to generate tokens. The class must be an instance of `java.util.Random`. If not set, the default value of `java.security.SecureRandom` will be used.|
|entryPoints||Entry points are URLs that will not be tested for the presence of a valid token. They are used to provide a way to navigate back to the protected apps after navigating away from them.|
Custom Whitelist for User, Group and Tenant IDs
From version 7.10, User, Group and Tenant IDs can be matched against a Whitelist Pattern to determine if the provided ID is acceptable or not. The default (global) Regular Expression pattern to match against is “[a-zA-Z0-9]+|camunda-admin” i.e. any combination of alphanumeric values or ‘camunda-admin’.
If your organisation allows the usage of additional characters (ex.: special characters), the ProcessEngineConfiguartion propery
generalResourceWhitelistPattern should be set with the appropriate pattern in the engine’s configuration file. Standard Java Regular Expression syntax can be used. For example, to accept any character, the following property value can be used:
<property name="generalResourceWhitelistPattern" value=".+"/>
The definition of different patterns for User, Group and Tenant IDs is possible by using the appropriate configuration propery:
<property name="userResourceWhitelistPattern" value="[a-zA-Z0-9-]+" /> <property name="groupResourceWhitelistPattern" value="[a-zA-Z]+" /> <property name="tenantResourceWhitelistPattern" value=".+" />
Note that if a certain pattern isn’t defined (ex. the tenant whitelist pattern), the general pattern will be used, either the default one (
"[a-zA-Z0-9]+|camunda-admin") or one defined in the configuration file.
Hierarchical History Cleanup
Version 7.10 of the Camunda BPM platform introduces a hierarchical structure to the historic data. This allows for a clear way of determining which was the top-level (root) process instance that started a given process instance and provides a consistent view of the historic instances.
Furthermore, a new History Cleanup mechanism was added, which is aware of this hierarchical structure, and performs cleanup only when the top level instance has finished and its “history time to live” expired (more here). The new mechanism is enabled by default, but can be disabled through the
hierarchicalHistoryCleanup property (see the Configuration options).
Support for JDK 9 / 10 / 11
This release introduces support for JDK 9 / 10 / 11.
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 18.104.22.168 or higher to work properly in conjunction with the newly supported JDK versions.
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.
Starting with 7.10, the engine supports database partitioning for historical data.
Due to this reason,
OptimisticLockingExceptions on UPDATE/DELETE operations for historical data are prevented by default.
There exist a process engine configuration flag to preserve the previous behavior.