Migration Guide

Migrating an existing application from Activiti 5.x (or camunda fox 6.x - see below) is straight forward. 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.
• A couple of (internal) classes are renamed - see list 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 this version.
• The camunda: Custom Extensions are kept. A camunda BPM namespace will be introduced soon but backwards compatibility will be ensured.

We base 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 assistence 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 Repostory 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 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 hit Ctrl-Shift-O.

That's it - your application should run again.

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

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

You have 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 migrate completely to our new distro you have to adjust your presistence.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. We 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:

  <dependency>
    <groupId>org.camunda.bpm</groupId>
    <artifactId>camunda-engine-cdi</artifactId>
    <version>$PLATFORM_VERSION</version>
  </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") else you should use @Named("camunda.taskForm"). Your application server should write an error or a warning if you use the wrong one. So be carefull! However, we recommend you to use the annotation @Named("camunda.taskForm").
• Since camunda BPM 7.0 the unique constraint for the business key is removed in the runtime and history tables and the database schema create and drop scripts. The migration scripts does 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 are able to delete the unique constraint by your own. 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 following:
  • 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 a look at our migration scripts which are located in the following folder of your downloaded pre-packaged distribution: $DISTRIBUTION_PATH/sql/upgrade. To perform the migration of your database choose according to your database platform the corresponding upgrade script $DATABASE_engine_6.2_to_7.0 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 are able to configure built-in process engine plugins, for more details see here.

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 are able to delete the corresponding Cockpit tables, because they are not needed anymore.

For further details about installing the camunda BPM webapps read the installation guide.

GlassFish 3.1

Cleanup 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 Resource 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

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

with

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

Configure 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 form 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 into $FOX_HOME/glassfish/domains/<domain>/autodeploy. The jobexecutor recource adapter has to be deployed first because the artifact camunda-glassfish-ear-$PLATFORM_VERSION.ear depends on it and cannot deployed succesfully without the resource adapter. If you try to deploy both compoments with the auto-deploy feature in one step you should be aware that the deployment order is not defined in this case. Due to this we propose to startup the Glassfish to deploy initially the jobexecutor resource adapter. After a successful startup shutdown the Glassfish.
• Copy the artifact $DISTRIBUTION_PATH/modules/camunda-glassfish-ear-$PLATFORM_VERSION.ear into $FOX_HOME/glassfish/domains/<domain>/autodeploy.
• After a successful startup the camunda BPM platform is installed.

Since camunda BPM 7.0 you are able to configure built-in process engine plugins, for more details see here.

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

• The camunda fox webapps has been already deleted in the previous steps. So you can additionally cleanup the $FOX_HOME/glassfish/domains/<domain>/autodeploy/ folder and delete the following artificats:
  • 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 are able to 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 (WebSphere)

• 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 definied 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 artificats:
  • fox-engine-$FOX_VERSION.jar
  • fox-platform-api-$FOX_VERSION.jar
• Now you are able to install camunda BPM 7.0, therefore you have to look in the installation guide and follow the instructions.

Since camunda BPM 7.0 you are able to configure built-in process engine plugins, for more details see here.

Deploy camunda BPM webapps

• Follow the installation instructions to deploy camunda BPM webapps (like Cycle, Cockpit etc.).
• Furthermore, you are able to 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 where you start the migration.

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 next one

The general approach to migrate from one minor version to the next 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 in your server.
4. Upgrade your process applications.

Depending if you are running Camunda BPM as a shared engine or an embedded one, if 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. Execute them by version number ordering. 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.1.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. Check for any existing patch scripts for your database that are within the bounds of the new minor version you are upgrading to and execute them in the version number order. 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 my 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 following steps have to 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.

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

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

• Shut down your server
• Exchange libraries and tools (EAR, RAR, Subsystem (JBoss), Shared Libs)
• Replace Webapps
• Restart your server