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.14.2 to 7.14.3.

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
7.14	engine_7.14_patch_7.14.2_to_7.14.3.sql	Re-define ACT_IDX_JOB_HANDLER index to make it work with extended data types on Oracle.	Oracle	CAM-12832

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 previous 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:

1. The default timer period can be changed to ‘this week’, ‘this month’ or ‘complete’
2. 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 call POST /history/cleanup
• HistoryService#findHistoryCleanupJob is deprecated (as well as GET /history/cleanup/job), one should use HistoryService#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.14.0 to 7.14.1 / 7.13.6 to 7.13.7

FEEL Engine: Changed Module Structure

With the above-mentioned patch releases, 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.14.3 to 7.14.4 / 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.

Further Reading

• Change Docker Environment Variables
• MySQL Connector/J 8.0 Migration Guide

7.14.9 to 7.14.10 / 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.14.11 to 7.14.12 / 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.

7.14.15 to 7.14.16

Spin configuration properties

This set of patches introduce configuration properties for the Spin DomXmlDataFormat module. The DomXmlDataFormat configuration properties provide options to toggle External XML Entity (XXE) processing, as well as secure processing for the Spin XML parser.

By default, we disabled XXE processing, and enabled secure processing of XML documents to protect the Spin XML parser against XXE attacks and Billion laughs attacks.

You can restore the old behavior by passing the appropriate configuration properties to the Spin process engine plugin.

7.14.17 to 7.14.18

This patch deactivates remote access to the H2 console application in the Tomcat and Wildfly distributions. The H2 application accepts only localhost connections moving forward.

To restore remote access, add the following initialization parameter to the org.h2.server.web.WebServlet servlet defined in the web.xml file of the h2 web application:

<init-param>
  <param-name>webAllowOthers</param-name>
  <param-value>true</param-value>
</init-param>

You can find the web.xml in the following paths:

• Tomcat distribution: server/apache-tomcat-${TOMCAT_VERSION}/webapps/h2/WEB-INF
• Wildfly distribution: server/wildfly-${WILDFLY_VERSION}/standalone/deployments/camunda-h2-webapp-${CAMUNDA_VERSION}.war/WEB-INF
• Docker container Tomcat: /camunda/webapps/h2/WEB-INF
• Docker container Wildfly: /camunda/standalone/deployments/camunda-h2-webapp-${CAMUNDA_VERSION}.war/WEB-INF

Please note that we strongly discourage enabling remote access because it creates a security risk.

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

1. update the Process Engine library in your dependency management (Apache Maven, Gradle …),
2. re-package the application,
3. deploy the new version of the application.

Standalone Webapplication Distribution

In case you installed the Standalone Webapplication Distribution you need to

1. undeploy the previous version of the webapplication,
2. 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).