Camunda Migration

This page describes the process of migrating a custom project, which uses Camunda BPM, to using CIB seven.

Migration script

To automate the renamings required when moving from Camunda to CIB seven, use the Migration Script, based on the OpenRewrite Maven plugin. It updates the versions and artifact names in your pom.xml files and the org.camunda imports in your Java code (see the version sections below for details).

Run from the command line

Execute in the root directory of your project:

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.configLocation=https://cibseven.github.io/cibseven-migration/replace-camunda-with-cibseven.yml -Drewrite.activeRecipes=org.cibseven.ReplaceCamundaWithCIBSeven

Run via the pom.xml

Alternatively, add the plugin configuration to your pom.xml:

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.openrewrite.maven</groupId>
        <artifactId>rewrite-maven-plugin</artifactId>
        <version>5.44.0</version>
        <configuration>
          <configLocation>
            https://cibseven.github.io/cibseven-migration/replace-camunda-with-cibseven.yml
          </configLocation>
          <activeRecipes>
            <recipe>org.cibseven.ReplaceCamundaWithCIBSeven</recipe>
          </activeRecipes>
        </configuration>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

and run:

mvn rewrite:run

Customize the migration

Download replace-camunda-with-cibseven.yml into the root directory of your project, adjust the recipe to your needs, and point the plugin to the local file:

<configLocation>${project.basedir}/replace-camunda-with-cibseven.yml</configLocation>

Clean up

After the migration, you can delete the YAML file and remove the rewrite-maven-plugin section from your pom.xml.

Migration to CIB seven 2.2

Before the migration, please check your Camunda version: it should be Camunda 7.24.0 If the version of Camunda is less than 7.24.0 then update it to 7.24.0, first.

For migration from Camunda 7.24.0 to CIB seven 2.2.0 you can use the following Migration Script, based on OpenRewrite maven plugin. This script performs the following actions:

• Changes version in pom.xml files: 7.24.0 -> 2.2.0.
• Changes artifacts names from camunda-* to cibseven-*.
• Changes namespaces inside imports, used in your custom Java code from org.camunda to org.cibseven.

Migration to CIB seven webclient

Among other things, CIB seven includes it own client: CIB seven webclient (however, the option of using the old Camunda web application remains available). The CIB seven webclient uses JWT-based authentication and requires a special JWT secret, which must be stored securely and be accessible to both, the engine REST and the webclient middleware. So, for migration to CIB seven webclient, you need to create file cibseven-webclient.properties on the classpath, ideally for both, the engine-REST and the webclient. This configuration file should contain a jwtSecret property with the same value:

   cibseven.webclient.authentication.jwtSecret=...

Place there your own 155-character alphanumeric secret.

Alternatively, the JWT secret can be specified via the environment variable CIBSEVEN_WEBCLIENT_AUTHENTICATION_JWTSECRET. In this case, the value specified in the environment variable takes precedence over the value from the cibseven-webclient.properties file.

Migration to CIB seven namespace

In some cases, processes created for Camunda may reference classes from the org.camunda namespace. For example:

• A process definition might include a script task that uses classes from the org.camunda namespace.
• A task can have an user variable of the camunda namespace.

All such objects are stored in the database and are not automatically renamed to the cibseven namespace during migration.

To ensure smooth operation post-migration, additional properties are available to facilitate the renaming of these objects from org.camunda namespace to org.cibseven upon the first access:

• useCibSevenNamespaceInScripting allows to handle org.camunda classes, used in a script, when the script is launched by a process
• useCibSevenNamespaceInReflection allows to convert serialized objects, stored in the database, from the camunda namespace to the cibseven namespace.

These properties are already included inside the configuration files for Tomcat (bpm_platform.xml), Wildfly (standalone.xml) and Run (production.yml) distributions of CIB seven 2.0 and higher, but the properties are disabled by default. Enabling these properties ensures smooth access to objects and prevents class loading errors after migration.

Liquibase changelog migration

When migrating from Camunda 7.24.0 to CIB seven 2.2.0, the Liquibase changelog location changes from:

org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml

to:

org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml

Liquibase identifies changesets by their author, ID, and changelog file path. Because the path changes, Liquibase treats the CIB seven changelog as a new changelog, even though the Camunda changesets it contains are identical to those of Camunda 7.24.0. Without additional steps, Liquibase may attempt to execute the historical changesets again.

To prevent this, we can suggest two possible workarounds: either rewrite the stored changelog path in the DATABASECHANGELOG table (Option A), or mark the existing history as already applied with changelog-sync-to-tag (Option B). Both tell Liquibase that the Camunda changesets have run, so only the CIB seven ones are executed.

Before migrating, ensure that the database schema has already been upgraded to Camunda 7.24.0.

Option A: Update DATABASECHANGELOG entries

First, configure Liquibase to use the CIB seven changelog at org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml. Depending on your installation, configure this through the Liquibase CLI, a liquibase.properties file, Spring Boot, or application-specific settings.

