Update from 2.2 to 3.0

This document guides you through the update from CIB seven 2.2.x to 3.0.0 and covers the following use cases:

  1. For administrators and developers: Database updates
  2. For administrators and developers: Webclient database tables are now optional
  3. For administrators: New database indexes
  4. For administrators: Stalled “Delete deployments” batches
  5. For administrators and developers: Java 17 is required
  6. For administrators and developers: Java 25 and GraalJS 25
  7. For developers: Spring Boot 4 and Spring Framework 7 are required
  8. For administrators anddevelopers: Quarkus 3.33 extension update
  9. For administrators and developers: Java EE variants and Tomcat 9, WildFly 26 and WildFly 28 distributions removed
  10. For developers: JUnit 4 and JUnit 3 test support removed
  11. For administrators and developers: Jakarta EE 11
  12. For developers: Jakarta Expression Language 6.0
  13. For developers: ELResolver#getFeatureDescriptors removed
  14. For administrators and developers: Jakarta RESTful Web Services 4.0
  15. For administrators and developers: Jakarta Activation and MIME types of file variables
  16. For developers: Spin and annotations in the Tomcat distribution and CIB seven Run
  17. For administrators and developers: Jackson 3
  18. For developers: OSGi package imports
  19. For administrators: Software Bill of Materials
  20. For administrators: Permissions for task and process instance attachments
  21. For administrators: Permissions for task and process instance comments
  22. For administrators and developers: JUEL scripts use the expression manager’s resolver chain
  23. For administrators: Optional endpoint allow-list for connectors
  24. For administrators: AI Agent Connector sends the global API key only to the configured endpoint
  25. For administrators: Optional allow list for task types and script languages
  26. For administrators and developers: Deny list for expressions and scripts

This guide covers mandatory migration steps and optional considerations for the initial configuration of new functionality included in CIB seven 3.0.

The security changes in this guide, from Permissions for task and process instance attachments on, also ship with CIB seven 2.2.5. If you update from 2.2.5 or later, they are already in effect, with one exception: on 2.2.5 the deny list for expressions and scripts is only active if deniedExpressionAccess is set; from 3.0.0 on it is active by default.

Breaking changes at a glance

  • Java 17 is required: all CIB seven 3.0 artifacts need Java 17, including the Java External Task Client used by your external task workers, the standalone DMN engine, Spin, Connect and the model APIs, so move everything that still runs on Java 11 to Java 17 before the update.
  • Spring Boot 4 and Spring Framework 7 are required: the Spring Boot starters, CIB seven Run and the Spring integration use Spring Boot 4.1 and Spring Framework 7. Spring Boot 3 is no longer supported.
  • Java EE variants and Tomcat 9, WildFly 26 and WildFly 28 distributions removed: the artifacts with the suffix -jakarta no longer exist. Use the artifacts without suffix.
  • JUnit 4 and JUnit 3 test support removed: ProcessEngineRule, DmnEngineRule and ProcessEngineTestCase no longer work in JUnit 4 or JUnit 3 tests, and the Spring Boot test starter no longer brings the JUnit Vintage engine. Move your process tests to JUnit 5.
  • Jakarta EE 11 and Jakarta Expression Language 6.0: CIB seven is compiled against Jakarta EE 11 and Jakarta Expression Language (EL) 6.0, so compile your own code against the same API versions; Jakarta EE 10 runtimes keep working. The expressions in your BPMN, CMMN and DMN models do not change.
  • Jakarta Expression Language 6.0 and ELResolver#getFeatureDescriptors removed: custom EL classes, for example an ELResolver, and process applications that override getElResolver(), getBeanElResolver() or initProcessApplicationElResolver() must switch from org.cibseven.bpm.impl.juel.jakarta.el to jakarta.el and be recompiled. Resolvers that override or call getFeatureDescriptors no longer compile.
  • Jakarta RESTful Web Services 4.0: the REST API is compiled against JAX-RS 4.0 and the Tomcat distribution now ships RESTEasy 7.0 instead of 6.2, so your own JAX-RS resources and providers must work with JAX-RS 4.0.
  • Jackson 3: Spin JSON, the Java External Task Client, the REST API and the Spring Boot starters use Jackson 3 (tools.jackson) instead of Jackson 2. Annotations of jackson-databind 2 on your variable classes are ignored, class ids on properties of type Object are no longer read, and code that needs Jackson 2 has to bring it itself. Back up the database before the update: the first read of an object variable can store it in its new form.
  • OSGi package imports: the OSGi bundles import the Jakarta packages in the ranges of Jakarta EE 11, for example jakarta.el in [6.0,7), and require Java 17.
  • New database indexes: check for existing indexes on ACT_HI_JOB_LOG(DEPLOYMENT_ID_) and ACT_RU_TASK(PARENT_TASK_ID_) before you run the update script, and plan for the time the job log index build takes.
  • Permissions for task and process instance attachments and Permissions for task and process instance comments: with authorization enabled, reading and writing attachments and comments now need a permission on the task or process instance, otherwise the call fails with an AuthorizationException (HTTP 403 in the REST API). enforceAttachmentPermissions and enforceCommentPermissions set to false restore the previous behavior.
  • JUEL scripts use the expression manager’s resolver chain: with a customized expression manager, its restrictions now apply to JUEL scripts, and names that only the script resolver factories provided, context and lang:import are no longer available there.
  • AI Agent Connector sends the global API key only to the configured endpoint: models that set their own base URL no longer receive OPENAI_API_KEY. Set OPENAI_BASE_URL to that endpoint or define the API key in the model.
  • Deny list for expressions and scripts: expressions and JUEL scripts that use reflection, Class objects, lang:import or the process engine configuration now fail. Start with expressionHardeningMode=report to find them.

The changes to attachments, comments, JUEL scripts and the AI Agent Connector already apply from 2.2.5 on. The deny list is active by default only from 3.0.0 on; on 2.2.5 it applies only if deniedExpressionAccess is set.

Database updates

Every CIB seven installation requires a database schema update. Check our database schema update guide for further instructions.

Important Note: The update from 2.2 to 3.0 ships two scripts per database instead of one: <database>_engine_2.2_to_3.0.sql for the process engine and <database>_extensions_2.2_to_3.0.sql for the tables of the CIB seven webclient. See Webclient database tables are now optional for which of them you need to run.

Webclient database tables are now optional

The CIB seven webclient owns a group of database tables that the process engine itself never reads: MOD_ for the modeler, CHAT_ for chat, and NOTIF_ for notifications. Until CIB seven 2.2.x the engine created them unconditionally, so every installation carried them whether or not it ran the webclient.

Starting with CIB seven 3.0.0 they form a schema component of their own, controlled by the new engine property webclientExtensionsEnabled, which is disabled by default. The engine no longer creates these tables unless you ask it to, and they ship as their own SQL scripts rather than inside the engine scripts.

No table is renamed or removed

This change concerns who creates these tables and which script contains them. The tables themselves, their columns and their contents are unchanged. An existing database keeps its data, and nothing drops these tables during an update.

The previous property name modelerEnabled still works and sets the same value, so an existing bpm-platform.xml or Spring configuration continues to start. It is deprecated and will be removed in a future release.

What changed in detail

  • Engine property. modelerEnabled is renamed to webclientExtensionsEnabled, and its default changes from true to false. It now governs the modeler, chat and notification tables together. The pre-packaged distributions set it to true in their shipped configuration, so their behaviour is unchanged.
  • Create and drop scripts. The webclient tables have moved out of <database>_engine_<version>.sql into <database>_extensions_<version>.sql, alongside the long-standing <database>_identity_<version>.sql.
  • Update scripts. The 2.2 to 3.0 update is split into <database>_engine_2.2_to_3.0.sql and <database>_extensions_2.2_to_3.0.sql.
  • Liquibase. A separate changeset applies the webclient tables. It runs only where those tables are already present, so an installation without them is left untouched.
  • Schema version. The webclient schema records its version in ACT_GE_PROPERTY under webclient.extensions.version. The engine reports it through the REST API as webclientExtensionsVersion, in the response of GET /configuration, so the webclient can tell whether its tables are present and current. The field is null when the tables are absent.

User impact

The impact depends on how your schema is managed and on whether you run the webclient.

Existing installations that update to 3.0.0 keep their webclient tables. Nothing removes them, and the webclient continues to read them. You do, however, have to apply the webclient update script to bring them to the 3.0 state - see the migration steps below.

Pre-packaged distributions - Tomcat, WildFly and Run - set webclientExtensionsEnabled to true in their shipped configuration. A new installation therefore still creates all tables and offers all webclient features out of the box, and no action is required. If you do not use the modeler, chat and notification features, set the property to false to keep these tables out of your database.

