Update from 7.10 to 7.11
This document guides you through the update from Camunda Platform 7.10.x
to 7.11.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: camunda-engine-spring Update
- For developers: External Task Client Update
- For developers: Changes Affecting Custom Permissions/Resources
- For administrators and developers: User Operation Log Permissions
- For developers: Custom WritableIdentityProvider
- For developers: Exception Handling in Processes
- For developers: Updated Front End Libraries
- For developers: HTTP Header Security in Webapps
This guide covers mandatory migration steps as well as optional considerations for initial configuration of new functionality included in Camunda Platform 7.11.
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.10_patch_?.sql
.Execute the corresponding update scripts named
$DATABASENAME_engine_7.10_to_7.11.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.11.X
whereX > 0
. The procedure is the same as in step 1, only for the new minor version.
MySQL/MariaDB Specifics
MySQL and MariaDB represent the TIMESTAMP
data type with a signed 32-bit integer. This limits the maximum date that can be stored to 03:14:07 on 19 January 2038 (UTC)
(also referred to as the Y2K38 problem).
For this reason, all the TIMESTAMP
columns that the Camunda engine uses to store future dates were migrated to the DATETIME
data type with a much larger time range.
Be aware that DATETIME
does not store time zone information. This means that, when applying the [MySQL|MariaDB]_engine_7.10_to_7.11.sql
script, the database server time zone will be used to convert the TIMESTAMP
into DATETIME
values. Any future time zone changes on the database server will offset the time stored in these columns causing an incorrect operation of the engine.
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.11 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
.
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. If your process application uses the camunda-engine-spring
module, please make sure to read the update section on camunda-engine-spring.
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 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)
camunda-engine-spring Update
The module camunda-engine-spring
has changed dependency scopes of the Spring framework from compile
to provided
.
If your application has a dependency on camunda-engine-spring
, you must additionally declare explicit dependencies to at least the
following Spring artifacts:
<properties>
<spring.version>YOUR SPRING VERSION</spring.version>
</properties>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>${spring.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-jdbc</artifactId>
<version>${spring.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-tx</artifactId>
<version>${spring.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-orm</artifactId>
<version>${spring.version}</version>
</dependency>
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)
Changes Affecting Custom Permissions/Resources
This section concerns you in case the authorization checks are enabled and you use custom permissions or resources.
An Authorization assigns a set of Permissions to an identity to interact with a given Resource. The build-in Permissions define the way an identity is allowed to interact with a certain resource. The build-in Resources are the entities the user interacts with.
A custom Permission is a custom implementation of the Permission interface. A custom Resource is a custom implementation of the Resource interface. In case you have at least one of these custom implementations please have a look at the table below what will be the impact for you:
Scenario | Impact |
---|---|
Built-in Permissions Built-in Resources |
None |
Custom Permissions Built-in Resources |
Permission#getResources() method. It must return all resources to which the permission applies.
|
Built-in Permissions Custom Resources |
Create a dedicated Permission Enum that copies the permissions that you use and implement the Permission#getResources() method such that it returns the custom resource. |
Custom Permissions Custom Resources |
Implement the new Permission#getResources() method. It must return all resources to which the permission applies.
|
Built-in permissions are used for built-in resources in combinations other than than those defined by Camunda |
Permission Enum that copies the permissions that you use and implement the Permission#getResources() method such that it returns the resource you use them with.
|
How to avoid a permission clash
- Check if any of your custom permissions is in conflict with one of the built-in permissions: Check the permission enums in the org.camunda.bpm.engine.authorization package. Determine if there is any permission that applies to the same resource and has the same value as one of your custom permissions.
- Deactivate this built-in permission via a process engine configuration property. Note that in this case Camunda no longer enforces the disabled permissions.
User Operation Log Permissions
The authorization for user operation log entries has been adjusted. Entries that are created with Camunda 7.11 and higher and that are not related to process definition keys (e.g. case instances, batches, standalone tasks and standalone jobs) can no longer be read and deleted without proper authorization.
Instead, permissions READ
and DELETE
can be granted on the new resource UserOperationLogCategory
with resource id set to a specific operation log category or *
for all.
In order to read (or delete) entries that are related to process definitions, a user either needs
- permission
READ
(orDELETE
) on resourceUserOperationLogCategory
with the resource id set to the respective category of the entry or*
- permission
READ_HISTORY
(orDELETE_HISTORY
) on resourceProcessDefinition
with the resource id set to the respective process definition key of the entry or*
In order to read (or delete) entries that are not related to process definitions, a user needs
- permission
READ
(orDELETE
) on resourceUserOperationLogCategory
with the resource id set to the respective category of the entry or*
An overview of the operation logs and their categories can be found at User Operation Log. Authorization management is detailed in Authorization Service.
Custom WritableIdentityProvider
Custom implementations of the WritableIdentityProvider
interface need to be adjusted to return the new type IdentityOperationResult
for all CUD (Create, Update, Delete) operations.
This includes all interface methods except createNewUser(String)
, createNewGroup(String)
and createNewTenant(String)
.
In order to return an instance of this type, you can easily change a current implementation from
public void unlockUser(String userId) {
UserEntity user = findUserById(userId);
if (user != null && (user.getAttempts() > 0 || user.getLockExpirationTime() != null)) {
getIdentityInfoManager().updateUserLock(user, 0, null);
}
}
to
public IdentityOperationResult unlockUser(String userId) {
UserEntity user = findUserById(userId);
if (user != null && (user.getAttempts() > 0 || user.getLockExpirationTime() != null)) {
getIdentityInfoManager().updateUserLock(user, 0, null);
return new IdentityOperationResult(user, IdentityOperationResult.OPERATION_UNLOCK);
}
return new IdentityOperationResult(null, IdentityOperationResult.OPERATION_NONE);
}
You can also inspect the DbIdentityServiceProvider to see how the new return type is handled in the default implementation.
Exception Handling in Processes
As of 7.11.0, exceptions thrown from execution and task listeners can trigger BPMN error events (for more information, please check the User Guide). Accordingly, the semantics of existing processes may change if there is an error event that catches the exception.
Updated Front End Libraries
With this release, we updated all front end libraries. Changes introduced with newer package versions might impacting:
Please find below a complete table of the updated front end libraries.
If you make use of these packages in your Embedded Task Forms as well as your Custom Scripts, please make sure that your customizations still work as expected with the new versions used in Camunda Platform 7.11.
Package | 7.10 | 7.11 | Further Reading |
---|---|---|---|
angular-moment | 0.9.0 | 1.3.0 | Release Notes |
angular-ui-bootstrap | 0.11.2 | 2.5.0 | Change Log |
angularjs | 1.2.29 | 1.7.8 | Migration Guide |
bootstrap | 3.3.6 | 3.4.1 | Release Notes |
bpmn-font | 0.2.0 | 0.8.0 | |
bpmn-js | 3.0.1 | 3.2.1 | Change Log |
clipboard | 1.5.10 | 2.0.4 | Release Notes |
cmmn-js | 0.15.2 | 0.17.1 | Change Log |
dmn-js | 5.2.0 | 6.3.2 | Change Log |
events | 1.1.0 | 3.0.0 | Release Notes |
fast-xml-parser | 2.7.3 | 3.12.14 | Change Log |
jquery | 2.1.1 | 3.3.1 | Upgrade Guide |
jquery-ui | 1.10.5 | 1.12.1 | Upgrade Guide 1.11, Upgrade Guide 1.12 |
lodash | 2.4.1 | 4.17.11 | Changelog |
moment | 2.9.0 | 2.24.0 | Changelog |
mousetrap | 1.5.3 | 1.6.3 | Release Notes |
q | 1.4.1 | 1.5.1 | Changelog |
requirejs | 2.1.22 | 2.3.6 | Release Notes |
superagent | 1.4.0 | 4.1.0 | Release Notes |
Noteworthy Changes
- Please pay especially attention to
angularjs
as it introduces a huge amount of changes - The directive names of
angular-ui-bootstrap
are now prefixed (i. e.uib-*
) - In form names, special characters are not allowed anymore
HTTP Header Security in Webapps
Starting with this release, a HTTP Header Security Servlet Filter is introduced for the Webapps. With Camunda Platform 7.11.0 we have added the XSS Protection Header to all server responses in conjunction with the Webapps.
XSS Protection in Webapps
By default, the XSS Protection HTTP Header is configured in a way that a page gets blocked as soon as the browser detects a cross-site scripting attack. You can either loosen this behavior or even disable the XSS Protection Header. Learn more about how to configure the HTTP Header Security Filter.
For further reading on how the XSS protection header works in detail, please see Mozillas MDN Web Docs.