Migrating an existing application from Activiti 5.x (or Camunda fox 6.x - see below) is straightforward. This page describes the necessary steps.

Getting Help: If you have any trouble, ask for assistance in the Forum.

The changes in short are:

• Maven Dependencies, e.g., activiti.jar changed to camunda-engine.jar.
• Package Names changed from org.activiti to org.camunda.bpm for all modules (including engine, CDI and spring).
• The configuration file changed from activiti.cfg.xml to camunda.cfg.xml.
• Several (internal) classes are renamed - see the lists below.

There are some things which have not changed yet:

• Database schema and table names. Note that we based our fork on Activiti 5.11 and the tables existent in that version.
• The camunda: Custom Extensions are kept. A Camunda BPM namespace will be introduced soon but backwards compatibility will be ensured.

We based our fork on the database schema of Activiti 5.11. So please upgrade your project to this database using the upgrade scripts provided by Activiti. If you are using a newer version, best ask for assistance in the Forum.

Exchange the existing library (here shown as Maven dependency)

<dependency>
  <groupId>org.activiti</groupId>
  <artifactId>activiti</artifactId>
  <version>5.11</version>
</dependency>

to

<dependency>
  <groupId>org.camunda.bpm</groupId>
  <artifactId>camunda-engine</artifactId>
  <version>7.0.0-Final</version>
</dependency>

Make sure that you have the Camunda Maven Repository set correctly:

<repository>
  <id>camunda-bpm-nexus</id>
  <name>camunda Maven Repository</name>
  <url>https://app.camunda.com/nexus/content/groups/public</url>
</repository>

Just do an Organize Imports in your IDE, that should do the trick as the API class names have not changed. Your IDE should figure out the rest for you. For Eclipse this can be done by clicking on the project and hitting Ctrl-Shift-O.

That's it - now your application should run again.

As Camunda fox included the Activiti engine you have to perform the above steps as well.

Before you can start with the migration from Camunda fox to Camunda BPM, we recommend that you download the pre-packaged distribution corresponding to your Camunda fox server.

To migrate your process application from Camunda fox to Camunda BPM, you need to follow these steps:

• Do the Activiti migration as described above, as Camunda fox included the Activiti engine.
• Remove the fox-platform-client.x.jar from your deployment - it is not needed anymore.
• Add a Process Application Class, see Process Applications.
• If you don't use our engine as embedded jar, you should set your maven-dependency for it to provided-scope
• Adjust the processes.xml to the new format, see Process Applications.
• If you completely migrate to our new distribution, you have to adjust your persistence.xml from FoxEngineDS to ProcessEngine
• If you use the new Camunda Tasklist component, you have to adjust the formKey, as described in the Getting Started section. We will provide more information soon. For JSF-Formkeys, your formkey should have the following format: /<application-context-path>/<form>.jsf. E.g., /loan-approval/request-loan.jsf

• If you use the fox.taskForm bean, make sure you have the camunda-engine-cdi dependency on your classpath:

  Please import the Camunda BOM to ensure correct versions for every Camunda project.

  <dependency>
    <groupId>org.camunda.bpm</groupId>
    <artifactId>camunda-engine-cdi</artifactId>
  </dependency>

• If you use @Inject with TaskForm, you have to add a @Named("...") annotation to the @Inject annotation due to backward-compatibility of fox.taskForm. There you have two choices: If you are using fox.taskForm in your process application and don't want to update all your jsf pages and beans you should use @Named("fox.taskForm"), otherwise you should use @Named("camundaTaskForm"). Your application server should write an error or a warning if you use the wrong one. So be careful! However, we recommend that you use the annotation @Named("camundaTaskForm").
• Since Camunda BPM 7.0, the unique constraint for the business key has been removed in the runtime and history tables and the database schema create and drop scripts. The migration scripts do not include the drop statements of the unique constraint for the business key. So if you do not rely on the unique constraint for the business key, you can delete the unique constraint yourself. See the following documentation about the Business Key to delete the unique constraint corresponding to your database.
• If you do a JNDI lookup to get one of the Platform Services (i.e., ProcessArchiveService or ProcessEngineService), you have to adjust the JNDI name to do the lookup as follows:
  • ProcessArchiveService:
    • Old JNDI name: java:global/camunda-fox-platform/process-engine/PlatformService!com.camunda.fox.platform.api.ProcessArchiveService
    • New JNDI name: java:global/camunda-bpm-platform/process-engine/ProcessApplicationService!org.camunda.bpm.ProcessApplicationService
    • Note: The name of ProcessArchiveService has changed to ProcessApplicationService.
  • ProcessEngineService:
    • Old JNDI name: java:global/camunda-fox-platform/process-engine/PlatformService!com.camunda.fox.platform.api.ProcessEngineService
    • New JNDI name: java:global/camunda-bpm-platform/process-engine/ProcessEngineService!org.camunda.bpm.ProcessEngineService

Be aware that there were major changes in our database structure. For migration from Camunda fox EE 6.2 and Camunda fox CE 1.34 we recommend to take a look at our migration scripts. These are located in the following folder of your downloaded pre-packaged distribution: $DISTRIBUTION_PATH/sql/upgrade. To perform the migration of your database, choose the corresponding upgrade script $DATABASE_engine_6.2_to_7.0 according to your database platform and run it.

JBoss AS 7.1.3

Upgrade the application server modules (JBoss)

• Delete the following folders:
  • $FOX_HOME/modules/com/camunda/
  • $FOX_HOME/modules/org/bouncycastle/
  • $FOX_HOME/modules/org/livetribe/
• Merge all content from $DISTRIBUTION_PATH/modules to $FOX_HOME/modules

Adjust the $FOX_HOME/standalone/configuration/standalone.xml

Change the Camunda JBoss subsystem as extension from:

<extension module="com.camunda.fox.platform.fox-platform-jboss-subsystem"/>

to:

<extension module="org.camunda.bpm.jboss.camunda-jboss-subsystem"/>

Remove the global modules:

<global-modules>
    <module name="com.camunda.fox.platform.fox-platform-api" />
    <module name="com.camunda.fox.engine.fox-engine" />
</global-modules>

and add the global module for Camunda BPM:

<global-modules>
    <module name="org.camunda.bpm.camunda-engine" slot="main"/>
</global-modules>

Adjust the Camunda JBoss subsystem configuration from:

<subsystem xmlns="urn:com.camunda.fox.fox-platform:1.1">

to:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">

Add authorizationEnabled and jobExecutorDeploymentAware properties to the configured process engines:

<process-engines>
  ...
  <process-engine name="${YOUR_PROCESS_ENGINE_NAME}">
    ...
    <properties>
      ...
      <property name="authorizationEnabled">true</property>
      <property name="jobExecutorDeploymentAware">true</property>
    </properties>
  </process-engine>
  ...
</process-engines>

Since Camunda BPM 7.0, you can configure built-in process engine plugins. For more details see this section of the user guide.

Replace the Camunda fox webapps with Camunda BPM webapps (JBoss)

• Undeploy the following Camunda fox webapps which are in the folder $FOX_HOME/standalone/deployments:
  • fox-cockpit-$FOX_VERSION.war
  • fox-cycle-$FOX_VERSION.war
  • fox-tasklist-$FOX_VERSION.war
• Deploy the following Camunda BPM webapps from $DISTRIBUTION_PATH/server/jboss-as-7.1.3.FINAL/standalone/deployments to $FOX_HOME/standalone/deployments:
  • camunda-cycle-jboss-$PLATFORM_VERSION.war
  • camunda-engine-rest-$PLATFORM_VERSION.war
  • camunda-webapp-jboss-$PLATFORM_VERSION.war
• You can delete the corresponding Cockpit tables because they are not needed anymore.

For more details about installing the Camunda BPM webapps read the installation guide.

GlassFish 3.1

Clean up the $FOX_HOME/glassfish/domains/<domain>/config/domain.xml

Remove the following applications:

<application
  location="${com.sun.aas.instanceRootURI}/applications/fox-platform-jobexecutor-rar/"
  name="fox-platform-jobexecutor-rar" object-type="user">
  ...
</application>

<application
  context-root="/cockpit"
  location="${com.sun.aas.instanceRootURI}/applications/fox-cockpit-glassfish-$FOX_VERSION/"
  name="fox-cockpit-glassfish-$FOX_VERSION" object-type="user">
  ...
</application>

<application
  context-root="/cycle"
  location="${com.sun.aas.instanceRootURI}/applications/fox-cycle-glassfish-$FOX_VERSION/"
  name="fox-cycle-glassfish-$FOX_VERSION" object-type="user">
  ...
</application>

<application
  context-root="/tasklist"
  location="${com.sun.aas.instanceRootURI}/applications/fox-tasklist-$FOX_VERSION/"
  name="fox-tasklist-$FOX_VERSION" object-type="user">
  ...
</application>

and the corresponding application references:

<application-ref ref="fox-platform-jobexecutor-rar" virtual-servers="server"></application-ref>

<application-ref ref="camunda-fox-platform" virtual-servers="server"></application-ref>

<application-ref ref="fox-cockpit-glassfish-$FOX_VERSION" virtual-servers="server"></application-ref>

<application-ref ref="fox-cycle-glassfish-$FOX_VERSION" virtual-servers="server"></application-ref>

<application-ref ref="fox-tasklist-$FOX_VERSION" virtual-servers="server"></application-ref>

To adjust the JDBC Connection Pool and JDBC Resources, replace the following JDBC resource:

<jdbc-resource pool-name="FoxEnginePool"
               jndi-name="jdbc/FoxEngine"
               enabled="true">
</jdbc-resource>

with:

<jdbc-resource pool-name="FoxEnginePool"
               jndi-name="jdbc/ProcessEngine"
               enabled="true">
</jdbc-resource>

and replace the following JDBC resource:

<resource-ref ref="jdbc/FoxEngine"></resource-ref>

with:

<resource-ref ref="jdbc/ProcessEngine"></resource-ref>

Adjust the configuration of the Thread Pool for the Job Executor from:

<resources>
  ...
  <resource-adapter-config
    thread-pool-ids="platform-jobexecutor-tp"
    resource-adapter-name="fox-platform-jobexecutor-rar">
  </resource-adapter-config>

  <connector-connection-pool
    name="platformJobExecutorPool"
    resource-adapter-name="fox-platform-jobexecutor-rar"
    connection-definition-name="com.camunda.fox.platform.jobexecutor.impl.ra.outbound.PlatformJobExecutorConnectionFactory"
    transaction-support="NoTransaction">
  </connector-connection-pool>

  <connector-resource
      enabled="true"
      pool-name="platformJobExecutorPool"
      jndi-name="eis/PlatformJobExecutorConnectionFactory" />
  ...
</resources>
...
<servers>
  <server>
    ...
    <resource-ref ref="eis/PlatformJobExecutorConnectionFactory"></resource-ref>
    ...
  </server>
</servers>

to:

<resources>
  ...
  <resource-adapter-config
    enabled="true"
    resource-adapter-name="camunda-jobexecutor-rar"
    thread-pool-ids="platform-jobexecutor-tp" >
  </resource-adapter-config>

  <connector-connection-pool
      enabled="true"
      name="platformJobExecutorPool"
      resource-adapter-name="camunda-jobexecutor-rar"
      connection-definition-name=
          "org.camunda.bpm.container.impl.threading.jca.outbound.JcaExecutorServiceConnectionFactory"
      transaction-support="NoTransaction" />

  <connector-resource
      enabled="true"
      pool-name="platformJobExecutorPool"
      jndi-name="eis/JcaExecutorServiceConnectionFactory" />
  ...
</resources>
...
<servers>
  <server>
    ...
    <resource-ref ref="eis/JcaExecutorServiceConnectionFactory"></resource-ref>
    ...
  </server>
</servers>

Upgrade the application server modules (GlassFish)

• Delete the following modules from the folder $FOX_HOME/glassfish/lib/:
  • fox-engine-$FOX_VERSION.jar
  • fox-platform-api-$FOX_VERSION.jar
• Merge all content from $DISTRIBUTION_PATH/modules/lib into $FOX_HOME/glassfish/lib/
• Delete the following applications from $FOX_HOME/glassfish/domains/<domain>/applications/:
  • camunda-fox-platform
  • fox-cockpit-glassfish-$FOX_VERSION
  • fox-cycle-glassfish-$FOX_VERSION
  • fox-platform-jobexecutor-rar
  • fox-tasklist-$FOX_VERSION
• Copy the jobexecutor resource adapter $DISTRIBUTION_PATH/modules/camunda-jobexecutor-rar-$PLATFORM_VERSION.rar to $FOX_HOME/glassfish/domains/<domain>/autodeploy. The jobexecutor resource adapter has to be deployed first because the artifact camunda-glassfish-ear-$PLATFORM_VERSION.ear depends on it and cannot be deployed successfully without the resource adapter. If you try to deploy both components with the auto-deploy feature in one step, you should be aware that in that case the deployment order is not defined. Due to this, we propose to startup the GlassFish to initially deploy the jobexecutor resource adapter. After a successful startup, shutdown the GlassFish application server.
• Copy the artifact $DISTRIBUTION_PATH/modules/camunda-glassfish-ear-$PLATFORM_VERSION.ear to $FOX_HOME/glassfish/domains/<domain>/autodeploy.
• After a successful startup, the Camunda BPM platform is installed.

Since Camunda BPM 7.0, you can configure built-in process engine plugins. For more details see this section of the user guide.

Replace the Camunda fox webapps with Camunda BPM webapps (GlassFish)

• The Camunda fox webapps have been already deleted in the previous steps. So you can additionally clean up the $FOX_HOME/glassfish/domains/<domain>/autodeploy/ folder and delete the following artifacts:
  • fox-cockpit-glassfish-$FOX_VERSION.war
  • fox-cycle-glassfish-$FOX_VERSION.war
  • fox-tasklist-$FOX_VERSION.war
• Deploy the following Camunda BPMN webapps from $DISTRIBUTION_PATH/glassfish3/glassfish/domains/domain1/autodeploy/ to $FOX_HOME/glassfish/domains/<domain>/autodeploy:
  • camunda-cycle-glassfish-$PLATFORM_VERSION.war
  • camunda-engine-rest-$PLATFORM_VERSION.war
  • camunda-webapp-glassfish-$PLATFORM_VERSION.war
• You can delete the corresponding Cockpit tables because they are not needed anymore.

IBM WebSphere Application Server

Undeploy Camunda fox webapps

• Open the WebSphere Integrated Solutions Console.
• Navigate to Applications / Application Types / WebSphere enterprise applications
• Select fox-cockpit-was-$FOX_VERSION.war and fox-cycle-was-$FOX_VERSION.war and uninstall them.

Upgrade the application server modules (IBM WebSphere Applicaton Server)

• Open the WebSphere Integrated Solutions Console.
• Navigate to Applications / Application Types / WebSphere enterprise applications
• Uninstall the Camunda platform application camunda-fox-platform
• Navigate to Resources / Resource Adapters / Resource Adapters
• Delete the camunda-fox-platform-jobexecutor-RAR resource adapter
• Navigate to Resources / Asynchronous Beans / Work Managers
• Delete the camunda-fox-platform-jobexecutor-WM work manager
• Navigate to Resources / JDBC / Datasources
• Select the defined data sources for the fox engine
• Change the JNDI-Name from jdbc/FoxEngine to jdbc/ProcessEngine
• Shutdown the IBM WebSphere Application Server
• Open the folder $FOX_HOME/lib/ext/ and delete the following artifacts:
  • fox-engine-$FOX_VERSION.jar
  • fox-platform-api-$FOX_VERSION.jar
• Now you can install Camunda BPM 7.0, to do so, see the installation guide and follow the instructions.

Since Camunda BPM 7.0, you can configure built-in process engine plugins. For more details see this section of the user guide.

Deploy Camunda BPM webapps

• Follow the installation instructions to deploy Camunda BPM webapps (like Cycle, Cockpit, etc.).
• Furthermore, you can delete the corresponding Cockpit tables because they are not needed anymore.

Getting Help: If you have any trouble, ask for assistance in the Forum. As an enterprise customer, you can contact our support team if you need further assistance.

This guide gives some hints and general guidelines / steps to follow when upgrading Camunda BPM from one minor version to the next one. It is NOT a migration guide by its own. Always check the concrete migration guide of the version from which you start the migration, e.g., migrate from Camunda BPM 7.0 to 7.1.

The migration guides usually cover following migration topics in detail:

• Database
• Engine (and plugins)
• Camunda web applications (and plugins)
• Process applications

Upgrading from a minor version to the next one

The general approach to migrate from one minor version to the next one involves the following steps:

1. Download the pre-packaged distribution corresponding to the next minor version from the Camunda website, e.g., camunda-bpm-tomcat-7.2.0.zip. As an enterprise customer, use the enterprise edition download page instead.
2. Migrate your database using the SQL scripts packaged inside the $DISTRIBUTION_PATH/sql/upgrade.
3. Upgrade the Camunda libraries and web applications on your server.
4. Upgrade your process applications.

Depending if you are running Camunda BPM as a shared engine or an embedded one, it differs what you have to do during steps 3 and 4. Check the concrete migration guide if there are any special steps you have to make.

When migrating your database to the next minor version, you have to do the following:

1. Check for any existing patch scripts for your database here that are within the bounds of your upgrade path. Locate the scripts at $DISTRIBUTION_PATH/sql/upgrade in the pre-packaged distribution or in the Camunda Nexus. We highly recommend to execute these patches before upgrading. Execute them in ascending order by version number. The naming pattern is $DATABASENAME_engine_$MINOR_VERSION_patch_$PLATFORM_VERSION_to_$NEW_PLATFORM_VERSION.sql, e.g., db2_engine_7.1_patch_7.1.9_to_7.1.10.sql.

2. Execute the corresponding upgrade scripts named

   • $DATABASENAME_engine_$MINOR_VERSION_to_$NEW_MINOR_VERSION.sql, e.g., db2_engine_7.1_to_7.2.sql
   • $DATABASENAME_identity_$MINOR_VERSION_to_$NEW_MINOR_VERSION.sql, e.g., db2_identity_7.1_to_7.2.sql

   The scripts migrate the database from one minor version to the next one and change the underlying database structure, so make sure to backup your database in case there are any failures during the upgrade 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 upgrading 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.2.X where X > 0. The procedure is the same as in step 1, only for the new minor version.

Check available SQL patch scripts for an overview of available SQL patch scripts for your current version.

Depending on the scenario in which the Camunda BPM platform is deployed, you have to adjust the upgrade process. Please note that the following procedure may differ for cluster scenarios. As an enterprise customer, you can contact our support team if you need further assistance.

When upgrading a shared or embedded engine, at least the following steps have to be done.

Shared Engine

• Shut down your application server.
• Exchange Camunda BPM libraries, tools and web applications (EAR, RAR, Subsystem (JBoss), Shared Libs) - essentially, follow the installation guide for your server.
• Restart your application server.

Embedded Engine

• Upgrade the Camunda-related dependencies in your WAR / EAR artifact.
• Rebuild and redeploy it.

For migration from Camunda BPM 7.0 to Camunda BPM 7.1, the provided upgrade scripts that match your database have to be executed. With a pre-packaged distribution, the upgrade scripts are located in the folder $DISTRIBUTION_PATH/sql/upgrade.

Check available SQL patch scripts for an overview of available sql patch scripts to see if there are any for your current version.

Regardless of the version you are migrating from, the main upgrade script is $DATABASE_engine_7.0_to_7.1.sql and has to be executed next.

To migrate your process application from Camunda BPM 7.0 to Camunda BPM 7.1, you need to follow these steps:

• If you use @Inject with TaskForm, you have to add a @Named("...") annotation to the @Inject annotation due to backward-compatibility of camunda.taskForm. There you have two choices: If you are using camunda.taskForm in your process application and don't want to update all your jsf pages and beans you should use @Named("camunda.taskForm"), otherwise you should use @Named("camundaTaskForm"). Your application server should write an error or a warning if you use the wrong one. So be careful! However, we recommend that you use the annotation @Named("camundaTaskForm").

In case you have to migrate (upgrade) the version of running process instances, we provide more information in our User Guide.

JBoss AS 7.1.3 to 7.2.0

Upgrade the JBoss application server

Camunda BPM 7.1 ships with a new version of the JBoss AS 7, namely, 7.2.0. The preferred upgrade steps are:

• copy all your custom modules / subsystems to the new JBoss server directory
• re-add all your custom modifications from the existing $CAMUNDA_HOME/standalone/configuration/standalone.xml to the new one located in the new JBoss server directory.
• copy all deployed datasources to the new JBoss server directory
• undeploy all process applications and copy them to the new JBoss server directory for redeployment

The following guide covers these use cases:

1. For administrators and developers: Migrate the database
2. For administrators and developers: Migrating a shared process engine setting
3. For administrators and developers: Migrating an embedded process engine setting
4. For developers: Migrating embedded task forms
5. For developers: Migrating a Cockpit plugin

This guide covers mandatory migration steps as well as optional steps that can be carried out to enable or disable new functionality included in Camunda BPM 7.2. The following concepts were introduced with Camunda BPM 7.2:

• CMMN: Case Management Model And Notation (CMMN) is a modelling standard similar to BPMN that focuses on human-centric processes. Camunda BPM 7.2 implements this standard and therefore extends the database schema during upgrade. If you do not plan to use CMMN, these tables will stay empty.
• Spin/Connect: Camunda Spin and Connect are optional Camunda extensions that ease the use of text-based data formats and connectivity in processes. Spin and Connect are separate modules that have to be explicitly added to and configured in an existing installation. This guide shows you how to enable/disable the usage of Spin and Connect.
• Freemarker: This optional Camunda extension provides a scripting engine for the templating language Freemarker that allows to use Freemarker as scripts in process constructs.

Before migrating, decide whether you additionally want to enable Spin/Connect and Freemarker. Based on this decision, you may have to carry out additional migration steps.

For migration from Camunda BPM 7.1 to Camunda BPM 7.2, the provided upgrade scripts that match your database have to be executed. With a pre-built distribution, the upgrade scripts are located in the folder $DISTRIBUTION_PATH/sql/upgrade.

If you migrate from a version < 7.1.4 or have not previously executed the 7.1.5 patch script, you have to execute the SQL script $DATABASE_engine_7.1_patch_7.1.4_to_7.1.5.sql first, where $DATABASE corresponds to the database platform you use.

If you migrate from a version < 7.1.10, you will have to execute the SQL script $DATABASE_engine_7.1_patch_7.1.9_to_7.1.10.sql.

Check available SQL patch scripts for an overview of available SQL patch scripts for your current version.

Regardless of the version you are migrating from, the main upgrade script is $DATABASE_engine_7.1_to_7.2.sql and has to be executed next.

When migrating a Camunda BPM shared engine installation, i.e., a scenario in which the process engine is configured as a central service on the application server, the following steps are required:

1. Upgrade of the Camunda libraries on the application server and optional configuration
2. Migrate process applications

Prerequisites:

• Before starting, make sure that you have downloaded the Camunda BPM 7.2 distribution for the application server you use. It contains the SQL scripts and libraries required for upgrade. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH.

1. Upgrade of the Camunda Libraries on the Application Server and Optional Configuration

Please choose the application server you are working with from the following list. You will be redirected to Camunda's installation guide.

• Apache Tomcat
• JBoss
• Glassfish
• IBM WebSphere
• Oracle WebLogic

2. Migration Process Applications

For every process application, the Camunda dependencies should be upgraded to the new Camunda version you are using. Which dependencies you have is application- and server-specific. Typically, the dependencies consist of any of the following:

• camunda-engine
• camunda-bpmn-model
• camunda-engine-spring
• camunda-engine-cdi
• camunda-ejb-client
• ...

There are no new mandatory dependencies. That means, upgrading the version should suffice to migrate a process application in terms of dependencies.

When migrating a Camunda BPM embedded engine, i.e., a process engine that is managed entirely within an application and bound to that application's lifecycle, the following steps are required:

1. Configure process engines (optional)
2. Upgrade Camunda dependencies

Prerequisites:

• Before starting, make sure that you have downloaded the Camunda BPM 7.2 distribution for the application server you use. It contains the SQL scripts required for upgrade. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH.

1. Configure Process Engines

This section describes a change in the engine's default behavior. While the change is reasonable, your implementation may rely on the previous default behavior. Thus, the previous behavior can be restored by explicitly setting a configuration option. Accordingly, this section applies to any embedded process engine but is not required for a successful upgrade.

Script Variable Storing

As of 7.2, the default behavior of script variables has changed. Script variables are set in e.g., a BPMN Script Task that uses a language such as JavaScript or Groovy. In previous versions, the process engine automatically stored all script variables as process variables. Starting with 7.2, this behavior has changed and the process engine does not automatically store script variables any longer. You can re-enable the legacy behavior by setting the boolean property autoStoreScriptVariables to true in your process engines' configurations. Depending on your scenario, this may involve updating a camunda.cfg.xml file, a processes.xml file or a programmatic configuration. For example, in a camunda.cfg.xml file, the property can be set as follows:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  ...
  <process-engine name="default">
    ...
    <properties>
      ... existing properties ...
      <property name="autoStoreScriptVariables">true</property>
    </properties>
    ...
  </process-engine>
  ...
</bpm-platform>

As an alternative, script code can be migrated by replacing all implicit declarations of process variables in scripts with an explicit call to execution.setVariable('varName', 'value').

2. Upgrade Camunda Dependencies

Upgrade the dependencies declared in your application's pom.xml file to the new Camunda version you are using. Which dependencies you have is application- and server-specific. Typically, the dependencies consist of any of the following:

• camunda-engine
• camunda-bpmn-model
• camunda-engine-spring
• camunda-engine-cdi
• camunda-ejb-client
• ...

There are no new mandatory dependencies. That means, upgrading the version should suffice to migrate a process application in terms of dependencies.

Embedded form support has been redesigned in Camunda BPM 7.2 and existing forms must be migrated.

Documentation on embedded forms support in 7.2 can be found in the Embedded Forms Reference

Overview

The following APIs / behavior has changed:

• The form-field directive has been replaced with cam-variable-name and cam-variable-type.
• The form now has a defined lifecycle (form-loaded, variables-fetched, ...) for which callbacks / event listeners can be provided.
• In 7.1, all process instance scope variables were fetched. In 7.2 only the variables used in the form are fetched. The variables are retrieved from the task scope and its parent scopes.

In the remainder of this section, we walk through these changes in detail.

The form-field directive

The form field directive is not supported in 7.2. HTML controls using the form-field directive need to be migrated.

The form-field directive was replaced by

• cam-variable-name: provides the name of the variable.
• cam-variable-type: provides the type of the variable.

The form-field directive on Input Fields

In 7.1, the form-field directive was used on input fields of the following form

<input form-field name="[variableName]" type="[type]" />

The name Attribute

In 7.2, the HTML name attribute is not used anymore for providing the name of the process variable. In 7.2, the cam-variable-name attribute must be used:

<input name="someName"
       cam-variable-name="[variableName]" />

The type Attribute

In 7.2 the HTML type attribute is not used anymore for providing the type of the variable. Instead, the cam-variable-type attribute is used:

<input name="someName"
       type="text|checkbox|hidden|..."
       cam-variable-name="[variableName]"
       cam-variable-type="[variableType]" />

Note: The cam-variable-type attribute is only required if the variable does not yet exist. If the variable already exists in the process, the attribute is not required.

Boolean

In 7.1 a boolean input field looked like this:

<input form-field name="VAR_NAME" type="boolean" />

In 7.2 it looks like this:

<input type="checkbox"
       cam-variable-name="VAR_NAME"
       cam-variable-type="Boolean" />

String

In 7.1 a string input field looked like this:

<input form-field name="VAR_NAME" type="string" />

In 7.2 it looks like this:

<input type="text"
       cam-variable-name="VAR_NAME"
       cam-variable-type="String" />

Number

In 7.1 a number input field looked like this:

<input form-field name="VAR_NAME" type="number" />

In 7.2 it looks like this:

<input type="text"
       cam-variable-name="VAR_NAME"
       cam-variable-type="Integer|Long|Short|Float|Double" />

Date

In 7.1 a date input field looked like this:

<input form-field name="VAR_NAME" type="date" />

In 7.2 it looks like this:

<input type="text"
       cam-variable-name="VAR_NAME"
       cam-variable-type="Date" />

See this Note on Datepickers

The form-field Directive on Select Boxes

In 7.1, select boxes had the following form:

<select form-field
        name="[variableName]"
        type="[type]"
        form-values="[optionsVarName]">
  <option value="[value]">[label]</option>
  <option value="[value]">[label]</option>
</select>

In 7.2, select boxes have the following form:

<select cam-variable-name="[variableName]"
        cam-variable-type="[type]"
        cam-choices="[optionsVarName]">
  <option value="[value]">[label]</option>
  <option value="[value]">[label]</option>
</select>

Serialized List and Map

In 7.1 a serialized java.util.List and java.util.Map instance could be used for populating the form-values="[optionsVarName]". In 7.2, this is possible in combination with the cam-choices="[optionsVarName]" directive. However, the lists and maps need to be serialized using the application/json dataformat:

Map<String, String> productTypes = new HashMap<String, String>();
productTypes.put("001", "Notebook");
productTypes.put("002", "Server");
productTypes.put("003", "Workstation");

execution.setVariable("AVAILABLE_PRODUCT_TYPES",  
  objectValue(customerData)
    .serializationDataFormat(SerializationDataFormats.JSON)
    .create());

The form-field Directive on a Textarea

In 7.1 a textarea control had the following form:

<textarea form-field name="[variableName]"></textarea>

In 7.2, it has the following form:

<textarea name="someName"
          cam-variable-name="[variableName]"
          cam-variable-type="String"></textarea>

Fetching additional variables

In 7.1 all variables from the process instance scope were fetched. In 7.2 the form needs to declare the variables it wants to fetch. This can be achieved declaratively or programmatically.

Fetching a variable using cam-variable-name

If you use the cam-variable-name directive, the corresponding process variable will be fetched.

Fetching a variable using JavaScript

Additional variables can be fetched by hooking into the form lifecycle.

<form role="form">

Value: {{customValue}}.

<script cam-script type="text/form-script">
var variableManager = camForm.variableManager;

camForm.on('form-loaded', function() {
  // this callback is executed *before* the variables are loaded from the server.
  // if we declare a variable here, its value will be fetched as well
  variableManager.fetchVariable('customVariable');
});

camForm.on('variables-fetched', function() {
  // this callback is executed *after* the variables have been fetched from the server
  $scope.customValue = variableManager.variableValue('customVariable');

});
</script>

</form>



As of version 7.2, Cockpit uses updated (and unpatched) versions of AngularJS (1.2.16) and Twitter Bootstrap (3.1.1). These updates introduce breaking changes in some heavily used features, such as JS promises, modal windows and a few more things described in detail below. Confer the AngularJS changelog and the Bootstrap migration guide for details.

First of all, bootstrap.js is not used anymore (it has been replaced by the angular-ui/bootstrap project), Only the CSS parts are kept (and they are being rewritten in order to leverage less compilation and avoid unnecessary declarations).

JS promises

The most critical change is probably the way JavaScript promises are implemented/used. If you had something like this in the 7.1 release:

SomeResource.$then(function(response) {
  var bar = response.data.something;
});

in the 7.2 release, it should look like:

// the resource returns an object having "$promise" (which has a method "then")
SomeResource.$promise.then(function(response) {
  // and the response does not have a "data" property
  var bar = response.something;
});

Dialogs / modal windows

Also widely used in web interfaces, the dialogues (a.k.a. modal windows) were completely rewritten. With the 7.1 release, you might have something like:

// a controller to open the dialog
module.controller('YadaYada', [
        'BimBamBum', '$dialog', '$scope',
function(BimBamBum,   $dialog,   $scope) {
  var dialogInstance = $dialog.dialog({
    // and a controller for the dialog content
    resolve: {
      foo: function() {
        return $scope.foo;
      },
      bar: function() {
        return BimBamBum.bar;
      }
    },
    // for the example, I wrote the dialog controller here
    // but it was generally found in a separate file (could have been "BimBamBum" for instance)
    controller: [
    // here "dialog" is the dialogInstance and "foo" and "bar" are _resolved_ (see above)
            'dialog', 'foo', 'bar',
    function(dialog,   foo,   bar) {
      // ...
    }]
  });

  // and finally, you would have open the dialog...
  dialogInstance.open().then(function() {
    // ...
  });
}];

From 7.2 onwards - using angular-ui/bootstrap - you have something like this:

// a controller to open the dialog
module.controller('YadaYada', [
        'BimBamBum', '$modal', '$scope',
function(BimBamBum,   $modal,   $scope) {
  // calling the "open" method of the "$modal" will create an instance
  $modal.open({
    // and a controller for the dialog content
    resolve: {
      // .. you know what comes here, right?
    },
    // again, for the example, I wrote the dialog controller here
    controller: [
            '$modalInstance', 'foo', 'bar',
    function($modalInstance,   foo,   bar) {
      // ...
    }]
  });
}];

Tooltips

In the 7.1 release, you could add tool tips using a help attribute like this:

<div class="yada-yada"
     help
     help-text="The text shown when mouse comes over this DIV"
     help-placement="'top'">
  ...
</div>

With the 7.2 release, the attributes would be:

<div class="yada-yada"
     tooltip="The text shown when mouse comes over this DIV"
     tooltip-placement="top">
  ...
</div>

Note the tooltip-placement value is not wrapped between single quotes anymore.

Pagers

Pagers need special attention because you might need to adapt setup and change your HTML. But generally speaking, if you have something like this with the 7.1 release:

$scope.pages = {
  size: 10,
  total: 0,
  current: 1
};
// ...
$http.post(Uri.appUri('plugin://base/:engine/incident/count'), params).success(function(data) {
  pages.total = Math.ceil(data.count / pages.size);
});

<div paginator total-pages="pages.total" current-page="pages.current"></div>

Then you will have something like this with the 7.2 release:

$scope.pages = {
  size: 10,
  total: 0,
  current: 1
};
// ...
$http.post(Uri.appUri('plugin://base/:engine/incident/count'), params).success(function(data) {
  pages.total = data.count;
});

<pagination ng-if="pages.total > pages.size"
            class="pagination-sm"
            page="pages.current"
            ng-model="pages.current"
            total-items="pages.total"
            items-per-page="pages.size"
            max-size="7"
            boundary-links="true"></pagination>

The following guide covers these use cases:

1. For administrators and developers: Migrate the database
2. For administrators and developers: Migrating a shared process engine setting
3. For administrators and developers: Migrating an embedded process engine setting
4. For developers: Migrating a Cockpit plugin
5. For administrators: Migrating a Tasklist translation file
6. For administrators and developers: Checking authorizations for newly introduced authorization resources

This guide covers mandatory migration steps as well as optional considerations for initial configuration of new functionality included in Camunda BPM 7.3. The following concepts were introduced with Camunda BPM 7.3 and are relevant for migration:

• Authorization: With Authorization being used for restricting access to applications and identity-related data in Camunda BPM 7.2, 7.3 extends authorization checks to execution-related concepts like process instances and tasks.

For migration from Camunda BPM 7.2 to Camunda BPM 7.3, the provided upgrade scripts that match your database have to be executed. With a pre-built distribution, the upgrade scripts are located in the folder $DISTRIBUTION_PATH/sql/upgrade.

If you migrate from a version < 7.2.5 and use DB2 or Microsoft SQL Server, you have to execute the SQL script $DATABASE_engine_7.2_patch_7.2.4_to_7.2.5.sql, where $DATABASE corresponds to the database platform you use.

Check available SQL patch scripts for an overview of available SQL patch scripts for your current version.

Regardless of the version you are migrating from, the main upgrade script is $DATABASE_engine_7.2_to_7.3.sql and has to be executed next.

When migrating a Camunda BPM shared engine installation, i.e., a scenario in which the process engine is configured as a central service on the application server, the following steps are required:

1. Upgrade of the Camunda libraries on the application server
2. Migrate process applications

Prerequisites:

• Before starting, make sure that you have downloaded the Camunda BPM 7.3 distribution for the application server you use. It contains the SQL scripts and libraries required for upgrade. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH.

No Rolling Upgrades

It is not possible to migrate process engines from Camunda 7.2 to 7.3 in a rolling fashion. This means, it is not possible to run process engines of version 7.2 and 7.3 in parallel with the same database configuration. The reason is that a 7.2 engine may not be able to execute process instances that have been previously executed by a 7.3 engine, as these may use features that were not available yet in 7.2.

1. Upgrade of the Camunda Libraries on the Application Server and Optional Configuration

Please choose the application server you are working with from the following list. You will be redirected to Camunda's installation guide.

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

2. Migration Process Applications

For every process application, the Camunda dependencies should be upgraded to the new Camunda version you are using. Which dependencies you have is application- and server-specific. Typically, the dependencies consist of any of the following:

• camunda-engine
• camunda-bpmn-model
• camunda-engine-spring
• camunda-engine-cdi
• camunda-ejb-client
• ...

There are no new mandatory dependencies. That means, upgrading the version should suffice to migrate a process application in terms of dependencies.

When migrating a Camunda BPM embedded engine, i.e., a process engine that is managed entirely within an application and bound to that application's lifecycle, the following steps are required:

1. Upgrade Camunda dependencies

Prerequisites:

• Before starting, make sure that you have downloaded the Camunda BPM 7.3 distribution for the application server you use. It contains the SQL scripts required for upgrade. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH.

No Rolling Upgrades

It is not possible to migrate process engines from Camunda 7.2 to 7.3 in a rolling fashion. This means, it is not possible to run process engines of version 7.2 and 7.3 in parallel with the same database configuration. The reason is that a 7.2 engine may not be able to execute process instances that have been previously executed by a 7.3 engine, as these may use features that were not available yet in 7.2.

1. Upgrade Camunda Dependencies

Upgrade the dependencies declared in your application's pom.xml file to the new Camunda version you are using. Which dependencies you have is application- and server-specific. Typically, the dependencies consist of any of the following:

• camunda-engine
• camunda-bpmn-model
• camunda-engine-spring
• camunda-engine-cdi
• camunda-ejb-client
• ...

There are no new mandatory dependencies. That means, upgrading the version should suffice to migrate a process application in terms of dependencies.

Migrating a Cockpit Plugin from Camunda BPM 7.2 to 7.3 consists of the following steps:

Client side:

• Replacing ngDefine with requireJS
• Reviewing usage of angular-ui
• Reviewing usage of bootstrap

Server side:

• Replacing Jackson 1 with Jackson 2

Replacing ngDefine with requireJS

As of version 7.3, the use of ngDefine in Cockpit and Admin Plugins is deprecated. You are encouraged to use requireJS instead. For information about the use of requireJS in plugins, see the How to develop a Cockpit Plugin Tutorial or the migration information below.

ngDefine remains part of the Cockpit and Admin app for backwards compatability, but may be removed in the future. ngDefine is not part of the Tasklist app. Tasklist plugins must be written using requireJS.

Replace ngDefine with define call

With ngDefine, you could create an angular module with its dependencies using the ngDefine call:

ngDefine('cockpit.plugin.myPlugin', [
  'jquery',
  'angular',
  'http://some-url/some-library.js',
  'module:some.other.angularModule:./someOtherModule.js'
], function(ngModule, $, angular) {
  // ...
});

From 7.3 onwards, you have to load dependencies using a define call and create and return the angular module in the callback:

define([
  'jquery',
  'angular',
  'http://some-url/some-library.js',
  './someOtherModule.js'
], function($, angular) {

  var ngModule = angular.module('cockpit.plugin.myPlugin', ['some.other.angularModule']);

  // ...

  return ngModule;
});

Reviewing usage of angular-ui

In the 7.3 release of the Admin and Cockpit UIs, the angular-ui, which is not supported anymore has been partially replaced by angular-bootstrap.

Custom Cockpit plugins might have used directives or filters provided by angular-ui and therefore need to be reviewed.

Hints

Typically, you can skip this if you do not have custom plugins, otherwise you might want to have a look at the templates of your custom plugins (because it is where filters and directives are expected to be used).

Directives which are not available anymore:

• ui-animate
• ui-calendar
• ui-codemirror
• ui-currency
• ui-date
• ui-event
• ui-if
• ui-jq
• ui-keypress
• ui-map
• ui-mask
• ui-reset
• ui-route
• ui-scrollfix
• ui-select2
• ui-showhide
• ui-sortable
• ui-tinymce
• ui-validate

Filters which are not availabe anymore:

• format
• highlight
• inflector
• unique

Reviewing usage of bootstrap

In the 7.3 release of the Admin and Cockpit UIs, bootstrap has been upgraded from version 3.1.1 to 3.3.1. You have to make sure that your plugin works with this new version of bootstrap.

Replacing Jackson 1 with Jackson 2

Beginning with 7.3, the REST API, as well as Cockpit, Tasklist and Admin use Jackson 2 instead of Jackson 1 for object mapping to and from JSON. Plugins explicitly using Jackson need to be migrated. In general, this consists of replacing the Jackson 1 packages org.codehaus.jackson with Jackson 2 packages com.fasterxml.jackson. Depending on the Jackson features used, further Jackson-specific migration may be required.

Jackson 2 JAX-RS polymorphic response

The Jackson 2 JAX-RS provider changes serialization of polymorphic types. Let's assume that your plugin's REST resource has a JAX-RS GET method with return type List<A>. A is an interface class with two implementing classes, B and C. With Jackson 2, the response JSON only contains properties defined in A. If your REST resource should dynamically include the properties of objects dependent on their actual class, consider adding the annotations com.fasterxml.jackson.annotation.JsonSubTypes and com.fasterxml.jackson.annotation.JsonTypeInfo to the superclass. See the Jackson Javadocs for details.

The following labels must be added to the Tasklist locale file:

• PROCESS_VARIABLE
• TASK_VARIABLE
• CASE_VARIABLE
• CREATE_TASK
• NEW_TASK_NAME
• NEW_TASK_ASSIGNEE
• NEW_TASK_DESCRIPTION
• TASK_SAVE_ERROR
• CHANGE
• ASC
• DESC
• BOOLEAN
• SHORT
• INTEGER
• LONG
• DOUBLE
• DATE
• STRING
• FILTER_CRITERIA_INCLUDE_ASSIGNED_TASKS
• FILTER_CRITERIA_INCLUDE_ASSIGNED_TASKS_HINT
• ADD_PERMISSION
• FILTER_FORM_PERMISSION_GROUP_USER
• FILTER_FORM_PERMISSION_IDENTIFIER
• BUSINESS_KEY
• ADD_SORT_BY
• REMOVE_SORTING
• EXECUTION_VARIABLE
• CASE_EXECUTION_VARIABLE
• CASE_INSTANCE_VARIABLE
• PROCESS_INSTANCE_ID
• PROCESS_INSTANCE_BUSINESS_KEY
• PROCESS_DEFINITION_ID
• PROCESS_DEFINITION_KEY
• PROCESS_DEFINITION_NAME
• EXECUTION_ID
• CASE_INSTANCE_ID
• CASE_INSTANCE_BUSINESS_KEY
• CASE_DEFINITION_ID
• CASE_DEFINITION_KEY
• CASE_DEFINITION_NAME
• CASE_EXECUTION_ID
• CANDIDATE_GROUP
• CANDIDATE_USER
• INVOLVED_USER
• TASK_DEFINITION_KEY
• DELEGATION_STATE
• LIKE

Have a look at the english translation file for a basis to translate.

As of version 7.3, it is possible to authorize access to process-related resources such as

• Deployment
• Process Definition
• Process Instance
• Task

so that an authenticated user can only see, modify, and delete those process definitions, process instances, and tasks for which the user is authorized to do so (for further details please read the User Guide).

The upgrade script $DATABASE_engine_7.2_to_7.3.sql contains INSERT-statements that create a new GLOBAL authorization and a new GRANT authorization for the group camunda-admin for each new authorization resource. These authorizations ensure that all users are able to access above-mentioned resources so that the process engine behaves the same way after the upgrade as it did before the upgrade.

If these authorizations are not desired and you want to restrict access to the listed resources, you have the following options:

• Before executing the upgrade script $DATABASE_engine_7.2_to_7.3.sql remove the corresponding INSERT-statements inside the script.
• Use the Camunda Admin application to delete the created authorizations.
• Use the Camunda Admin application to add authorizations that restrict access.

Upgrading over multiple Patch Level versions

It is possible to upgrade the Camunda BPM platform over multiple patch level versions (e.g., from 7.1.0 to 7.1.4). To do so, follow the steps listed below.

Within a minor version we will not change anything in our database structure. The database structure of all patch releases is backwards compatible to the corresponding minor version.

However, we do provide patch scripts for certain bugs that are caused by the database configuration. If you are affected by those bugs you have the option to run a patch script. We ship the patch scripts with the prepackaged distribution in the following location: $DISTRIBUTION_PATH/sql/upgrade, named: $DATABASE_engine_$VERSION_patch_$A_to_$B. Please execute all patch scripts that are within the bounds of your upgrade path. This means if your current patch version is X.X.1 and you upgrade to X.X.5 you have to execute all patch scripts first where $A ≥ X.X.1 and $B ≤ X.X.5.

Each patch script contains a comment what the fixes are related to and a link to the corresponding Camunda Jira issue.

Available SQL Patch scripts

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.

Depending on the scenario in which the Camunda BPM platform is deployed, you have to adjust the upgrade process. Please note that the following procedure may differ for cluster scenarios. Contact our support team if you need further assistance.

• Shut down your server
• Exchange Camunda BPM libraries, tools and webapps (EAR, RAR, Subsystem (JBoss), Shared Libs) - essentially, follow the installation guide for your server.
• Restart your server