Engines you configure yourself - an embedded Spring Boot or Quarkus application, a custom container image, or any installation that does not use the shipped distribution configuration - no longer get these tables, because the engine default is false. Enable the property if such an installation serves the CIB seven webclient. Otherwise no action is required, and this is the purpose of the change.

Installations that already set modelerEnabled continue to work unchanged; the property is accepted and applied to webclientExtensionsEnabled.

Migration steps

Choose the steps that match how your database schema is managed.

If you update the schema with the SQL scripts

Run the engine update script, then the webclient one if you use the CIB seven webclient:

<database>_engine_2.2_to_3.0.sql
<database>_extensions_2.2_to_3.0.sql

Skip the second script if you do not use the webclient. Its tables then stay at their 2.2 state, and you can apply the script later.

If you create a new schema with the SQL scripts

Run the webclient script in addition to the engine and identity scripts:

<database>_engine_<version>.sql
<database>_identity_<version>.sql
<database>_extensions_<version>.sql

If you let the engine create or update the schema

The pre-packaged distributions already set the property, so there is nothing to do. For an engine you configure yourself, set it when the installation serves the webclient and relies on databaseSchemaUpdate:

<property name="webclientExtensionsEnabled">true</property>

In a Spring Boot application, set it as a generic engine property:

camunda.bpm:
  generic-properties.properties:
    webclientExtensionsEnabled: true

If you do not use the modeler, chat and notifications

Set the same property to false to keep these tables out of your database. In a pre-packaged distribution, change the value in bpm-platform.xml, standalone.xml or default.yml. An engine you configure yourself already defaults to false.

This setting does not remove tables that already exist. Run the webclient drop script if you want them gone.

If you update the schema with Liquibase

No action is required. The webclient changeset recognises an existing webclient schema and updates it; an installation without those tables is left as it is.

New database indexes

The 3.0 update script creates a few new indexes:

  • ACT_IDX_HI_JOB_LOG_DEPLOYMENT on ACT_HI_JOB_LOG(DEPLOYMENT_ID_), on all databases. Without it, deleting a deployment with cascade (RepositoryService#deleteDeployment(id, true) or REST DELETE /deployment/{id}?cascade=true) scans the whole job log table.
  • ACT_IDX_TASK_PARENT_TASK_ID on ACT_RU_TASK(PARENT_TASK_ID_), on all databases except Microsoft SQL Server, where it already exists.

User impact

ACT_RU_TASK is a runtime table and normally small, so ACT_IDX_TASK_PARENT_TASK_ID is built quickly. The rest of this section is about the job log index.

The database reads the whole ACT_HI_JOB_LOG table to build the index. On a large job log this takes a while: on a PostgreSQL system with a 61 GB job log, building the index took about 25 minutes. Plan your update window accordingly.

Database Writes to ACT_HI_JOB_LOG during the build
PostgreSQL blocked
Oracle blocked
Microsoft SQL Server blocked
MySQL, MariaDB allowed (InnoDB online DDL)
IBM Db2 allowed, except briefly at the end
H2 –

With history level full, the default of the pre-packaged distributions, CIB seven Run and the Spring Boot starter, every job execution writes to ACT_HI_JOB_LOG. While these writes are blocked, jobs cannot finish. This matters if process engines keep running while you update the database, for example during a rolling update.

Migration steps

Check for an existing index first. Some installations created an index on ACT_HI_JOB_LOG(DEPLOYMENT_ID_) themselves after slow deployment deletions. The update script creates the index unconditionally, so it fails on every database if an index named ACT_IDX_HI_JOB_LOG_DEPLOYMENT already exists. On Oracle it also fails if another index covers the same column (ORA-01408). Check before you start the update:

  • PostgreSQL: select indexname, indexdef from pg_indexes where tablename = 'act_hi_job_log';
  • MySQL, MariaDB: show index from ACT_HI_JOB_LOG;
  • Oracle: select index_name, column_name from user_ind_columns where table_name = 'ACT_HI_JOB_LOG';
  • SQL Server: select name from sys.indexes where object_id = object_id('ACT_HI_JOB_LOG');
  • Db2: select indname, colnames from syscat.indexes where tabname = 'ACT_HI_JOB_LOG';

If you find such an index, drop it before the update. The update script then builds the index again.

The same applies to ACT_IDX_TASK_PARENT_TASK_ID: check ACT_RU_TASK with the same queries, and drop an index of that name if you find one. On Microsoft SQL Server the update script does not create it.

Stalled “Delete deployments” batches

In 2.2.2 to 2.2.4, the “Delete deployments” batch (RepositoryService#deleteDeploymentsAsync, REST POST /deployment/delete, “Delete deployments” in the Cockpit batch operations) can stall with a deployment-aware job executor, which the Tomcat and WildFly distributions use by default. The batch bound its jobs to the deployments it deletes, so the job executor stopped picking them up after the first deployment was deleted, or did not pick them up at all for deployments that were not registered on any node. In 3.0, the batch no longer binds its jobs to a deployment; see Delete Deployments.

User impact

A batch that stalled before the update stays stalled after it: its jobs were stored with the binding. It stays in progress, and the number of its remaining jobs does not change. Executing its seed job by hand does not help.

Migration steps

After the update, look for “Delete deployments” batches that do not progress, for example with GET /batch/statistics?type=deployment-deletion. For each of them:

  1. Delete the batch with ManagementService#deleteBatch or REST DELETE /batch/{id}. With cascade=true, its history is deleted as well.
  2. Start a new “Delete deployments” batch for the deployments that are still there, with the same deployment query or with their ids. Do not pass the ids of deployments that the old batch already deleted: the request is rejected if a deployment does not exist.

Java 17 is required

CIB seven 2.2 ended the support for Java 11 runtimes. With 3.0, all CIB seven artifacts are compiled for Java 17 (class file version 61). They no longer load on a Java 11 runtime.

User impact

This affects every component that still runs on Java 11, also outside the application server:

  • applications with an embedded process engine,
  • standalone DMN engine usage,
  • external task workers that use the Java External Task Client,
  • applications that use the BPMN, CMMN or DMN model API, Spin or Connect on their own.

Migration steps

Update the Java runtime of all these components to Java 17, 21 or 25 before you update to CIB seven 3.0.0. Applications that compile against CIB seven need a JDK 17 or later and must not set --release (or source/target) below 17.

Java 25 and GraalJS 25

CIB seven 3.0 supports Java 17, 21 and 25 and is tested on all three versions. The artifacts are compiled for Java 17 (see Java 17 is required), so the same artifacts run on each of them.

CIB seven 3.0 also updates GraalVM JavaScript (GraalJS), the JavaScript engine of the pre-packaged distributions, from 21.3 to 25.0.1. The 21.3 line does not run on Java 25, so supporting Java 25 required this upgrade; the new version ships for every installation, not only for those that move to Java 25.

User impact

  • GraalJS 25 consists of more artifacts than GraalJS 21.3. org.graalvm.js:js is now a POM without a jar. It brings the language (org.graalvm.js:js-language) and the Truffle runtime (org.graalvm.truffle:truffle-runtime). The polyglot API (org.graalvm.polyglot) moved from org.graalvm.sdk:graal-sdk to org.graalvm.polyglot:polyglot. The Tomcat and WildFly distributions and CIB seven Run contain the new artifacts. CIB seven does not add GraalJS to an embedded process engine: if you use JavaScript there, your application brings GraalJS itself.
  • An in-place update of a Tomcat or WildFly installation must not replace only the files that are already there: graal-sdk and js no longer exist as jars and several artifacts are new, so a partial replacement leaves an incomplete runtime — a chain of NoClassDefFoundError the first time a script runs, or a ModuleLoadError while WildFly boots. Follow the Tomcat and WildFly / JBoss EAP pages.
  • GraalJS 21.3 depended on ICU (com.ibm.icu:icu4j). With GraalJS on the class path, the com.ibm.icu classes were available to your code and to JavaScript and Groovy scripts. GraalJS 25 uses its own relocated copy (org.graalvm.shadowed:icu4j, package org.graalvm.shadowed.com.ibm.icu), which does not provide com.ibm.icu. The Tomcat and WildFly distributions and CIB seven Run still contain com.ibm.icu:icu4j 71.1, next to the shaded copy: icu4j-71.1.jar and icu4j-25.0.1.jar in lib/, two modules in WildFly. Both are needed, and neither replaces the other. In your own application, the com.ibm.icu classes are missing after the update to GraalJS 25 unless you add ICU yourself.
  • In GraalJS 25, the Nashorn compatibility mode alone accepts ECMAScript 5 only, so let, const and arrow functions fail with a SyntaxError. If enableScriptEngineNashornCompatibility is true, CIB seven 3.0 therefore also sets the ECMAScript version to 2022 (js.ecmascript-version). Scripts in this mode can use let, const, arrow functions and the built-in objects of ECMAScript 2022. In 2.2, scripts in this mode could already use let, const and arrow functions, but built-in objects such as Map, Set, Symbol and Promise were not defined.
  • As in 2.2, GraalJS runs scripts in interpreter mode on a standard OpenJDK and compiles them only on a JVM that supports it, for example a GraalVM JDK. On WildFly and JBoss EAP, CIB seven 3.0.0 supports interpreter mode only: the module org.graalvm.truffle.truffle-runtime is part of the distribution, but no other module depends on it.
  • On Java 25, the JVM can print warnings when GraalJS starts: GraalJS calls the restricted method System::load and memory access methods of sun.misc.Unsafe. The scripts still run.
  • In script tasks, listeners, input and output mappings, conditions and DMN expressions, GraalJS 25 changes the number types a script hands to Java and the script error messages.

Migration steps

  • If your application embeds the process engine and brings GraalJS itself, update GraalJS to 25.0.1, the version CIB seven 3.0 is tested with, and declare org.graalvm.js:js with <type>pom</type>:

    <dependency>
      <groupId>org.graalvm.js</groupId>
      <artifactId>js</artifactId>
      <version>25.0.1</version>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>org.graalvm.js</groupId>
      <artifactId>js-scriptengine</artifactId>
      <version>25.0.1</version>
    </dependency>
    

    Without <type>pom</type>, Maven looks for js-25.0.1.jar, which does not exist, and the build fails with Could not find artifact org.graalvm.js:js:jar:25.0.1. Keep js-scriptengine as a separate dependency: it is the JSR-223 bridge that ScriptEngineManager discovers, and the js POM does not bring it in. Everything else is resolved transitively.

  • If your code or your scripts use com.ibm.icu classes, add com.ibm.icu:icu4j to your application. The distributions contain version 71.1.

  • If you create the GraalJS context yourself and set js.nashorn-compat, for example in a custom ScriptEngineResolver, also set js.ecmascript-version, for example to 2022. Otherwise, your scripts are limited to ECMAScript 5.

  • If you installed CIB seven into Tomcat manually, remove the GraalJS 21.3 jars from $TOMCAT_HOME/lib/ (graal-sdk-21.3.*.jar, js-21.3.*.jar, js-scriptengine-21.3.*.jar, regex-21.3.*.jar and truffle-api-21.3.*.jar) and copy the jars listed in GraalVM JavaScript Integration. Keep icu4j-71.1.jar.

  • If you installed CIB seven into WildFly or JBoss EAP manually or maintain your own module.xml files, replace the GraalJS modules with the modules listed in GraalVM JavaScript Integration, and take the module org/cibseven/bpm/cibseven-engine from the 3.0 distribution. Its module.xml depends on the new module org.graalvm.js.js-language.

  • To suppress the warnings on Java 25, start the JVM with --enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow, for example in JAVA_OPTS. Java 17 and 21 do not know the option --sun-misc-unsafe-memory-access and do not start with it.

  • Check the Java code that reads numbers which JavaScript scripts set, as described in Number types in JavaScript scripts, and the monitoring rules, alerts and tests that look for PolyglotException in incident messages, as described in Script error messages.

Number types in JavaScript scripts

In 2.2, an integer in the int range that comes from Java as a long was stored by the script in a variable as Integer. Such a number comes, for example, from a variable of type Long, from java.lang.Long.valueOf(7) or from the count() of a query. GraalJS 25 would store it as Long. By default, CIB seven 3.0 stores such a number in a variable as Integer, as in 2.2. One difference: the result of arithmetic with such a number is now Double.

Script 2.2 3.0 (default) 3.0 with none
execution.setVariable('x', execution.getVariable('lng')), where lng is Long 5 Integer 5 Integer 5 Long 5
execution.setVariable('x', query.count()) Integer Integer Long
execution.setVariable('x', execution.getVariable('lng') + 1) Integer 6 Double 6.0 Double 6.0

What you may notice after the update:

  • A Java delegate that casts a variable to Integer ((Integer) execution.getVariable("x")) fails with ClassCastException if a script stored the result of arithmetic with such a number in it (lng + 1).
  • The expression Amount ${x} in a task name or in a form shows Amount 6.0 instead of Amount 6.
  • The REST API and Cockpit show the type Double (with none also Long) for such a variable instead of Integer.

To make the type independent of the version:

  • In a script, set the type explicitly, for example for a number n: execution.setVariable('x', java.lang.Integer.valueOf(n + 1)) or Variables.integerValue(n + 1) after var Variables = Java.type('org.cibseven.bpm.engine.variable.Variables');;
  • In Java, read the number through Number: ((Number) execution.getVariable("x")).intValue().

The property javaScriptNumberNarrowing

This behavior is set by the process engine property javaScriptNumberNarrowing: long (default) gives Integer, as described above; none gives the GraalJS 25 types, Long and Double. In CIB seven Run and in Spring Boot:

camunda.bpm.generic-properties.properties:
  javaScriptNumberNarrowing: none

In bpm-platform.xml and processes.xml: <property name="javaScriptNumberNarrowing">none</property>.

The property has no effect if configureScriptEngineHostAccess is switched off or if the application creates the GraalJS engine itself (its own ScriptEngineResolver). If the process engine cannot apply the property, every JavaScript script fails with the error ENGINE-21006, which names the cause; then set none.

Script error messages

The beginning of the message is the same: Unable to evaluate script while executing activity '…' in the process definition with id '…':. What changes is what follows the colon:

Script 2.2 3.0
throw new Error('x') org.graalvm.polyglot.PolyglotException: Error: x Error: Error: x
notDefined + 1 org.graalvm.polyglot.PolyglotException: ReferenceError: notDefined is not defined ReferenceError: notDefined is not defined in <eval> at line number 1 at column number …

Monitoring rules, alerts and tests that look for PolyglotException in incident messages need to be corrected.

Spring Boot 4 and Spring Framework 7 are required

The Spring Boot starters (cibseven-bpm-spring-boot-starter*), CIB seven Run (cibseven-bpm-run*) and the Spring integration (cibseven-engine-spring) now use Spring Boot 4.1 and Spring Framework 7. Spring Boot 3 and Spring Framework 6 are no longer supported.

User impact

  • In CIB seven 2.2, the artifacts without suffix used Spring Boot 3 and Spring Framework 6. The variants for Spring Boot 4 and Spring Framework 7 had their own names: the starters with the suffix -4 (for example cibseven-bpm-spring-boot-starter-4), cibseven-bpm-run4* and cibseven-engine-spring-7.
  • In CIB seven 3.0, the artifacts without suffix use Spring Boot 4.1 and Spring Framework 7. The former -4, run4 and -7 artifacts still exist as relocation POMs that point to the artifacts without suffix. Builds that use them keep working, and Maven prints a relocation warning.

Migration steps

  • If your application still runs on Spring Boot 3, update it to Spring Boot 4.1 first. Follow the migration guides of Spring Boot 4.0 and Spring Framework 7.0.
  • Replace the artifact IDs with the suffix -4, run4 or -7 with the artifact IDs without suffix, for example cibseven-bpm-spring-boot-starter-4 with cibseven-bpm-spring-boot-starter.

Quarkus 3.33 extension update

The CIB seven engine Quarkus Extension has been updated from Quarkus 3.27 to Quarkus 3.33.3, the current LTS. For what the Quarkus release itself brings, check the Quarkus 3.33 LTS release blog post.

User impact

This change affects applications that use the Quarkus Extension. They have to run on the same Quarkus version. The update also fixes a job executor problem of 2.2: a CDI bean with @ConfigProperty that was created while a job ran failed with SRCFG00015: No configuration is available for this class loader, and the job ended in an incident.

Migration steps

Set the Quarkus version of your application to 3.33.x, for example the property quarkus.platform.version in your pom.xml. See Quarkus Version Compatibility.

Java EE variants and Tomcat 9, WildFly 26 and WildFly 28 distributions removed

CIB seven 2.2 still built several modules in two variants: one for Java EE (javax.*) without suffix, and one for Jakarta EE with the suffix -jakarta. CIB seven 3.0 is built for Jakarta EE only, so each of these modules exists only once, under the name without suffix. The distributions for the Java EE servers Apache Tomcat 9 and WildFly 26, and the distribution for WildFly 28, were removed.

User impact

The following artifacts no longer exist. There are no relocation POMs, so a build that still uses them fails because the artifact cannot be resolved:

Removed artifact Use instead
cibseven-engine-cdi-jakarta cibseven-engine-cdi
cibseven-engine-rest-core-jakarta cibseven-engine-rest-core
cibseven-engine-rest-jakarta cibseven-engine-rest
cibseven-webapp-jakarta cibseven-webapp
cibseven-webapp-tomcat-jakarta cibseven-webapp-tomcat
cibseven-ejb-client-jakarta cibseven-ejb-client
cibseven-spin-dataformat-xml-dom-jakarta cibseven-spin-dataformat-xml-dom

Migration steps

  • Replace the artifact IDs in the table with the names without suffix. The group IDs stay the same.
  • If you run CIB seven on Tomcat 9, WildFly 26 or WildFly 28, move to a supported server first, for example Tomcat 11 or WildFly 42. See Supported Environments.

JUnit 4 and JUnit 3 test support removed

CIB seven 3.0 supports process and decision tests with JUnit 5 (JUnit Jupiter) only.

User impact

  • org.cibseven.bpm.engine.test.ProcessEngineRule is no longer a JUnit 4 rule. It is a JUnit 5 extension now (BeforeEachCallback, AfterEachCallback). A JUnit 4 test with @Rule public ProcessEngineRule ... no longer works.
  • org.cibseven.bpm.dmn.engine.test.DmnEngineRule is no longer a JUnit 4 rule either. It creates the DMN engine in its constructor and provides it through getDmnEngine().
  • org.cibseven.bpm.engine.test.ProcessEngineTestCase no longer extends the JUnit 3 class junit.framework.TestCase.
  • The Spring Boot test starter (cibseven-bpm-spring-boot-starter-test) no longer brings junit-vintage-engine. JUnit 4 tests in your Spring Boot project therefore no longer run, unless you add the Vintage engine yourself, and even then the CIB seven test helpers above do not work in them.

Migration steps

  • Write your process tests with JUnit 5. Use the ProcessEngineExtension from org.cibseven.bpm:cibseven-bpm-junit5 (org.cibseven.bpm.engine.test.junit5.ProcessEngineExtension), either with @ExtendWith(ProcessEngineExtension.class) or as a field with @RegisterExtension.

  • If you want to keep using ProcessEngineRule, register it as a JUnit 5 extension: @RegisterExtension public ProcessEngineRule processEngineRule = new ProcessEngineRule();.

  • Replace @Rule DmnEngineRule with a plain field, DmnEngineRule dmnEngineRule = new DmnEngineRule();, and use dmnEngineRule.getDmnEngine().

  • Subclasses of ProcessEngineTestCase keep working as JUnit 5 test classes, but only if they are adapted:

    • Annotate every test method with @Test (org.junit.jupiter.api.Test). JUnit 3-style test*() methods without @Test are no longer discovered and do not run.
    • Replace overrides of the JUnit 3 methods setUp() and tearDown(), and calls of super.setUp(), super.tearDown() and getName(), with your own @BeforeEach / @AfterEach methods. They run after the process engine setup and before the process engine teardown. Use a TestInfo parameter instead of getName(). With @Override, such an override no longer compiles; without @Override, it compiles but does not run, because it is not annotated.
    • setUpProcessEngineTestCase and tearDownProcessEngineTestCase are new in 3.0. If you override them, annotate the override with @BeforeEach / @AfterEach and call super.

    Alternatively, register it as an extension: @RegisterExtension ProcessEngineTestCase extension = new ProcessEngineTestCase();, and get the services through its getters.

  • Tests whose @RequiredHistoryLevel or @RequiredDatabase does not match the current configuration are reported as skipped.

Jakarta EE 11

CIB seven 3.0 is built against the Jakarta EE 11 APIs: Jakarta Expression Language 6.0, Jakarta Servlet 6.1 and Jakarta Contexts and Dependency Injection (CDI) 4.1. The pre-packaged Tomcat 11 and WildFly distributions already provide these APIs.

CIB seven only uses APIs that are also present in Jakarta EE 10. The released modules therefore remain compatible with Jakarta EE 10 servers at the API level. Apache Tomcat 10.1 is covered by the integration tests of the web applications. JBoss EAP 8.1 is not yet tested in the continuous integration.

Migration steps

No action is required for the pre-packaged distributions.

If your build imports the Jakarta EE BOM (jakarta.platform:jakarta.jakartaee-bom) or depends on jakarta.platform:jakarta.jakartaee-api next to CIB seven, use version 11.0.0 to compile against the same API level as CIB seven.

Note that jakarta.platform:jakarta.jakartaee-api:11.0.0 no longer contains the API classes itself. It only depends on the individual API artifacts. If your build excludes one of them, for example jakarta.ws.rs:jakarta.ws.rs-api, declare that API explicitly.

Jakarta Expression Language 6.0

The process engine, the DMN engine and the JUEL implementation are now compiled against Jakarta Expression Language (EL) 6.0.

User impact

  • The expressions in your BPMN, CMMN and DMN models do not change. The process engine evaluates them with the JUEL implementation that is part of CIB seven (org.cibseven.bpm.impl.juel). The DMN engine uses the same implementation for expressions in the language juel. The supported syntax stays the same.
  • Method calls in expressions behave as in 2.2 on every runtime: with an embedded process engine, on Tomcat, WildFly and JBoss EAP, in CIB seven Run and in Spring Boot. In 2.2, cibseven-juel contained its own copy of the EL 4.0 API. In 3.0, the EL API comes from the runtime. CIB seven therefore selects and invokes the methods itself, with the rules of the EL API that 2.2 used (org.cibseven.bpm.impl.juel.JuelBeanELResolver), and JUEL converts the arguments. Overloaded and varargs methods are selected as in 2.2, an array passed to a varargs parameter is passed as it is, and null passed to a Long, Boolean or BigDecimal parameter becomes 0, false or 0.
  • Two kinds of method calls failed with a NullPointerException in 2.2. In 3.0, null as the only argument of a varargs parameter becomes an array with the converted null, for example [""] for String... and [0] for Long.... A method that cannot be accessed, for example a method of a non-public class that no public interface or superclass declares, fails with a MethodNotFoundException.
  • cibseven-engine-dmn and cibseven-engine-feel-juel, and with them the process engine, now bring the EL API jakarta.el:jakarta.el-api 6.0.1 as a compile dependency. In 2.2, they brought no EL API, because cibseven-juel contained its own copy of the EL 4.0 API. The EL 6.0 API requires Java 17.
  • If you embed the process engine and provide your own EL API or EL implementation, use EL 6.0 to compile against CIB seven, for example jakarta.el:jakarta.el-api 6.0.x with org.glassfish.expressly:expressly 6.0.x. Tomcat 11 and WildFly ship EL 6.0.
  • Runtimes with EL 5.0 (Jakarta EE 10) continue to work. EL 4.0 (Jakarta EE 9) is not supported.
  • On WildFly and JBoss EAP, CIB seven uses the EL API of the server. The CIB seven modules do not bring their own EL implementation; the server provides one: Expressly 6.0 on WildFly, Expressly 5.0 on JBoss EAP 8.1. Do not add another EL implementation to the server modules, because it would replace the server’s implementation for all applications, including Jakarta Faces, Bean Validation and CDI.
  • Outside a container, CIB seven now brings an EL implementation: cibseven-engine-dmn, and with it the process engine, has a runtime dependency on Expressly 6.0 (org.glassfish.expressly:expressly 6.0.0, the reference implementation of EL 6.0). This affects an embedded process engine, a Spring Boot application without a web server, a standalone DMN engine and your unit tests. In 2.2, CIB seven used org.glassfish:jakarta.el 4.0.2 for its own tests only. Method calls in the expressions of your models, also those that convert arguments such as ${dateTime().plusDays(1)}, do not depend on Expressly: JUEL converts the arguments. Expressly is the EL implementation that jakarta.el.ExpressionFactory.newInstance() finds, for example when a plain jakarta.el.BeanELResolver checks whether an argument can be converted (see below). The Tomcat and WildFly distributions do not ship Expressly; there, the server provides the EL API and implementation. CIB seven Run contains Expressly 5.0 (5.0.0) instead of 6.0: spring-boot-starter-jersey brings it through jersey-bean-validation, and Maven prefers it because it is nearer in the dependency tree. Spring Boot applications with cibseven-bpm-spring-boot-starter-rest usually get Expressly 5.0 the same way.
  • org.cibseven.bpm.impl.juel.ExpressionFactoryImpl#coerceToType now has the generic signature of jakarta.el.ExpressionFactory: <T> T coerceToType(Object obj, Class<T> targetType) instead of Object coerceToType(Object obj, Class<?> targetType). A subclass that overrides the old signature no longer compiles (name clash). Subclasses that are already compiled keep working, because the erased signature is the same.
  • In 2.2, the process engine used the copy of the EL 4.0 API in cibseven-juel, in the package org.cibseven.bpm.impl.juel.jakarta.el. In 3.0, this package no longer exists, and the process engine uses jakarta.el. This affects your own implementations of the EL API, for example an ELResolver, an ELContext, a TypeConverter, an ExpressionFactory or a ValueExpression, and your own expression manager. They must import jakarta.el and use the signatures of EL 6.0. The generic signatures of convertToType, coerceToType and getValue, and the removal of MethodExpression#isParmetersProvided, came with EL 5.0. The changes listed in ELResolver#getFeatureDescriptors removed came with EL 6.0.
  • If your own expression manager builds its resolver chain with a plain jakarta.el.BeanELResolver, or your process application returns one from getBeanElResolver(), the EL API of the runtime selects the methods with its own rules. Tomcat’s EL API, for example, rejects some overloaded and varargs calls with Unable to find unambiguous method and wraps an array passed to a varargs parameter into a new array. Outside a container, such a resolver needs an EL implementation on the class path to check whether an argument can be converted.
  • As in 2.2, when the arguments of the selected method are converted, the resolvers in the resolver chain that implement ELResolver#convertToType come first, then JUEL. These resolvers do not take part in the selection of the method.

Migration steps

  • If a subclass of ExpressionFactoryImpl overrides coerceToType, change the method to public <T> T coerceToType(Object obj, Class<T> targetType).
  • Replace the imports of org.cibseven.bpm.impl.juel.jakarta.el with jakarta.el and adapt your EL classes to the signatures of EL 6.0. This includes process applications that override getElResolver(), getBeanElResolver() or initProcessApplicationElResolver().
  • If your own expression manager or process application creates a jakarta.el.BeanELResolver, create an org.cibseven.bpm.impl.juel.JuelBeanELResolver instead, as the expression managers of CIB seven do. Method calls then behave as in 2.2. Like JuelExpressionManager, this class is in an implementation package and not part of the public API.
  • If you package the process engine into a WAR or EAR for Tomcat, WildFly or JBoss EAP, exclude org.glassfish.expressly:expressly from the CIB seven dependencies that bring it, for example cibseven-engine. The server provides the EL implementation. A bundled Expressly would otherwise become the EL implementation of your application, for example for JSP and Bean Validation messages.
  • Outside a container, you can replace Expressly with another EL 5.0 or 6.0 implementation: exclude Expressly and add the other implementation. Keep one EL implementation on the class path. Without one, jakarta.el.ExpressionFactory.newInstance() fails. This affects your own code that uses it, and a plain jakarta.el.BeanELResolver in your own resolver chain when a method call needs an argument conversion.

ELResolver#getFeatureDescriptors removed

EL 6.0 removed the method jakarta.el.ELResolver#getFeatureDescriptors together with its dependency on java.beans.FeatureDescriptor. It also removed the constants ELResolver.TYPE and ELResolver.RESOLVABLE_AT_DESIGN_TIME, which only implementations of this method used. CIB seven removed its implementations of this method from the following classes:

  • org.cibseven.bpm.engine.impl.el.AbstractElResolverDelegate
  • org.cibseven.bpm.engine.impl.el.ReadOnlyMapELResolver
  • org.cibseven.bpm.engine.impl.el.VariableContextElResolver
  • org.cibseven.bpm.engine.impl.el.VariableScopeElResolver
  • org.cibseven.bpm.engine.test.mock.MockElResolver
  • org.cibseven.bpm.dmn.engine.impl.el.VariableContextElResolver
  • org.cibseven.bpm.impl.juel.RootPropertyResolver
  • org.cibseven.bpm.impl.juel.SimpleResolver

User impact

Custom code no longer compiles in the following cases, in a subclass of one of these classes or of jakarta.el.ELResolver:

  • it overrides getFeatureDescriptors with @Override;
  • it calls super.getFeatureDescriptors(...);
  • it uses ELResolver.TYPE or ELResolver.RESOLVABLE_AT_DESIGN_TIME.

Typical cases are a custom ExpressionManager with its own resolvers, an ELResolver that restricts what expressions may access, an ELResolver that makes the beans of another framework available in expressions, and test mocks.

Resolvers compiled against CIB seven 2.2 reference the package org.cibseven.bpm.impl.juel.jakarta.el, which no longer exists in 3.0 (see Jakarta Expression Language 6.0). They fail to load and must be recompiled against jakarta.el. The compiler then reports every place that needs a change.

Migration steps

Remove the getFeatureDescriptors method, the references to ELResolver.TYPE and ELResolver.RESOLVABLE_AT_DESIGN_TIME, and the imports of java.beans.FeatureDescriptor from your resolvers. The process engine never called this method, so removing it does not change the behavior of expressions.

Jakarta RESTful Web Services 4.0

The REST API (cibseven-engine-rest-core) is compiled and tested against Jakarta RESTful Web Services (JAX-RS) 4.0. The JAX-RS implementations that CIB seven ships are now:

  • the web applications Cockpit, Tasklist and Admin of the pre-packaged Tomcat distribution (cibseven-webapp-tomcat): RESTEasy 7.0 instead of 6.2, the same JAX-RS implementation as WildFly,
  • the REST API web application (cibseven-engine-rest, deployed as engine-rest in the pre-packaged Tomcat distribution): it continues to run on RESTEasy, now RESTEasy 7.0 instead of 6.2, the same version as the Tomcat web applications and WildFly. A web.xml that you customized for the Jakarta variant of 2.2 (cibseven-engine-rest-jakarta, Tomcat 10) keeps working. A web.xml from the Java EE variant of 2.2 (Tomcat 9) needs the context parameter jakarta.ws.rs.Application instead of javax.ws.rs.Application. The war no longer contains angus-activation: the pre-packaged Tomcat distribution provides it in lib/, next to the Jakarta Activation API (see Jakarta Activation and MIME types of file variables),
  • the Spring Boot starter and CIB seven Run: Jersey 4.0, which comes with Spring Boot 4.

User impact

  • If you deploy the REST API in your own application and bundle a JAX-RS implementation, use a JAX-RS 4.0 implementation, for example Jersey 4.0 or RESTEasy 7.0.

  • JAX-RS 3.1 runtimes (Jakarta EE 10), for example RESTEasy 6.2 in JBoss EAP 8.1, remain compatible. CIB seven runs the unit tests of the REST API, with a mocked process engine, on such a runtime as well.

  • If you use the Spring Boot starter without suffix of CIB seven 2.2 (Spring Boot 3, Jersey 3.1) and have your own Jersey code, the update to Spring Boot 4 brings Jersey 4.0. Jersey 4.0 introduces the following changes, among others:

    • AbstractBinder moved from org.glassfish.jersey.internal.inject (jersey-common) to org.glassfish.jersey.inject.hk2 (jersey-hk2);
    • jersey-container-servlet-core is no longer released and is part of jersey-container-servlet;
    • jersey-apache-connector is replaced by jersey-apache5-connector.

    Users of the -4 starters of 2.2 already run on Jersey 4.0.

  • JAX-RS 4.0 removed the classes Link.JaxbLink and Link.JaxbAdapter and the support for @ManagedBean. This affects your own JAX-RS resources and providers, for example in Cockpit or Tasklist plugins or next to the REST API.

  • RESTEasy 7 removed the embedded server adapters resteasy-netty4, resteasy-netty4-cdi, resteasy-vertx and resteasy-reactor-netty. This affects you if you run the REST API on one of these adapters.

Migration steps

  • Replace Link.JaxbLink and Link.JaxbAdapter with your own JAXB types.
  • Replace @ManagedBean on JAX-RS resources and providers with a CDI scope annotation, for example @RequestScoped or @ApplicationScoped.
  • If you run the REST API in an embedded RESTEasy server with Netty, Vert.x or Reactor Netty, switch to resteasy-undertow or resteasy-jdk-http.
  • If your Spring Boot application has its own Jersey code, follow the Jersey migration guide from 3.x to 4.0.

Jakarta Activation and MIME types of file variables

Variables.fileValue(File) sets the MIME type of a file variable from the file name. In 2.2, cibseven-commons-typed-values contained a relocated copy of the JavaBeans Activation Framework 1.2 for this. In 3.0, it uses jakarta.activation.MimetypesFileTypeMap from Jakarta Activation 2.1. This API has no implementation of its own: without one, every file gets the MIME type application/octet-stream.

User impact

  • cibseven-commons-typed-values brings Eclipse Angus Activation (org.eclipse.angus:angus-activation) as a runtime dependency. An embedded process engine and the External Task Client therefore detect the same MIME types as in 2.2, for example text/plain for .txt and image/png for .png. File types that 2.2 did not know either, for example .pdf, .json or Office files, stay application/octet-stream.
  • The pre-packaged Tomcat distribution has two new jars in lib/: the Jakarta Activation API (jakarta.activation-api) and Angus (angus-activation).
  • On WildFly and JBoss EAP, the modules org.cibseven.commons.cibseven-commons-typed-values and org.cibseven.bpm.cibseven-engine depend on the server module org.eclipse.angus.activation, with services="import".

Migration steps

  • If your application embeds the process engine or uses the External Task Client and excludes transitive dependencies of CIB seven, keep org.eclipse.angus:angus-activation, or provide another Jakarta Activation 2.1 implementation.
  • If you installed CIB seven into Tomcat manually, also copy jakarta.activation-api and angus-activation from $TOMCAT_DISTRIBUTION/lib/ to $TOMCAT_HOME/lib/.
  • If the process engine runs as a shared engine in Tomcat (the pre-packaged distribution or a manual installation), do not package the Activation API or Angus into your web applications. If a library brings them, for example org.glassfish.jaxb:jaxb-runtime, exclude jakarta.activation:jakarta.activation-api and org.eclipse.angus:angus-activation. If WEB-INF/lib contains Angus and the Activation API, the MIME type detection of the shared process engine fails in calls from this web application, and every file gets application/octet-stream.
  • If you installed CIB seven into WildFly or JBoss EAP manually or maintain your own module.xml files, take the modules cibseven-commons-typed-values and cibseven-engine from the 3.0 distribution, or add <module name="org.eclipse.angus.activation" services="import" /> to the dependencies of both modules.
  • To store another MIME type, for example application/pdf, set it explicitly: Variables.fileValue(name).file(file).mimeType("application/pdf").create().

Spin and annotations in the Tomcat distribution and CIB seven Run

As in CIB seven 2.x, cibseven-spin-dataformat-all, which the Tomcat distribution and CIB seven Run use, contains Jackson, JSON Path and Jakarta XML Binding relocated to the spinjar package. Spin therefore ignores Jackson annotations and jakarta.xml.bind.annotation.* annotations (for example @XmlRootElement, @XmlElement) in your classes when it serializes or deserializes variables. The behavior is the same as in 2.x, and existing variables stay readable.

If you need annotation support, use cibseven-spin-core with cibseven-spin-dataformat-json-jackson and cibseven-spin-dataformat-xml-dom instead. This is the default on WildFly and recommended for Spring Boot and embedded process engines. See Configuring Spin Integration.

Jackson 3

CIB seven 3.0 reads and writes JSON with Jackson 3 (packages tools.jackson.*) instead of Jackson 2 (com.fasterxml.jackson.*):

  • Spin JSON, which stores object variables in the format application/json: cibseven-spin-dataformat-json-jackson and its shaded variant cibseven-spin-dataformat-all,
  • the Java External Task Client (cibseven-external-task-client),
  • the REST API (cibseven-engine-rest-core, cibseven-engine-rest), the Spring Boot starters and the web application archives of the Tomcat and WildFly distributions.

Jackson 3 keeps the annotations of com.fasterxml.jackson.annotation, for example @JsonProperty, @JsonIgnore, @JsonFormat and @JsonTypeInfo. Its own databind annotations moved to tools.jackson.databind.annotation. The default mappers of Spin and of the External Task Client use the Jackson 2 defaults of Jackson 3 and the nesting depth limit of Jackson 2, so variables written by CIB seven 2.x are usually read and written unchanged. The exceptions are listed below.

The deprecated artifacts cibseven-spin-dataformat-json-jackson2, cibseven-spin-dataformat-all-jackson2 and cibseven-external-task-client-jackson2 contain the Jackson 2 code of CIB seven 2.x, with the same packages and class names. They are a way out for applications that cannot move to Jackson 3 yet, and they will be removed in CIB seven 3.1.0. Never put a -jackson2 artifact and its counterpart without suffix on one class path.

User impact

  • Jackson types in the public API. These methods now use the Jackson 3 types tools.jackson.databind.ObjectMapper, JsonMapper and JavaType:
    • Spin: the constructor JacksonJsonDataFormat(String, ObjectMapper), getObjectMapper(), setObjectMapper(ObjectMapper) and constructJavaTypeFromCanonicalString(String) of org.cibseven.spin.impl.json.jackson.format.JacksonJsonDataFormat;
    • External Task Client: getObjectMapper() and setObjectMapper(ObjectMapper) of its JacksonJsonDataFormat, ExternalTaskClientBuilderImpl#getObjectMapper() and OAuth2ClientCredentialsProvider.Builder#objectMapper(ObjectMapper);
    • REST API: the constructors of the query DTOs, resources and converters, and ContextResolver<ObjectMapper> for REST extensions. JacksonConfigurator.configureObjectMapper(ObjectMapper) is replaced by configureObjectMapper(), which returns the configured JsonMapper. Applications that register com.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvider must register org.cibseven.bpm.engine.rest.mapper.CibsevenJacksonJsonProvider instead.
  • CIB seven no longer brings Jackson 2.
    • The Spring Boot starters no longer bring jackson-databind 2, spring-boot-jackson2 and jersey-media-json-jackson. Unless your application brings spring-boot-jackson2 itself, there is no Jackson 2 ObjectMapper bean. JAX-RS resources that your application registers in the Jersey configuration of the REST starter are read and written with Jackson 3 and the settings of the REST API.
    • The core of CIB seven Run contains no Jackson 2.
    • The REST API and web application archives of the Tomcat and WildFly distributions bundle Jackson 3. JAX-RS extensions registered in them no longer see the Jackson 2 modules of the server.
  • Variable classes. Where Spin or the External Task Client see the Jackson annotations of your classes, some classes are written or read differently (see the migration steps below). This applies to Spring Boot applications with the starter, to embedded process engines, to the External Task Client 3.0 and to process applications on WildFly whose jboss-deployment-structure.xml lets Spin see the Jackson annotations of their classes. As in 2.x, Spin in CIB seven Run and in the Tomcat distribution (cibseven-spin-dataformat-all) does not see the Jackson annotations of your classes.
  • Reading writes back. When the process engine reads an object variable, it writes the variable back at the end of the command if Spin serializes the value to a different text. This was the same in 2.x. A plain GET .../variables of the REST API or opening the variables of a process instance in the web client is enough. So the first read after the update stores the new form of a changed value, and a later downgrade to 2.2 does not bring the old value back.

Migration steps

Before the update

  • Back up the database.
  • Search your variable classes for the cases below: annotations from com.fasterxml.jackson.databind.annotation, @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS) or Id.MINIMAL_CLASS on properties of type Object, and @JsonInclude(content = ...) on classes.
  • In a rolling update, update all nodes before variables of affected classes are read. Nodes of 2.2 and 3.0 on one database rewrite such a variable each time one of them reads a value the other version wrote, with a new revision and a new history entry each time. Nodes of 2.2 cannot read some values that 3.0 wrote, for example of classes with @JsonNaming or with java.time properties.

Spring Boot applications

  • Import cibseven-bom before spring-boot-dependencies. Spin JSON on Jackson 3 needs com.jayway.jsonpath:json-path 3.0.0 or later, while Spring Boot 4.1 manages json-path 2.10.0. If spring-boot-dependencies comes first, the application does not start and the log names SPIN/JACKSON-JSON-01018. If your project inherits from spring-boot-starter-parent, set the property json-path.version to 3.0.0 instead.

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>org.cibseven.bpm</groupId>
          <artifactId>cibseven-bom</artifactId>
          <version>3.0.0</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
        <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-dependencies</artifactId>
          <version>${spring-boot.version}</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>
    
  • If your application injects a Jackson 2 com.fasterxml.jackson.databind.ObjectMapper, add org.springframework.boot:spring-boot-jackson2 to its dependencies.

Data format configurators

A DataFormatConfigurator of Spin (org.cibseven.spin.spi.DataFormatConfigurator) or of the External Task Client (org.cibseven.bpm.client.spi.DataFormatConfigurator) that is compiled against CIB seven 2.x fails with NoSuchMethodError on JacksonJsonDataFormat.getObjectMapper(). Compile it against Jackson 3. Jackson 3 mappers are immutable: build a new mapper from the current one and set it.

public class AcmeJsonConfigurator implements DataFormatConfigurator<JacksonJsonDataFormat> {

  @Override
  public Class<JacksonJsonDataFormat> getDataFormatClass() {
    return JacksonJsonDataFormat.class;
  }

  @Override
  public void configure(JacksonJsonDataFormat dataFormat) {
    dataFormat.setObjectMapper(dataFormat.getObjectMapper().rebuild()
        .addModule(new AcmeModule())
        .build());
  }
}

Start from getObjectMapper().rebuild(), not from a new JsonMapper: the default mapper carries the settings that keep the JSON of 2.x. You no longer need JavaTimeModule or Jdk8Module: Jackson 3 supports java.time and Optional itself.

CIB seven Run: Jackson 2 for your own libraries

Delegates, listeners and plugins in configuration/userlib that use Jackson 2 (com.fasterxml.jackson.databind) fail with NoClassDefFoundError: com/fasterxml/jackson/databind/ObjectMapper when they first run under --production --rest. In the other modes they only work because the web applications (internal/webapps) and the AI agent connector (configuration/userlib-ai) happen to bring Jackson 2. Put jackson-databind and jackson-core 2.21, and the Jackson 2 modules your code uses, for example jackson-datatype-jsr310, into configuration/userlib. jackson-annotations 2.21 is already part of CIB seven Run.

WildFly and JBoss EAP: Jackson modules in jboss-deployment-structure.xml

In 2.2, the Jackson modules of CIB seven on WildFly also had the slot of their Jackson version, for example 2.21.7. In 3.0, their slot is cibseven: the Jackson 2 modules com.fasterxml.jackson.core.jackson-* and the Jackson 3 modules tools.jackson.core.jackson-core and tools.jackson.core.jackson-databind. A process application whose jboss-deployment-structure.xml names one of these modules with the old slot does not deploy (WFLYSRV0179: Failed to load module). Change the slot:

<module name="com.fasterxml.jackson.core.jackson-databind" slot="cibseven" />

If your application uses these modules so that Spin sees the Jackson annotations of its classes, the following sections apply to it as well.

Annotations of jackson-databind 2 on variable classes

Jackson 3 reads its databind annotations only from tools.jackson.databind.annotation. Spin and the External Task Client ignore the annotations of jackson-databind 2 (com.fasterxml.jackson.databind.annotation.*) on the classes of your object variables, without a message:

Annotation on a variable class CIB seven 2.2 CIB seven 3.0
@JsonNaming(SnakeCaseStrategy.class) writes and reads first_name writes firstName; JSON written by 2.2 cannot be read
@JsonSerialize(using = ToStringSerializer.class) on a Long writes "9007199254740993" writes the number 9007199254740993, which JavaScript clients read as 9007199254740992
@JsonSerialize(as = ...) with an interface writes the properties of the interface writes all properties of the class, also those that the interface hides
Your own @JsonSerialize(using = ...) and @JsonDeserialize(using = ...) uses your serializer and deserializer writes the bean; JSON written by 2.2 cannot be read
@EnumNaming(EnumNamingStrategies.LowerCamelCaseStrategy.class) writes phoneCall writes PHONE_CALL; JSON written by 2.2 cannot be read
@JsonDeserialize(as = ...) or contentAs reads cannot read any JSON (InvalidDefinitionException)
@JsonDeserialize(builder = ...) with @JsonPOJOBuilder, also Lombok @Jacksonized reads cannot read any JSON (InvalidDefinitionException)
@JsonTypeInfo(use = Id.CUSTOM) with @JsonTypeIdResolver writes and reads cannot write (IllegalStateException)

In a Spring Boot application with the REST starter, the REST API writes object values that you request with deserializeValues=true with Jackson 3 as well, so these annotations are ignored in its responses too.

Choose one of the following ways:

  • Both annotations side by side. Put the annotation of tools.jackson.databind.annotation next to the one of com.fasterxml.jackson.databind.annotation on the same element. The class then writes and reads the JSON of 2.2 on 2.2 and on 3.0, also in an external task worker of 2.x without Jackson 3 on its class path. Your own serializers, deserializers and type id resolvers then exist twice, for the Jackson 2 API and for the Jackson 3 API. Use this for classes that 2.x and 3.0 share, for example in a library of your workers or during a rolling update.

  • Jackson 3 annotations only. Replace the annotations with those of tools.jackson.databind.annotation once nothing on 2.x reads these variables any more.

  • Lombok. Up to Lombok 1.18.42, @Jacksonized generates the annotations of Jackson 2 only. From Lombok 1.18.44, add the following lines to lombok.config to generate both:

    lombok.jacksonized.jacksonVersion += 2
    lombok.jacksonized.jacksonVersion += 3
    
  • The -jackson2 artifacts. Until CIB seven 3.1.0, Spring Boot applications, embedded process engines and external task workers can keep the JSON of 2.2 with the deprecated -jackson2 artifacts.

Class ids on properties of type Object

@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS) or Id.MINIMAL_CLASS on a property of a general type, such as Object, Serializable, Comparable, List<Object> or Map<String, Object>, lets the JSON decide which class Jackson creates. Jackson 3 refuses this by default to protect against the deserialization of arbitrary classes, and CIB seven 3.0 keeps that. Spin and the External Task Client still write such a variable with "@class", but they no longer read it, neither new values nor values written by 2.2. The read fails for the whole class, also if the property is null, and the error names PolymorphicTypeValidator. Id.NAME with @JsonSubTypes, and class ids on properties whose type is one of your own classes or interfaces, keep working.

To keep reading such variables, allow the packages of the classes that can occur in these properties with a PolymorphicTypeValidator. Allow only your own packages, never all classes:

public class AcmeClassIdConfigurator implements DataFormatConfigurator<JacksonJsonDataFormat> {

  @Override
  public Class<JacksonJsonDataFormat> getDataFormatClass() {
    return JacksonJsonDataFormat.class;
  }

  @Override
  public void configure(JacksonJsonDataFormat dataFormat) {
    dataFormat.setObjectMapper(dataFormat.getObjectMapper().rebuild()
        .polymorphicTypeValidator(BasicPolymorphicTypeValidator.builder()
            .allowIfSubType("com.acme.")
            .build())
        .build());
  }
}

BasicPolymorphicTypeValidator is in the package tools.jackson.databind.jsontype.

  • For the process engine, implement org.cibseven.spin.spi.DataFormatConfigurator for org.cibseven.spin.impl.json.jackson.format.JacksonJsonDataFormat and register the class in META-INF/services/org.cibseven.spin.spi.DataFormatConfigurator (see Configuring Data Formats).
  • For the External Task Client, implement org.cibseven.bpm.client.spi.DataFormatConfigurator for org.cibseven.bpm.client.variable.impl.format.json.JacksonJsonDataFormat and register the class in META-INF/services/org.cibseven.bpm.client.spi.DataFormatConfigurator of each worker.

@JsonInclude(content = NON_NULL) on a class

On a class, Jackson 3 also applies @JsonInclude(content = JsonInclude.Include.NON_NULL) to the values of its Map properties: entries with the value null are no longer written, so {"a":"x","b":null} is stored as {"a":"x"}. Jackson 2 kept these entries. If they matter, put @JsonInclude(content = JsonInclude.Include.ALWAYS) on the Map property.

Map and Set properties with enum keys

As in 2.x, Spin and the External Task Client read a property declared as Map<SomeEnum, V> as a LinkedHashMap, in the order of the JSON, and a Set<SomeEnum> as a HashSet. To get an EnumMap or EnumSet instead, annotate the property with @JsonDeserialize(as = EnumMap.class) or @JsonDeserialize(as = EnumSet.class) from tools.jackson.databind.annotation. If your data format configurator enables READ_UNKNOWN_ENUM_VALUES_AS_NULL, an unknown key is now dropped from such a map; 2.x read it as a null key.

OSGi package imports

The OSGi bundles of CIB seven now import the Jakarta packages in the ranges of Jakarta EE 11, for example jakarta.el in the range [6.0,7) and jakarta.enterprise.* in the range [4.1,5). All CIB seven bundles declare Java 17 as the required execution environment (osgi.ee JavaSE 17). Provide matching API bundles in your OSGi container.

Software Bill of Materials

CIB seven 3.0 publishes a CycloneDX Software Bill of Materials (SBOM) for the whole project, for each distribution and for each Docker image.

User impact

No user impact is expected, and no migration step is needed. The SBOMs are additional artifacts; nothing in the distributions or the images changes because of them. See Software Bill of Materials.

Permissions for task and process instance attachments

Reading, creating, updating and deleting task and process instance attachments now require a permission on the task or process instance, including the tenant check:

  • Reading an attachment of a task, its content or the attachment list of a task: READ on the task or READ_TASK on the process definition.
  • Reading an attachment of a process instance or the attachment list of a process instance: READ on the process instance or READ_INSTANCE on the process definition. Attachments of tasks the caller may not read are left out of the list.
  • Creating, updating or deleting an attachment of a task: TASK_WORK or UPDATE on the task, or TASK_WORK or UPDATE_TASK on the process definition; of a process instance: UPDATE on the process instance or UPDATE_INSTANCE on the process definition.

Attachments of completed tasks and process instances are checked against the history permissions: reading needs READ_HISTORY on the process definition, or READ on the historic task or historic process instance with enableHistoricInstancePermissions; writing needs DELETE_HISTORY on the process definition or ALL on the historic task or historic process instance. Attachments whose task or process instance no longer exists, not even in the history, can only be read or changed by an administrator. With authorization enabled, an attachment for a task and a process instance is rejected if the task does not belong to that process instance.