Then update the stored changelog path in the Liquibase history table:

UPDATE DATABASECHANGELOG
SET FILENAME = 'org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml'
WHERE FILENAME = 'org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml';

After this one-time adjustment, Liquibase recognizes the existing migration history and continues with the CIB seven-specific migrations.

Option B: Use changelog-sync-to-tag

If you use the Liquibase CLI, set changelogFile and searchPath in your liquibase.properties to the CIB seven values. On Liquibase versions older than 4.9, use classpath instead of searchPath.

Then synchronize the history to the last Camunda tag:

liquibase changelog-sync-to-tag --tag=7.24.0

This command marks all changesets up to tag 7.24.0 as executed in DATABASECHANGELOG without running them. Then run the normal upgrade:

liquibase update

Use this option only when the database schema is already at Camunda 7.24.0. This is normally satisfied by the recommendation to upgrade to Camunda 7.24.0 before migrating to CIB seven 2.2.0.

Migration to CIB seven 2.1

The backend of CIB seven 2.1.0 is based on Camunda 7.24.0, so before the migration, please check your Camunda version: it should be Camunda 7.24.0. If the version of Camunda is less than 7.24.0 then update it to 7.24.0, first.

In the rest, the migration process from Camunda 7.24.0 to CIB seven 2.1.0 follows the same steps as described in the section: Migration to CIB seven 2.0.

Please note that the considerations outlined in the Authorization Configuration section are also actual to 2.1.0 and 2.1.1 versions.

Liquibase changelog migration

When migrating from Camunda 7.24.0 to CIB seven 2.1.0, the Liquibase changelog location changes from:

org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml

to:

org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml

Liquibase identifies changesets by their author, ID, and changelog file path. Because the path changes, Liquibase treats the CIB seven changelog as a new changelog, even though its contents are identical to Camunda 7.24.0. Without additional steps, Liquibase may attempt to execute the historical changesets again.

To prevent this, we can suggest two possible workarounds: either rewrite the stored changelog path in the DATABASECHANGELOG table (Option A), or mark the existing history as already applied with changelog-sync-to-tag (Option B). Both tell Liquibase that the Camunda changesets have run, so only the CIB seven ones are executed.

Before migrating, ensure that the database schema has already been upgraded to Camunda 7.24.0.

Option A: Update DATABASECHANGELOG entries

First, configure Liquibase to use the CIB seven changelog at org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml. Depending on your installation, configure this through the Liquibase CLI, a liquibase.properties file, Spring Boot, or application-specific settings.

Then update the stored changelog path in the Liquibase history table:

UPDATE DATABASECHANGELOG
SET FILENAME = 'org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml'
WHERE FILENAME = 'org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml';

After this one-time adjustment, Liquibase recognizes the existing migration history and continues with the CIB seven-specific migrations.

Option B: Use changelog-sync-to-tag

If you use the Liquibase CLI, set changelogFile and searchPath in your liquibase.properties to the CIB seven values. On Liquibase versions older than 4.9, use classpath instead of searchPath.

Then synchronize the history to the last Camunda tag:

liquibase changelog-sync-to-tag --tag=7.24.0

This command marks all changesets up to tag 7.24.0 as executed in DATABASECHANGELOG without running them. Then run the normal upgrade:

liquibase update

Use this option only when the database schema is already at Camunda 7.24.0. This is normally satisfied by the prerequisite to upgrade to Camunda 7.24.0 before migrating to CIB seven 2.1.0.

Migration to CIB seven 2.0

The backend of CIB seven 2.0.0 is based on Camunda 7.23.0, so before the migration, please check your Camunda version: it should be Camunda 7.23.0. If the version of Camunda is less than 7.23.0 then update it to 7.23.0, first.

For migration from Camunda 7.23.0 to CIB seven 2.0 you can use the following Migration Script, based on OpenRewrite maven plugin. This script performs the following actions:

• Changes version in pom.xml files: 7.23.0 -> 2.0.0.
• Changes artifacts names from camunda-* to cibseven-*.
• Changes namespaces inside imports, used in your custom Java code from org.camunda to org.cibseven.

Migration to CIB seven webclient

Among other things, CIB seven 2.0.0 includes a new web client: CIB seven webclient (however, the option of using the old Camunda web application remains available). The CIB seven webclient uses JWT-based authentication and requires a special JWT secret, which must be stored securely and be accessible to both, the engine REST and the webclient middleware. So, for migration to CIB seven webclient, you need to create file cibseven-webclient.properties on the classpath, ideally for both, the engine-REST and the webclient. This configuration file should contain a jwtSecret property with the same value:

   cibseven.webclient.authentication.jwtSecret=...

Place there your own 155-character alphanumeric secret.

Alternatively, the JWT secret can be specified via the environment variable CIBSEVEN_WEBCLIENT_AUTHENTICATION_JWTSECRET. In this case, the value specified in the environment variable takes precedence over the value from the cibseven-webclient.properties file.

Authorization configuration

Important note: when upgrading to CIB seven version 2.0.4 or 2.0.5, verify the authorization settings in the engine configuration. If the authorization is enabled for the engine REST, ensure that the camunda.bpmn.authorization.enabled property is also added to the webclient configuration and is set to true.

Migration to CIB seven namespace

In some cases, processes created for Camunda may reference classes from the org.camunda namespace. For example:

• A process definition might include a script task that uses classes from the org.camunda namespace.
• A task can have an user variable of the camunda namespace.

All such objects are stored in the database and are not automatically renamed to the cibseven namespace during migration.

To ensure smooth operation post-migration, additional properties are available to facilitate the renaming of these objects from org.camunda namespace to org.cibseven upon the first access:

• useCibSevenNamespaceInScripting allows to handle org.camunda classes, used in a script, when the script is launched by a process
• useCibSevenNamespaceInReflection allows to convert serialized objects, stored in the database, from the camunda namespace to the cibseven namespace.

These properties are already included inside the configuration files for Tomcat (bpm_platform.xml), Wildfly (standalone.xml) and Run (production.yml) distributions of CIB seven 2.0 and higher, but the properties are disabled by default. Enabling these properties ensures smooth access to objects and prevents class loading errors after migration.

Liquibase changelog migration

When migrating from Camunda 7.23.0 to CIB seven 2.0.0, the Liquibase changelog location changes from:

org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml

to:

org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml

Liquibase identifies changesets by their author, ID, and changelog file path. Because the path changes, Liquibase treats the CIB seven changelog as a new changelog, even though its contents are identical to Camunda 7.23.0. Without additional steps, Liquibase may attempt to execute the historical changesets again.

To prevent this, we can suggest two possible workarounds: either rewrite the stored changelog path in the DATABASECHANGELOG table (Option A), or mark the existing history as already applied with changelog-sync-to-tag (Option B). Both tell Liquibase that the Camunda changesets have run, so only the CIB seven ones are executed.

Before migrating, ensure that the database schema has already been upgraded to Camunda 7.23.0.

Option A: Update DATABASECHANGELOG entries

First, configure Liquibase to use the CIB seven changelog at org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml. Depending on your installation, configure this through the Liquibase CLI, a liquibase.properties file, Spring Boot, or application-specific settings.

Then update the stored changelog path in the Liquibase history table:

UPDATE DATABASECHANGELOG
SET FILENAME = 'org/cibseven/bpm/engine/db/liquibase/camunda-changelog.xml'
WHERE FILENAME = 'org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml';

After this one-time adjustment, Liquibase recognizes the existing migration history and continues with the CIB seven-specific migrations.

Option B: Use changelog-sync-to-tag

If you use the Liquibase CLI, set changelogFile and searchPath in your liquibase.properties to the CIB seven values. On Liquibase versions older than 4.9, use classpath instead of searchPath.

Then synchronize the history to the last Camunda tag:

liquibase changelog-sync-to-tag --tag=7.23.0

This command marks all changesets up to tag 7.23.0 as executed in DATABASECHANGELOG without running them. Then run the normal upgrade:

liquibase update

Use this option only when the database schema is already at Camunda 7.23.0. This is normally satisfied by the prerequisite to upgrade to Camunda 7.23.0 before migrating to CIB seven 2.0.0.

Migration to CIB seven 1.1

CIB seven 1.1 has set of changes for versions, packages and artifacts naming. So you will need to update:

• Versions used (in pom.xml files): 7.22.0 -> 1.1.0.
• Artifacts names are changes from camunda-* to cibseven-* (for example camunda-bpm-spring-boot-starter-webapp is called now cibseven-bpm-spring-boot-starter-webapp).
• Imports used in custom code should now use org.cibseven.foo.bar instead of org.camunda.foo.bar packages.

All these changes can be done, using our Migration Script, based on OpenRewrite maven plugin (see GitHub for details).

Migration to CIB seven 1.0

CIB seven 1.0 is a special version with minimal changes from Camunda. No source level changes were applied, no library dependencies were changed.

We expect migration to this version should be as easy as possible. Only two steps are essential:

Change Version to 7.22.0-cibseven

Update your pom.xml files using Camunda and change version used from 7.22.x (usually 7.22.0 for Community Edition) to 7.22.0-cibseven.

Setup CIB seven Maven Repository

We are not able to deliver artifacts for other projects to any Maven Central repository. Version 7.22.0-cibseven is available only at artifacts.cibseven.org - our public maven repository.

You can add this repository to pom.xml for current project or to settings.xml in $M2_HOME (usually $HOME/.m2) folder for current user:

  <repositories>
    <repository>
      <id>mvn-cibseven-public</id>
      <name>CIB seven Public Repository</name>
      <url>https://artifacts.cibseven.org/repository/public/</url>
    </repository>
  </repositories>