Update from 2.1 to 2.2
This document guides you through the update from CIB seven 2.1.x to 2.2.0 and covers the following use cases:
- For administrators and developers: Database updates
- For administrators and developers: Full distribution update
- For administrators and developers: Docker Base Image Update
- For administrators and developers: Docker Java 21 Only
- For administrators: OpenTelemetry and JMX metrics
- For administrators and developers: Spring Boot 4 Support
- For administrators and developers: Update to Tomcat 11
- For administrators and developers: Update to WildFly 40
- For administrators and developers: End of Java 11 support
- For administrators and developers: AI Agent Connector
- For administrators and developers: CIB seven Modeler
- For administrators: JWT secret configuration
- For administrators: Multi-engine support
- For administrators: License key location
- For administrators: Keycloak User provider renaming
- For administrators: Direct Provider
- For administrators: SCIM2 Identity Provider
- For administrators: New Configuration Options
This guide covers mandatory migration steps and optional considerations for the initial configuration of new functionality included in CIB seven 2.2.
Database updates
Every CIB seven installation requires a database schema update. Check our database schema update guide
for further instructions.
Note:
For rolling update SQL scripts, the file name versioning has been switched from Camunda 7 versioning to CIB seven versioning. The transition to CIB seven versioning changed version part in the file names from 7.x-based naming to 2.x-based naming, such as h2_engine_7.24_to_2.1.sql followed by h2_engine_2.1_to_2.2.sql. The Liquibase changelog has been updated accordingly to use the new CIB seven version identifiers as well.
Full distribution
This section is applicable if you installed the Full Distribution with a shared process engine.
The following steps are required:
- Update the CIB seven libraries and applications inside the application server.
- Migrate custom process applications.
Before starting, ensure you have downloaded the CIB seven 2.2 distribution for the application server you use. This contains the SQL scripts and libraries required for the update. This guide assumes you have unpacked the distribution to a path named $DISTRIBUTION_PATH.
Docker Base Image Update
The Docker base image has been updated from Alpine Linux 3.22 to Alpine Linux 3.23.
Migration Steps
For standard Docker image usage, no action is required beyond pulling the 2.2.0 image.
For custom Docker configurations:
- Assess Custom Code: Review any Alpine-specific customizations for version 3.23 compatibility.
- Update Dependencies: Check that the additional packages you install are available in Alpine 3.23.
- Rebuild Custom Images: Update Dockerfiles that extend the CIB seven base image.
- Test Migration: Verify functionality after updating to the new base image.
Docker Java 21 Only
For CIB seven 2.2.0, only Java 21 Docker images are published. Java 17 images are no longer built or released.
Java 21 is now the default image variant, so the java21- tag prefix has been removed. As a result, images are published under the regular tags such as cibseven:2.2.0 and cibseven:run-2.2.0, while the enterprise variants continue to use the -ee suffix.
Migration Steps
If you consume CIB seven Docker images in deployment scripts, CI pipelines, or container manifests, review image names and tags accordingly and switch any Java 17 or java21- prefixed references to the new default Java 21 tags.
OpenTelemetry and JMX metrics
Starting with CIB seven 2.2.0, the Docker images use the OpenTelemetry Java Agent instead of the Prometheus JMX Exporter for metrics and observability.
This change modernizes the observability setup and extends it beyond Prometheus-specific metrics. JMX metrics configuration files were added for extended JVM metrics collection, and the related tests and documentation were updated accordingly.
User impact
This change mainly affects installations that rely on the previous Prometheus JMX Exporter based setup.
If you use the standard Docker image defaults, no user impact is expected.
Migration steps
If you use custom monitoring or scraping configuration, review it and adapt it to the OpenTelemetry based metrics setup.
Spring Boot 4 Support
CIB seven 2.2.0 starts supporting Spring Boot 4. This includes a new Spring Boot 4 starter suite and a new Run4 distribution based on Spring Boot 4.
Additionally, the new Run4 distribution has been added to the Docker images.
User impact
This change only affects installations and applications that migrate from Spring Boot 3 to Spring Boot 4.
Migration steps
If you want to move from Spring Boot 3 to Spring Boot 4:
- Update your POM files to switch from the existing Spring Boot 3 starter modules to the new Spring Boot 4 starter modules.
- Review your project configuration and dependencies for Spring Boot 4 compatibility.
- Test your application thoroughly after the upgrade.
Update to Tomcat 11
With this release, CIB seven supports Tomcat 11 as the new default pre-packaged Tomcat distribution.
If you prefer to stay on Tomcat 10, you can still use the released CIB seven modules in your Tomcat 10 installation when updating to CIB seven 2.2.0, since the released modules remain compatible with Tomcat 10.
Update to WildFly 40
With this release, CIB seven supports WildFly 40 as the new default pre-packaged WildFly distribution.
If you prefer to stay on previous supported WildFly versions, such as WildFly 28 and higher, you can still use the released CIB seven modules in your WildFly installation when updating to CIB seven 2.2.0, since the released modules remain compatible with these WildFly versions.
End of Java 11 support
Java 11 is no longer supported. Starting with this release, CIB seven is not supported in Java 11 environments.
Update your Java runtime to a currently supported version, such as Java 17 or Java 21.
User impact
This change affects installations that still run on Java 11.
Migration steps
Update your Java environment to Java 17 or Java 21 before upgrading to CIB seven 2.2.0.
AI Agent Connector
The AI Agent Connector is a major new feature in CIB seven 2.2.0. It introduces the new cibseven-connect-ai-agent module, allowing BPMN service tasks to invoke AI agents through standard connector configuration without custom Java code.
The connector supports tool calling, retrieval-augmented generation with pgvector, chat memory, and audit trail capabilities. It also ships with a Knowledge Ingestor connector for preparing content used by AI-powered process interactions.
CIB seven Modeler
CIB seven 2.2.0 introduces CIB seven Modeler as a new web-based modeling application for BPMN, DMN, and embedded forms.
The modeler is integrated into cibseven-webclient and includes features such as visual BPMN and DMN modeling, form modeling, element templates, and direct deployment. For more details, see the CIB seven Modeler documentation.
BPMN AI Agent
BPMN AI Agent is integrated into the CIB seven Modeler and accessible in the Enterprise Edition only.
JWT secret configuration
Starting with CIB seven 2.2.0, the JWT secret for engine-rest can also be configured using the JVM system property cibseven.engine-rest.jwt-secret or the environment variable CIBSEVEN_ENGINE_REST_JWT_SECRET.
This is useful in environments where setting dotted property names as operating-system environment variables is problematic. No migration is required unless you want to switch from file-based configuration to the new system property or environment variable based setup.
Multi-engine support
CIB seven webclient supports connections to multiple engine REST endpoints, allowing a single webclient instance to manage multiple CIB seven engines.
This is useful for administrators and developers who need to switch quickly between environments such as development, test, and production. Additional engines can be configured via the additionalEngineRest property, and after configuration an additional engine selector icon appears in the webclient top menu.
For configuration details, see Multi-engine support.
License key location
Starting with CIB seven version 2.2.0, a license key is automatically saved in the database. This update allows to avoid a problem with applying a license key when the user home directory is placed on a read-only file system.
User impact
No user impact is expected.
Keycloak User provider renaming
The KeycloakUserProvider configuration name has been renamed to OAuth2UserProvider.
User impact
This change affects installations that explicitly configure KeycloakUserProvider.
Migration steps
When updating to CIB seven 2.2.0, review your default.yml or application.yml files and replace existing userProvider entries that still use KeycloakUserProvider with OAuth2UserProvider.
Direct Provider
Direct Provider is a new beta feature in CIB seven 2.2.0. It introduces SevenDirectProvider as an alternative BpmProvider implementation that accesses the process engine directly without REST.
This can be useful for embedded deployments that want tighter integration without going through REST APIs. As this feature is currently beta, it should be evaluated carefully before productive use.
User impact
No user impact is expected unless you want to adopt this new beta feature.
Migration steps
If you want to use this feature, configure your application to use SevenDirectProvider.
SCIM2 Identity Provider
SCIM2 Identity Provider Plugin is a new beta feature in CIB seven 2.2.0.
It allows CIB seven to integrate with a SCIM-compliant service and provides configurable caching and optional OIDC-secured access. As this feature is currently beta, it is intended for selected use cases and should be validated carefully before wider adoption.
User impact
No user impact is expected unless you want to enable SCIM 2.0 identity provider plugin.
Migration steps
If you want to use this feature, activate the plugin in the engine configuration and configure the plugin accordingly.
New Configuration Options
This release introduces several new configuration options:
checkVariableTaskId: validates that a referenced task exists and is not yet completed before assigning task variables, helping to prevent orphaned task variable references.authGroupFilterThreshold: can improve authorization query performance allowing to skip an auxiliary SQL query toACT_RU_AUTHORIZATIONwhen a user belongs to fewer groups than the configured threshold, which can improve performance for very large authorization tables.maxCallActivityRecursionDepth: prevents infinite recursion in call activities by enforcing a configurable recursion limit.
User impact
These options do not affect existing behavior by default. They preserve the original behavior unless explicitly enabled or configured.