Expected impact

With authorization enabled, users without these permissions now get an AuthorizationException, and the REST endpoints for task attachments answer with HTTP 403. The former assignee of a completed process task needs READ_HISTORY on the process definition to keep reading its attachments; enable enableHistoricInstancePermissions if assignees should keep access. Engines without authorization and tenant check are not affected.

The new engine property enforceAttachmentPermissions (default true) can be set to false to restore the previous behavior.

Permissions for task and process instance comments

Creating and reading task and process instance comments, and reading task events, now require a permission on the task or process instance, including the tenant check:

  • Reading the comments or events of a task: READ on the task or READ_TASK on the process definition.
  • Reading the comments of a process instance: READ on the process instance or READ_INSTANCE on the process definition. Task comments the caller may not read are left out.
  • Adding a comment to a task: TASK_WORK or UPDATE on the task, or UPDATE_TASK on the process definition; to a process instance: UPDATE on the process instance or UPDATE_INSTANCE on the process definition.

Comments of completed tasks and process instances are checked against the history permissions: reading needs READ_HISTORY on the process definition, or READ on the historic task or historic process instance with enableHistoricInstancePermissions; adding a comment needs DELETE_HISTORY on the process definition or ALL on the historic task or historic process instance. A comment for a task and a process instance is rejected if the task does not belong to that process instance.

