Camunda Migration

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

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.

My Camunda version is less than 7.23.0!

For Camunda versions before 7.23.0, please do minor updates, before migrating to CIB seven, as described in Camunda version upgrade docs.

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.

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.

Impact post-migration:

If your processes utilize these objects, post-migration, attempting to access them may result in ClassNotFoundException.

You can search for the string pattern org.camunda.* inside the BPMN files to find the processes with the camunda namespace.

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.

Migration to CIB seven 1.1

Don't panic and use OpenRewrite!

There are renamings done in this version. It is too boring to do it manually. Just use Migration Script we made for you!

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

My Camunda version is less than 7.22!

For Camunda versions before 7.22 please do minor updates before migrating to CIB seven as described in Camunda version upgrade docs.

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>

On this Page: