Patch Level Update
This guide explains how to perform a patch level update. The patch level is the version number “after the second dot”. Example: update from 7.3.2
to 7.3.3
.
Enterprise Feature
Please note that Patch Level Updates are only provided to enterprise customers, they are not available in the community edition.
Check the Camunda enterprise homepage for more information or get your free trial version.
Reading this Guide
In this guide, a number of variables are used to denote common path names and constants:
$DATABASE
: the target database platform, e.g. DB2, MySQL, etc.$DISTRIBUTION_PATH
: the path of the downloaded pre-packaged Camunda Platform distribution, e.g.camunda-bpm-tomcat-$PLATFORM_VERSION.zip
orcamunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz
for Tomcat etc.$PLATFORM_VERSION
: the version of the Camunda Platform you want to install, e.g.7.1.0
.
Database Patches
Between patch levels, the structure of the database schema is not changed. The database structure of all patch releases is backwards compatible to the corresponding minor version. Example: the database schema of all 7.3.x
versions is backwards compatible to the 7.3.0
schema.
The one exception to this are bugs in the database schema itself. If you are affected by such a bug, you have the option to run a patch script.
Patch scripts are shipped inside the distribution at the following location: $DISTRIBUTION_PATH/sql/upgrade
, named: engine_$VERSION_patch_$A_to_$B
.
If you do choose to apply a database patch, then you must apply all patch scripts that are within the bounds of your update path. This means if your current patch version is X.X.1
and you update to X.X.5
you have to execute all patch scripts first where $A
≥ X.X.1
and $B
≤ X.X.5
.
Note: Some patches are provided for multiple versions. It is not required to execute them more than once. See the description of the following list for information on duplicate fixes.
The description for each patch script also contains information on what the fixes are related to and a link to the corresponding Camunda Jira issue.
The following list is an overview of all currently available patch scripts:
Camunda Version | Patch file | Description | Affected databases | Issue link |
---|---|---|---|---|
7.1 | engine_7.1_patch_7.1.4_to_7.1.5.sql | Add a missing index on foreign key to prevent deadlocks | H2, MySQL, Oracle, PostgreSQL | CAM-2567 |
7.1 | engine_7.1_patch_7.1.9_to_7.1.10.sql | Add a missing index on foreign key to prevent deadlocks | DB2, SQL Server | CAM-3565 |
7.2 | engine_7.2_patch_7.2.4_to_7.2.5.sql | Add a missing index on foreign key to prevent deadlocks. This is the same patch as engine_7.1_patch_7.1.9_to_7.1.10.sql. | DB2, SQL Server | CAM-3565 |
7.2 | engine_7.2_patch_7.2.6_to_7.2.7.sql | Add indices to improve deployment performance. | All databases | CAM-4497 |
7.3 | engine_7.3_patch_7.3.0_to_7.3.1.sql | Adjust column size of ACT_HI_JOB_LOG.ACT_ID_ to 255. | All databases | CAM-4037 |
7.3 | engine_7.3_patch_7.3.2_to_7.3.3_1.sql | Add a missing index on ACT_RU_AUTHORIZATION#RESOURCE_ID_ to prevent deadlocks. | All databases | CAM-4440 |
7.3 | engine_7.3_patch_7.3.2_to_7.3.3_2.sql | Add indices to improve deployment performance. This is the same patch as engine_7.2_patch_7.2.6_to_7.2.7.sql. | All databases | CAM-4497 |
7.3 | engine_7.3_patch_7.3.5_to_7.3.6_1.sql | Adjust column size of ACT_RU_JOB.PROCESS_DEF_KEY_ to 255. | All databases | CAM-4328 |
7.3 | engine_7.3_patch_7.3.5_to_7.3.6_2.sql | Add indices to improve performance of group authorizations. | All databases | CAM-5364 |
7.4 | engine_7.4_patch_7.4.2_to_7.4.3_1.sql | Add index to improve historic activity instance statistics query performance. | All databases | CAM-5257 |
7.4 | engine_7.4_patch_7.4.2_to_7.4.3_2.sql | Add a missing index on ACT_RU_EXT_TASK#EXECUTION_ID_ to prevent deadlocks. | All databases | CAM-5440 |
7.4 | engine_7.4_patch_7.4.2_to_7.4.3_3.sql | Add indices to improve performance of group authorizations. This is the same patch as engine_7.3_patch_7.3.5_to_7.3.6_2.sql. | All databases | CAM-5364 |
7.4 | engine_7.4_patch_7.4.5_to_7.4.6.sql | Adjust column size of ACT_RU_JOB.PROCESS_DEF_KEY_ to 255. This is the same patch as engine_7.3_patch_7.3.5_to_7.3.6_1.sql. | All databases | CAM-4328 |
7.6 | engine_7.6_patch_7.6.0_to_7.6.1.sql | Adjust column size of ACT_RU_EVENT_SUBSCR.ACTIVITY_ID_ to 255. | All databases | CAM-6788 |
7.6 | engine_7.6_patch_7.6.2_to_7.6.3_1.sql | Add a missing index on ACT_RU_EXT_TASK#ERROR_DETAILS_ID_ to prevent deadlocks. | All databases | CAM-7263 |
7.6 | engine_7.6_patch_7.6.2_to_7.6.3_2.sql | Remove an incorrect index ACT_RU_JOB#ACT_IDX_JOB_HANDLER for MSSQL Server. | MSSQL Server | CAM-7442 |
7.7 | engine_7.7_patch_7.7.3_to_7.7.4.sql | Insert new startup.lock in ACT_GE_PROPERTY. | All databases | CAM-8162 |
7.7 | engine_7.7_patch_7.7.4_to_7.7.5_1.sql | Add indices to improve performance of history cleanup | All databases | CAM-8184 |
7.7 | engine_7.7_patch_7.7.4_to_7.7.5_2.sql | Increase the field length of ACT_RU_AUTHORIZATION.RESOURCE_ID_ | All databases | CAM-8177 |
7.7 | engine_7.7_patch_7.7.5_to_7.7.6.sql | Add indices to improve historic activity instance statistics | All databases | CAM-8485 |
7.7 | engine_7.7_patch_7.7.8_to_7.7.9_1.sql | Add indexes on Process Definition ID and End Time for Historic Process Instance and Historic Activity Instance | All databases | CAM-8833 | 7.7 | engine_7.7_patch_7.7.8_to_7.7.9_2.sql | Add a missing index on foreign key to prevent deadlocks. | DB2, SQL Server | CAM-9165 |
7.8 | engine_7.8_patch_7.8.0_to_7.8.1.sql | Add indices to improve historic activity instance statistics. This is the same patch as engine_7.7_patch_7.7.5_to_7.7.6.sql. | All databases | CAM-8485 |
7.8 | engine_7.8_patch_7.8.4_to_7.8.5.sql | Add indexes on Process Definition ID and End Time for Historic Process Instance and Historic Activity Instance. This is the same patch as engine_7.7_patch_7.7.8_to_7.7.9_1.sql. | All databases | CAM-8833 |
7.8 | engine_7.8_patch_7.8.7_to_7.8.8.sql | Add a missing index on foreign key to prevent deadlocks. This is the same patch as engine_7.7_patch_7.7.8_to_7.7.9_2.sql. | DB2, SQL Server | CAM-9165 |
7.8 | engine_7.8_patch_7.8.8_to_7.8.9.sql | Drop ACT_IDX_JOB_HANDLER index causing issues on DB2. | DB2 | CAM-7676 |
7.8 | engine_7.8_patch_7.8.11_to_7.8.12.sql | Add index to improve history cleanup performance. | All databases | CAM-9435 |
7.8 | engine_7.8_patch_7.8.12_to_7.8.13_1.sql | Add support for Optimize 2.3. | All databases | CAM-9523 |
7.8 | engine_7.8_patch_7.8.12_to_7.8.13_2.sql | Add support for Optimize 2.3. | All databases | CAM-9525 |
7.9 | engine_7.9_patch_7.9.0_to_7.9.1.sql | Add index to improve historic operation logs performance. | All databases | CAM-9006 |
7.9 | engine_7.9_patch_7.9.1_to_7.9.2.sql | Add a missing index on foreign key to prevent deadlocks. This is the same patch as engine_7.8_patch_7.8.7_to_7.8.8.sql. | DB2, SQL Server | CAM-9165 |
7.9 | engine_7.9_patch_7.9.2_to_7.9.3.sql | Drop ACT_IDX_JOB_HANDLER index causing issues on DB2. This is the same patch as engine_7.8_patch_7.8.8_to_7.8.9.sql. | DB2 | CAM-7676 |
7.9 | engine_7.9_patch_7.9.5_to_7.9.6.sql | Add index to improve history cleanup performance. This is the same patch as engine_7.8_patch_7.8.11_to_7.8.12.sql. | All databases | CAM-9435 |
7.9 | engine_7.9_patch_7.9.6_to_7.9.7_1.sql | Add support for Optimize 2.3. This is the same patch as engine_7.8_patch_7.8.12_to_7.8.13_1.sql. | All databases | CAM-9523 |
7.9 | engine_7.9_patch_7.9.6_to_7.9.7_2.sql | Add support for Optimize 2.3. This is the same patch as engine_7.8_patch_7.8.12_to_7.8.13_2.sql. | All databases | CAM-9525 |
7.9 | engine_7.9_patch_7.9.11_to_7.9.12.sql | Add support for Optimize 2.5. | All databases | CAM-10264 |
7.10 | engine_7.10_patch_7.10.5_to_7.10.6.sql | Add support for Optimize 2.5. This is the same patch as engine_7.9_patch_7.9.11_to_7.9.12.sql. | All databases | CAM-10264 |
7.10 | engine_7.10_patch_7.10.6_to_7.10.7.sql | Add index to improve history cleanup performance.
This patch script is introduced in 7.10.9. If your current patch is 7.10.6, 7.10.7 or 7.10.8, please execute the script to upgrade to 7.10.9+. |
All databases | CAM-10616 |
7.10 | engine_7.10_patch_7.10.13_to_7.10.14.sql | Add index to improve Historic Activity Instance query performance. | All databases | CAM-11117 |
7.11 | engine_7.11_patch_7.11.2_to_7.11.3.sql | Add index to improve history cleanup performance. This is the same patch as engine_7.10_patch_7.10.6_to_7.10.7.sql. | All databases | CAM-10616 |
7.11 | engine_7.11_patch_7.11.7_to_7.11.8.sql | Add index to improve Historic Activity Instance query performance. This is the same patch as engine_7.10_patch_7.10.13_to_7.10.14.sql. | All databases | CAM-11117 |
7.11 | engine_7.11_patch_7.11.18_to_7.11.19.sql | Introducing new engine lock properties | All databases | CAM-12590 |
7.12 | engine_7.12_patch_7.12.0_to_7.12.1.sql | Add index to improve Historic Activity Instance query performance. This is the same patch as engine_7.11_patch_7.11.7_to_7.11.8.sql. | All databases | CAM-11117 |
7.12 | engine_7.12_patch_7.12.10_to_7.12.11.sql | Add support for Optimize 3.2. | All databases | CAM-12383 |
7.12 | engine_7.12_patch_7.12.11_to_7.12.12.sql | Introducing new engine lock properties This is the same patch as engine_7.11_patch_7.11.18_to_7.11.19.sql. | All databases | CAM-12590 |
7.13 | engine_7.13_patch_7.13.4_to_7.13.5_1.sql | Add index to improve Task query performance. | All databases | CAM-4441 |
7.13 | engine_7.13_patch_7.13.4_to_7.13.5_2.sql | Add support for Optimize 3.2. This is the same patch as engine_7.12_patch_7.12.10_to_7.12.11.sql. | All databases | CAM-12383 |
7.13 | engine_7.13_patch_7.13.5_to_7.13.6.sql | Introducing new engine lock properties This is the same patch as engine_7.12_patch_7.12.11_to_7.12.12.sql. | All databases | CAM-12590 |
Special Considerations
This section describes noteworthy changes between individual patch levels.
7.3.2 to 7.3.3
By default it is not possible anymore to pass arbitrary expressions as parameters of task queries.
Reason: 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. The pevious behavior can be re-enabled by setting the process configuration enableExpressionsInAdhocQueries
to true.
See the user guide on security considerations for custom code for details.
7.6.10 to 7.6.11 / 7.7.5 to 7.7.6 / 7.8.0 to 7.8.1
Java serialization format
You can now configure, if you forbid the usage of Java serialization format, when passing object variables in their Java serialized representation.
The new configuration parameter javaSerializationFormatEnabled
defaults to true
, but can be configured to false
in Camunda engine configuration.
Following use cases are affected:
- REST API:
PUT /process-instance/{id}/variables/{varName}
{
"value" : "ab",
"type" : "Object",
"valueInfo" : {
"objectTypeName": "com.example.MyObject",
"serializationDataFormat": "application/x-java-serialized-object"
}
}
- Java API:
runtimeService.setVariable(processInstanceId, "varName",
Variables
.serializedObjectValue("ab")
.serializationDataFormat("application/x-java-serialized-object")
.objectTypeName("com.example.MyObject")
.create());
You can disable Java serialization usage with the help of this configuration parameter:
<property name="javaSerializationFormatEnabled">false</property>
Groovy version
The pre-built Camunda distributions of versions 7.6.10, 7.7.5 and 7.8.0 ship with Groovy library of version 2.4.5, whereas newer versions come with Groovy 2.4.13.
Please update the library groovy-all-$GROOVY_VERSION.jar
in the lib
folder of your application server.
7.8.1. to 7.8.2
Restrict heatmap/statistics by time period
In the historic process definition diagram it is possible to select time periods for which activity instance badges are displayed.
By default the displayed timer period is set to ‘today’ but can be extended to show badges of ‘this week’, ‘this month’ or the ‘complete’ history.
This feature can be configured in two ways:
- The default timer period can be changed to ‘this week’, ‘this month’ or ‘complete’
- The manual selection of the time period within cockpit can be disabled.
These attributes can be modified in the configuration file
7.8.6 to 7.8.7
History cleanup can be parallelized
As of v. 7.8.7, history cleanup can be parallelized, which leads to creation of several jobs in the database. For this reason:
- call to
HistoryService#cleanupHistoryAsync
does not guarantee to return correct Job object in return and you should not rely on the returned value any more. The same valid for REST callPOST /history/cleanup
HistoryService#findHistoryCleanupJob
is deprecated (as well asGET /history/cleanup/job
), one should useHistoryService#findHistoryCleanupJobs
instead.
7.10.16 to 7.10.17 / 7.11.10 to 7.11.11 / 7.12.3 to 7.12.4
DMN 1.3 Support in Cockpit
With this release, cockpit adds support for DMN 1.3, the next version of the DMN standard. If you edit and deploy DMN diagrams in Cockpit, which use earlier versions of DMN, they will automatically be migrated to DMN 1.3.
The Camunda engine already supports the DMN 1.3 namespace by default, so there are no more steps required to migrate. Make sure you have the latest version of Camunda Modeler installed to edit DMN 1.3 files locally.
7.12.5 to 7.12.6
Oracle JDBC Driver Removed from Camunda Docker Images
The Docker images for Camunda 7.13 no longer provide an Oracle JDBC driver out of the box. If you relied on this, apply the strategy outlined in https://github.com/camunda/docker-camunda-bpm-platform#database-environment-variables: Add the driver to the container and configure the database settings manually by linking the configuration file into the container.
7.13.6 to 7.13.7 / 7.12.11 to 7.12.12 / 7.11.18 to 7.11.19
[Legal Note] Telemetry
In the mentioned patches above, a telemetry functionality is introduced. For more information please visit the telemetry page. Before you upgrade to a Camunda Platform Runtime version >= 7.14.0-alpha1, 7.13.7+, 7.12.12+, and 7.11.19+, or activate the telemetry functionality, please make sure that you are authorized to take this step, and that the installation or activation of the telemetry functionality is not in conflict with any company-internal policies, compliance guidelines, any contractual or other provisions or obligations of your company.
Camunda cannot be held responsible in the event of unauthorized installation or activation of this function.
Custom REST API
In case you are deploying a custom REST API that builds upon the one provided by Camunda, please make sure to add the following listener to the web.xml
:
<web-app ...>
...
<listener>
<listener-class>org.camunda.bpm.engine.rest.impl.web.bootstrap.RestContainerBootstrap</listener-class>
</listener>
...
</web-app>
This servlet context listener is used for bootstrapping the REST API and should therefore be included in your custom application setup.
7.13.6 to 7.13.7
FEEL Engine: Changed Module Structure
With the above-mentioned patch release, the module structure has changed in conjunction with the FEEL Engine.
From now on, the FEEL Engine will be delivered as a dedicated module feel-engine
. It is no longer part of
the camunda-engine-feel-scala
module. The FEEL Engine module follows its own versioning.
The following modules are dependent on the newly introduced feel-engine
module:
camunda-engine-plugin-spin
camunda-engine-feel-scala
7.13.9 to 7.13.10 / 7.12.15 to 7.12.16
Update of MySQL JDBC Driver in Camunda Docker Images
With this release, the docker images contain a new version of the MySQL JDBC Driver.
Old Version: 5.1.21
New Version: 8.0.23
Behavior Changes
The driver’s new version has two significant behavioral changes you should take care of when migrating your Docker-based Camunda Runtime installation.
Downgrade to 5.1.21
You don’t want to migrate to the new version? You can replace the new MySQL JDBC Driver with the old one
to restore the previous behavior. To do so, you can create a new Dockerfile
based on one of our official
docker images and add your custom commands to replace the MySQL JDBC Driver.
For the Wildfly image, additionally make sure to adjust the data source class in the standalone.xml
file located under /camunda/standalone/configuration/
from com.mysql.cj.jdbc.MysqlXADataSource
back to
com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
:
<!-- ... -->
<driver name="mysql" module="mysql.mysql-connector-java">
<xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
</driver>
<!-- ... -->
1) Milliseconds Precision for Date/Time values
The new version of the Driver changes how a date/time value is handled. Please make sure to configure the Driver as described in MySQL Database Configuration to avoid breaking behavior.
2) Changed Time Zone Handling
In case the process engine and the MySQL Server operate in different time zones, and you use the MySQL JDBC Driver’s default configuration, migrating to the new release leads to a wrong conversion of date values (e.g., the due date of a task can change).
You can configure the driver to convert date values from and to the MySQL Server into the time zone
in which the process engine/JVM operates. This ensures that values that were stored before the migration
are returned correctly after the migration and date values are stored correctly after the migration.
You can achieve this by specifying the correct time zone via the property serverTimeZone
in your JDBC connection URL.
For instance, if your process engine operates in CET but your MySQL Server does not, set the property to serverTimeZone=CET
.
Heads-up!
Changing the time zone of the MySQL Server to the one the process engine operates in can have unwanted side-effects
to date values that are stored in columns of type TIMESTAMP
: MySQL converts TIMESTAMP
values from the server time zone
to UTC for storage, and back from UTC to the current time zone for retrieval. Read more about it in the
MySQL Docs.
Further Reading
7.13.15 to 7.13.16
Spin: updated dependencies
With this release, the following dependencies of Spin have been updated:
- json-path from 2.4.0 to 2.6.0
- accessors-smart from 1.2 to 2.4.7
- json-smart from 2.3 to 2.4.7
Standalone Webapplication: HikariCP replaces Commons DBCP
The standalone web applications now use HikariCP for data source configuration instead of Apache Commons DBCP. Replace
the org.apache.commons.dbcp.BasicDataSource
class in your applicationContext.xml
with a
com.zaxxer.hikari.HikariDataSource
. The HikariCP data source expects the JDBC URL on a property called jdbcUrl
instead of url
. Thus, you need to rename the url
property. Your data source description should look similar to
this, with DB-DRIVER-CLASS
, JDBC-URL
, DB-USER
, and DB-PASSWORD
replaced by values related to your database:
<bean id="dataSource" class="org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy">
<property name="targetDataSource">
<bean class="com.zaxxer.hikari.HikariDataSource">
<property name="driverClassName" value="DB-DRIVER-CLASS" />
<property name="jdbcUrl" value="JDBC-URL" />
<property name="username" value="DB-USER" />
<property name="password" value="DB-PASSWORD" />
</bean>
</property>
</bean>
7.13.17 to 7.13.18
The patches include version 2.1.0 of the org.camunda.template-engines
artifacts, in particular camunda-template-engines-freemarker
, camunda-template-engines-velocity
, and camunda-template-engines-xquery-saxon
.
This updates the following template engine versions:
- Apache Freemarker
- Old version: 2.3.29 (Release date: August 2019)
- New version: 2.3.31 (Release date: February 2021)
- Change log: https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-
- Apache Velocity
- Old version: 2.2 (Release date: January 2020)
- New version: 2.3 (Release date: March 2021)
- Change log: https://velocity.apache.org/engine/2.3/upgrading.html
Please note that the new version of Freemarker contains changes that are not compatible with the previous version. We strongly recommend to test the execution of your templates before applying the update. In addition, you can replace the artifacts of version 2.1.0 by the old artifacts in version 2.0.0 to continue using the old versions of Freemarker and Velocity.
Full Distribution
This section is applicable if you installed the Full Distribution with a shared process engine. In this case you need to update the libraries and applications installed inside the application server.
Please note that the following procedure may differ for cluster scenarios. Contact our support team if you need further assistance.
- Shut down the server
- Exchange Camunda Platform libraries, tools and webapps (EAR, RAR, Subsystem (JBoss), Shared Libs) - essentially, follow the installation guide for your server.
- Restart the server
Application With Embedded Process Engine
In case you use an embedded process engine inside your Java Application, you need to
- update the Process Engine library in your dependency management (Apache Maven, Gradle …),
- re-package the application,
- deploy the new version of the application.
Standalone Webapplication Distribution
In case you installed the Standalone Webapplication Distribution you need to
- undeploy the previous version of the webapplication,
- deploy the new version of the webapplication.
Applying Multiple Patches at Once
It is possible to apply multiple patches in one go (e.g., updating from 7.1.0
to 7.1.4
).