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:
activiti.jar
changed to camunda-engine.jar
.org.activiti
to org.camunda.bpm
for all modules (including engine, CDI and spring).activiti.cfg.xml
to camunda.cfg.xml
.There are some things which have not changed yet:
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
.
component | Activiti class name | camunda class name |
---|---|---|
engine | ActivitiException | ProcessEngineException |
ActivitiClassLoadingException | ClassLoadingException | |
ActivitiOptimisticLockingException | OptimisticLockingException | |
ActivitiTaskAlreadyClaimedException | TaskAlreadyClaimedException | |
ActivitiWrongDbException | WrongDbException | |
ActivitRule | ProcessEngineRule | |
ActivitiTestCase | ProcessEngineTestCase | |
PluggableActivitiTestCase | PluggableProcessEngineTestCase | |
AbstractActivitiTestCase | AbstractProcessEngineTestCase | |
ResourceActivitiTestCase | ResourceProcessEngineTestCase | |
spring | ActivitiComponent | ProcessEngineComponent |
SpringActivitiTestCase | SpringProcessEngineTestCase | |
cdi | ActivitiCdiException | ProcessEngineCdiException |
ActivitiExtension | ProcessEngineExtension | |
CdiActivitiTestCase | CdiProcessEngineTestCase |
That's it - now your application should run again.
$DATABASE
expresses the target database platform, e.g. DB2, MySql etc.$DISTRIBUTION_PATH
represents the path of the downloaded pre-packaged Camunda BPM distribution, e.g., camunda-bpm-tomcat-$PLATFORM_VERSION.zip
or camunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz
for Tomcat etc.$PLATFORM_VERSION
denotes the version of the Camunda BPM platform you want to install, e.g., 7.0.0
.$FOX_HOME
points to the Camunda fox server main directory.$FOX_VERSION
denotes the version of the Camunda fox platform you have installed, e.g., 6.2.4
.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:
fox-platform-client.x.jar
from your deployment - it is not needed anymore.processes.xml
to the new format, see Process Applications.persistence.xml
from FoxEngineDS to ProcessEngineformKey
, 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:
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-engine-cdi</artifactId>
<version>$PLATFORM_VERSION</version>
</dependency>
@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")
.ProcessArchiveService
or ProcessEngineService
), you have to adjust the JNDI name to do the lookup as follows:java:global/camunda-fox-platform/process-engine/PlatformService!com.camunda.fox.platform.api.ProcessArchiveService
java:global/camunda-bpm-platform/process-engine/ProcessApplicationService!org.camunda.bpm.ProcessApplicationService
ProcessArchiveService
has changed to ProcessApplicationService
.java:global/camunda-fox-platform/process-engine/PlatformService!com.camunda.fox.platform.api.ProcessEngineService
java:global/camunda-bpm-platform/process-engine/ProcessEngineService!org.camunda.bpm.ProcessEngineService
component | camunda fox class name | camunda BPM class name |
---|---|---|
fox-platform-api | ProcessArchiveService | ProcessApplicationService |
fox-platform-client | ProcessArchiveSupport | DefaultEjbProcessApplication |
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.
$FOX_HOME/modules/com/camunda/
$FOX_HOME/modules/org/bouncycastle/
$FOX_HOME/modules/org/livetribe/
$DISTRIBUTION_PATH/modules
to $FOX_HOME/modules
$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.
$FOX_HOME/standalone/deployments
:fox-cockpit-$FOX_VERSION.war
fox-cycle-$FOX_VERSION.war
fox-tasklist-$FOX_VERSION.war
$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
For more details about installing the camunda BPM webapps read the installation guide.
$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>
$FOX_HOME/glassfish/lib/
:fox-engine-$FOX_VERSION.jar
fox-platform-api-$FOX_VERSION.jar
$DISTRIBUTION_PATH/modules/lib
into $FOX_HOME/glassfish/lib/
$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
$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.$DISTRIBUTION_PATH/modules/camunda-glassfish-ear-$PLATFORM_VERSION.ear
to $FOX_HOME/glassfish/domains/<domain>/autodeploy
.Since Camunda BPM 7.0 you can configure built-in process engine plugins. For more details see this section of the user guide.
$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
$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
Applications / Application Types / WebSphere enterprise applications
fox-cockpit-was-$FOX_VERSION.war
and fox-cycle-was-$FOX_VERSION.war
and uninstall them.Applications / Application Types / WebSphere enterprise applications
camunda-fox-platform
Resources / Resource Adapters / Resource Adapters
camunda-fox-platform-jobexecutor-RAR
resource adapterResources / Asynchronous Beans / Work Managers
camunda-fox-platform-jobexecutor-WM
work managerResources / JDBC / Datasources
jdbc/FoxEngine
to jdbc/ProcessEngine
$FOX_HOME/lib/ext/
and delete the following artifacts:fox-engine-$FOX_VERSION.jar
fox-platform-api-$FOX_VERSION.jar
Since Camunda BPM 7.0 you can configure built-in process engine plugins. For more details see this section of the user guide.
$DATABASE
expresses the target database platform, e.g., DB2, MySql, etc.$DISTRIBUTION_PATH
represents the path of the downloaded pre-packaged Camunda BPM distribution, e.g., camunda-bpm-tomcat-$PLATFORM_VERSION.zip
or camunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz
for Tomcat etc.$MINOR_VERSION
denotes the current minor version of the Camunda BPM platform you are currently using, e.g., 7.1
.$NEW_MINOR_VERSION
denotes the next minor version of the Camunda BPM platform you want to upgrade to, e.g., 7.2
.$PLATFORM_VERSION
denotes the version of the Camunda BPM platform you are currently using, e.g., 7.1.0
.$NEW_PLATFORM_VERSION
denotes the version of the Camunda BPM platform you want to upgrade to, e.g., 7.2.0
.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:
The general approach to migrate from one minor version to the next involves the following steps:
camunda-bpm-tomcat-7.2.0.zip
. As an enterprise customer, use the enterprise edition download page instead. $DISTRIBUTION_PATH/sql/upgrade
.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:
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
.
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.
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.
$DATABASE
expresses the target database platform, e.g., DB2, MySql, etc.$DISTRIBUTION_PATH
represents the path of the downloaded pre-packaged Camunda BPM distribution, e.g., camunda-bpm-tomcat-$PLATFORM_VERSION.zip
or camunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz
for Tomcat etc.$PLATFORM_VERSION
denotes the version of the Camunda BPM platform you want to install, e.g., 7.1.0
.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:
@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.
camunda bpm 7.1 ships with a new version of the JBoss AS 7, namely, 7.2.0. The preferred upgrade steps are:
$CAMUNDA_HOME/standalone/configuration/standalone.xml
to the new one located in the new JBoss server directory.$DATABASE
expresses the target database platform, e.g. DB2, MySql etc.$DISTRIBUTION_PATH
represents the path of the downloaded pre-packaged Camunda BPM distribution, e.g., camunda-bpm-tomcat-$PLATFORM_VERSION.zip
or camunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz
for Tomcat etc.$PLATFORM_VERSION
denotes the version of the Camunda BPM platform you want to install, e.g., 7.1.0
.Enterprise Feature
Please note that Patch Level Upgrades will only be provided to enterprise customers, they are not available in the community edition.Check the camunda enterprise homepage for more information or get your free trial version.
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.
Camunda Version | Patch file | Description | Affected databases | Issue link |
---|---|---|---|---|
7.1 | $DATABASE_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 | $DATABASE_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 | $DATABASE_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 $DATABASE_engine_7.1_patch_7.1.9_to_7.1.10.sql. | DB2, SQL Server | CAM-3565 |
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.