Expected impact

With authorization enabled, users without these permissions now get an AuthorizationException, and the REST endpoint for creating a task comment answers with HTTP 403 instead of 400. As for the task itself, the former assignee of a completed process task needs READ_HISTORY on the process definition to keep reading its comments; enable enableHistoricInstancePermissions if assignees should keep access.

The new engine property enforceCommentPermissions (default true) can be set to false to restore the previous behavior. Updating and deleting comments stay checked either way.

JUEL scripts use the expression manager’s resolver chain

JUEL scripts (scriptFormat="juel" in script tasks, listeners, script conditions and input/output mappings) now resolve names, properties and methods through the configured expression manager, like attribute expressions do. Restrictions of a customized expression manager therefore apply to JUEL scripts as well.

This only applies with a customized expression manager (a subclass of JuelExpressionManager) or a SpringExpressionManager with beans set. With the default expression managers, JUEL scripts behave as before.

Expected impact

In JUEL scripts, with a customized expression manager or a SpringExpressionManager with beans set:

  • restrictions of the expression manager now apply, including to top-level names,
  • names that only the script resolver factories provided (configuration beans, Spring beans, mocks, a custom ResolverFactory) are no longer available,
  • context and lang:import are no longer available,
  • a process variable takes precedence over a bean with the same name,
  • unknown names fail with “Cannot resolve identifier”.

To keep the previous behavior, override isAppliedToJuelScripts() in your expression manager to return false.

Optional endpoint allow-list for connectors

Connector targets such as the HTTP request URL, the AI agent’s base URL or its MCP servers often come from process variables. Operators can now restrict the endpoints that the HTTP, SOAP, AI agent and knowledge ingestor connectors may contact. Without configuration, nothing changes.

Set the allow-list as a JVM system property or an environment variable (it is not read from application.yaml):

  • cibseven.connect.allowed-endpoints / CIBSEVEN_CONNECT_ALLOWED_ENDPOINTS for all connectors,
  • cibseven.connect.<connectorId>.allowed-endpoints / CIBSEVEN_CONNECT_<CONNECTOR_ID>_ALLOWED_ENDPOINTS for one connector, e.g. cibseven.connect.cibseven-ai-agent.allowed-endpoints. A connector’s own list replaces the global one; * exempts the connector.

Entries are separated by commas or whitespace and have the form scheme://host[:port] or scheme://*.domain[:port], without a path, e.g. https://api.openai.com, https://*.example.com or postgresql://db.example.com:5432. Host names are compared without DNS resolution; wildcards need at least two labels and never match IP addresses. Invalid entries are ignored with a warning.

Checked are the HTTP and SOAP request URL and every redirect, the AI agent’s base URL, every MCP server, the pgvector host and the OpenAI embedding endpoint, and the knowledge ingestor’s pgvector host and embedding endpoint. A refused endpoint fails the connector call with a ConnectorEndpointNotAllowedException before anything is sent.

Expected impact

None without configuration. With an allow-list, list every endpoint your processes use, including the pgvector host (postgresql://host:port) and https://api.openai.com for remote embeddings. Redirects are only checked for the HTTP client the connector creates itself, not for a client replaced through a connector configurator.

AI Agent Connector sends the global API key only to the configured endpoint

The AI Agent Connector now sends the API key from the OPENAI_API_KEY environment variable only to the endpoint configured by the operator. This prevents a base URL supplied by a process (for example through a process variable) from receiving the global API key.

The global key is sent when the model does not set a base URL, or when the base URL has the same scheme, host and port as OPENAI_BASE_URL (or as https://api.openai.com/v1 if OPENAI_BASE_URL is not set). An API key defined in the model is used as before, for any endpoint.

Expected impact

Models that set their own base URL and rely on OPENAI_API_KEY from the environment (e.g. OpenRouter) no longer receive that key. The request is sent without an API key and the provider typically rejects it with HTTP 401. The connector logs a warning naming the endpoint (scheme, host and port only).

To keep such models working, do one of the following:

  • Set OPENAI_BASE_URL to the endpoint the models use, or
  • define the API key in the model.

Endpoints that do not need an API key, such as a local Ollama, are not affected.

Remote embedding models (embeddingModelName set, in the AI agent task and the knowledge ingestor) always call https://api.openai.com/v1. They now receive OPENAI_API_KEY only if OPENAI_BASE_URL is not set or points to OpenAI as well, so another provider’s key is no longer sent to OpenAI. In the AI agent task, the API key defined in the model belongs to its base URL: it is only sent to remote embeddings if that base URL is OpenAI as well. With another provider configured, define the API key in the model or leave embeddingModelName empty to use the local embedding model.

For more information, see Configuring the Agent.

Optional allow list for task types and script languages

Operators can now restrict the built-in task types and the script languages that process definitions may use. Without configuration, nothing changes.

Set the process engine property executionAllowList to a comma-separated list of names, e.g. external, groovy. Once it has entries, only the listed task types (shell, mail, external) and script languages are allowed. Names are matched in full and ignore case; entries with a leading - or a * are rejected as a configuration error. Script language aliases (for example js, ecmascript and graal.js) must be listed individually.

  • New deployments that use an unlisted camunda:type on a service task, send task, business rule task, intermediate message throw event or message end event are rejected.
  • Process definitions that are already deployed are blocked when they reach such an activity, and an unlisted script language is blocked when the script is executed, including scripts in process applications and in DMN decisions. JUEL and FEEL in DMN are always allowed.
  • A blocked use fails with ENGINE-25003. The message names the task type or language and the activity, but not the configured list.

The property expressionHardeningMode controls how a violation is handled: enforce (default) blocks it, report only logs a warning ENGINE-25004 and allows it, off disables the check. The same property applies to the deny list for expressions and scripts.

Expected impact

None without configuration. With an allow list, list every task type and script language your processes use. External tasks that were created before the list was restricted can still be fetched and completed.

Deny list for expressions and scripts

Expressions and JUEL scripts are now checked against a deny list. It applies to BPMN and CMMN expressions, JUEL scripts, JUEL expressions in DMN and the legacy JUEL-based FEEL, including EL functions.

By default, the deny list blocks reflection and access to engine internals: class, getClass, java.lang.Class, java.lang.ClassLoader, java.lang.reflect.AccessibleObject, java.lang.invoke.MethodHandle, java.lang.invoke.MethodHandles, lang:import, org.cibseven.bpm.engine.impl.cfg.ProcessEngineConfigurationImpl, java.lang.Runtime and java.lang.ProcessBuilder. In addition, jakarta.el, javax.el and org.cibseven.bpm.impl.juel are always denied while the check is active.

Two process engine properties configure it:

  • deniedExpressionAccess: comma-separated entries that are added to the defaults; -entry removes a default. Entries can be names (getClass), types or packages (java.lang.Runtime), EL functions (lang:import, :name) and members (com.example.Admin#delete); * is a wildcard.
  • expressionHardeningMode: enforce (default) blocks a denied access, report logs a warning ENGINE-25010 and allows it, off disables the deny list.

The configuration is fixed when the process engine is built.

Expected impact

Expressions and JUEL scripts that use reflection or Class objects, JUEL scripts with lang:import and expressions that read the process engine configuration now fail. A newly denied EL function also affects deployed process definitions once the deployment cache is rebuilt.

We recommend to start with expressionHardeningMode=report, check the log for ENGINE-25010 and then switch to enforce. To allow a single default again, remove it, for example deniedExpressionAccess=-lang:import; getClass() needs -class,-getClass,-java.lang.Class. expressionHardeningMode=off restores the previous behavior.

The engine also logs:

  • ENGINE-25011 if the configured expression manager is not a JuelExpressionManager,
  • ENGINE-25012 if a custom expression manager’s own policy overrides the properties,
  • ENGINE-25013 if the expression manager was used before the process engine was built.

On 2.2.5 the deny list is only active if deniedExpressionAccess is set.

On this Page: