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:
- For administrators and developers: Database updates
- For administrators and developers: Webclient database tables are now optional
- For administrators: New database indexes
- For administrators: Stalled “Delete deployments” batches
- For administrators and developers: Java 17 is required
- For administrators and developers: Java 25 and GraalJS 25
- For developers: Spring Boot 4 and Spring Framework 7 are required
- For administrators anddevelopers: Quarkus 3.33 extension update
- For administrators and developers: Java EE variants and Tomcat 9, WildFly 26 and WildFly 28 distributions removed
- For developers: JUnit 4 and JUnit 3 test support removed
- For administrators and developers: Jakarta EE 11
- For developers: Jakarta Expression Language 6.0
- For developers: ELResolver#getFeatureDescriptors removed
- For administrators and developers: Jakarta RESTful Web Services 4.0
- For administrators and developers: Jakarta Activation and MIME types of file variables
- For developers: Spin and annotations in the Tomcat distribution and CIB seven Run
- For administrators and developers: Jackson 3
- For developers: OSGi package imports
- For administrators: Software Bill of Materials
- For administrators: Permissions for task and process instance attachments
- For administrators: Permissions for task and process instance comments
- For administrators and developers: JUEL scripts use the expression manager’s resolver chain
- For administrators: Optional endpoint allow-list for connectors
- For administrators: AI Agent Connector sends the global API key only to the configured endpoint
- For administrators: Optional allow list for task types and script languages
- 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
-jakartano longer exist. Use the artifacts without suffix. - JUnit 4 and JUnit 3 test support removed:
ProcessEngineRule,DmnEngineRuleandProcessEngineTestCaseno 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 overridegetElResolver(),getBeanElResolver()orinitProcessApplicationElResolver()must switch fromorg.cibseven.bpm.impl.juel.jakarta.eltojakarta.eland be recompiled. Resolvers that override or callgetFeatureDescriptorsno 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 typeObjectare 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.elin[6.0,7), and require Java 17. - New database indexes: check for existing indexes on
ACT_HI_JOB_LOG(DEPLOYMENT_ID_)andACT_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).enforceAttachmentPermissionsandenforceCommentPermissionsset tofalserestore 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,
contextandlang:importare 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. SetOPENAI_BASE_URLto that endpoint or define the API key in the model. - Deny list for expressions and scripts: expressions and JUEL scripts that use reflection,
Classobjects,lang:importor the process engine configuration now fail. Start withexpressionHardeningMode=reportto 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.
modelerEnabledis renamed towebclientExtensionsEnabled, and its default changes fromtruetofalse. It now governs the modeler, chat and notification tables together. The pre-packaged distributions set it totruein their shipped configuration, so their behaviour is unchanged. - Create and drop scripts. The webclient tables have moved out of
<database>_engine_<version>.sqlinto<database>_extensions_<version>.sql, alongside the long-standing<database>_identity_<version>.sql. - Update scripts. The
2.2to3.0update is split into<database>_engine_2.2_to_3.0.sqland<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_PROPERTYunderwebclient.extensions.version. The engine reports it through the REST API aswebclientExtensionsVersion, in the response ofGET /configuration, so the webclient can tell whether its tables are present and current. The field isnullwhen 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_DEPLOYMENTonACT_HI_JOB_LOG(DEPLOYMENT_ID_), on all databases. Without it, deleting a deployment with cascade (RepositoryService#deleteDeployment(id, true)or RESTDELETE /deployment/{id}?cascade=true) scans the whole job log table.ACT_IDX_TASK_PARENT_TASK_IDonACT_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:
- Delete the batch with
ManagementService#deleteBatchor RESTDELETE /batch/{id}. Withcascade=true, its history is deleted as well. - 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:jsis 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 fromorg.graalvm.sdk:graal-sdktoorg.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-sdkandjsno longer exist as jars and several artifacts are new, so a partial replacement leaves an incomplete runtime — a chain ofNoClassDefFoundErrorthe first time a script runs, or aModuleLoadErrorwhile 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, thecom.ibm.icuclasses were available to your code and to JavaScript and Groovy scripts. GraalJS 25 uses its own relocated copy (org.graalvm.shadowed:icu4j, packageorg.graalvm.shadowed.com.ibm.icu), which does not providecom.ibm.icu. The Tomcat and WildFly distributions and CIB seven Run still containcom.ibm.icu:icu4j71.1, next to the shaded copy:icu4j-71.1.jarandicu4j-25.0.1.jarinlib/, two modules in WildFly. Both are needed, and neither replaces the other. In your own application, thecom.ibm.icuclasses 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,constand arrow functions fail with aSyntaxError. IfenableScriptEngineNashornCompatibilityistrue, CIB seven 3.0 therefore also sets the ECMAScript version to 2022 (js.ecmascript-version). Scripts in this mode can uselet,const, arrow functions and the built-in objects of ECMAScript 2022. In 2.2, scripts in this mode could already uselet,constand arrow functions, but built-in objects such asMap,Set,SymbolandPromisewere 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-runtimeis 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::loadand memory access methods ofsun.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 declareorg.graalvm.js:jswith<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 forjs-25.0.1.jar, which does not exist, and the build fails withCould not find artifact org.graalvm.js:js:jar:25.0.1. Keepjs-scriptengineas a separate dependency: it is the JSR-223 bridge thatScriptEngineManagerdiscovers, and thejsPOM does not bring it in. Everything else is resolved transitively. -
If your code or your scripts use
com.ibm.icuclasses, addcom.ibm.icu:icu4jto your application. The distributions contain version71.1. -
If you create the GraalJS context yourself and set
js.nashorn-compat, for example in a custom ScriptEngineResolver, also setjs.ecmascript-version, for example to2022. 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.*.jarandtruffle-api-21.3.*.jar) and copy the jars listed in GraalVM JavaScript Integration. Keepicu4j-71.1.jar. -
If you installed CIB seven into WildFly or JBoss EAP manually or maintain your own
module.xmlfiles, replace the GraalJS modules with the modules listed in GraalVM JavaScript Integration, and take the moduleorg/cibseven/bpm/cibseven-enginefrom the 3.0 distribution. Itsmodule.xmldepends on the new moduleorg.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 inJAVA_OPTS. Java 17 and 21 do not know the option--sun-misc-unsafe-memory-accessand 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
PolyglotExceptionin 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 withClassCastExceptionif 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 showsAmount 6.0instead ofAmount 6. - The REST API and Cockpit show the type Double (with
nonealso 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))orVariables.integerValue(n + 1)aftervar 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 examplecibseven-bpm-spring-boot-starter-4),cibseven-bpm-run4*andcibseven-engine-spring-7. - In CIB seven 3.0, the artifacts without suffix use Spring Boot 4.1 and Spring Framework 7. The former
-4,run4and-7artifacts 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,run4or-7with the artifact IDs without suffix, for examplecibseven-bpm-spring-boot-starter-4withcibseven-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.ProcessEngineRuleis 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.DmnEngineRuleis no longer a JUnit 4 rule either. It creates the DMN engine in its constructor and provides it throughgetDmnEngine().org.cibseven.bpm.engine.test.ProcessEngineTestCaseno longer extends the JUnit 3 classjunit.framework.TestCase.- The Spring Boot test starter (
cibseven-bpm-spring-boot-starter-test) no longer bringsjunit-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
ProcessEngineExtensionfromorg.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 DmnEngineRulewith a plain field,DmnEngineRule dmnEngineRule = new DmnEngineRule();, and usedmnEngineRule.getDmnEngine(). -
Subclasses of
ProcessEngineTestCasekeep 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-styletest*()methods without@Testare no longer discovered and do not run. - Replace overrides of the JUnit 3 methods
setUp()andtearDown(), and calls ofsuper.setUp(),super.tearDown()andgetName(), with your own@BeforeEach/@AfterEachmethods. They run after the process engine setup and before the process engine teardown. Use aTestInfoparameter instead ofgetName(). With@Override, such an override no longer compiles; without@Override, it compiles but does not run, because it is not annotated. setUpProcessEngineTestCaseandtearDownProcessEngineTestCaseare new in 3.0. If you override them, annotate the override with@BeforeEach/@AfterEachand callsuper.
Alternatively, register it as an extension:
@RegisterExtension ProcessEngineTestCase extension = new ProcessEngineTestCase();, and get the services through its getters. - Annotate every test method with
-
Tests whose
@RequiredHistoryLevelor@RequiredDatabasedoes 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 languagejuel. 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-juelcontained 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, andnullpassed to aLong,BooleanorBigDecimalparameter becomes0,falseor0. - Two kinds of method calls failed with a
NullPointerExceptionin 2.2. In 3.0,nullas the only argument of a varargs parameter becomes an array with the convertednull, for example[""]forString...and[0]forLong.... A method that cannot be accessed, for example a method of a non-public class that no public interface or superclass declares, fails with aMethodNotFoundException. cibseven-engine-dmnandcibseven-engine-feel-juel, and with them the process engine, now bring the EL APIjakarta.el:jakarta.el-api6.0.1as a compile dependency. In 2.2, they brought no EL API, becausecibseven-juelcontained 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-api6.0.xwithorg.glassfish.expressly:expressly6.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:expressly6.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 usedorg.glassfish:jakarta.el4.0.2for 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 thatjakarta.el.ExpressionFactory.newInstance()finds, for example when a plainjakarta.el.BeanELResolverchecks 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-jerseybrings it throughjersey-bean-validation, and Maven prefers it because it is nearer in the dependency tree. Spring Boot applications withcibseven-bpm-spring-boot-starter-restusually get Expressly 5.0 the same way. org.cibseven.bpm.impl.juel.ExpressionFactoryImpl#coerceToTypenow has the generic signature ofjakarta.el.ExpressionFactory:<T> T coerceToType(Object obj, Class<T> targetType)instead ofObject 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 packageorg.cibseven.bpm.impl.juel.jakarta.el. In 3.0, this package no longer exists, and the process engine usesjakarta.el. This affects your own implementations of the EL API, for example anELResolver, anELContext, aTypeConverter, anExpressionFactoryor aValueExpression, and your own expression manager. They must importjakarta.eland use the signatures of EL 6.0. The generic signatures ofconvertToType,coerceToTypeandgetValue, and the removal ofMethodExpression#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 fromgetBeanElResolver(), 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 withUnable to find unambiguous methodand 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#convertToTypecome first, then JUEL. These resolvers do not take part in the selection of the method.
Migration steps
- If a subclass of
ExpressionFactoryImploverridescoerceToType, change the method topublic <T> T coerceToType(Object obj, Class<T> targetType). - Replace the imports of
org.cibseven.bpm.impl.juel.jakarta.elwithjakarta.eland adapt your EL classes to the signatures of EL 6.0. This includes process applications that overridegetElResolver(),getBeanElResolver()orinitProcessApplicationElResolver(). - If your own expression manager or process application creates a
jakarta.el.BeanELResolver, create anorg.cibseven.bpm.impl.juel.JuelBeanELResolverinstead, as the expression managers of CIB seven do. Method calls then behave as in 2.2. LikeJuelExpressionManager, 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:expresslyfrom the CIB seven dependencies that bring it, for examplecibseven-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 plainjakarta.el.BeanELResolverin 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.AbstractElResolverDelegateorg.cibseven.bpm.engine.impl.el.ReadOnlyMapELResolverorg.cibseven.bpm.engine.impl.el.VariableContextElResolverorg.cibseven.bpm.engine.impl.el.VariableScopeElResolverorg.cibseven.bpm.engine.test.mock.MockElResolverorg.cibseven.bpm.dmn.engine.impl.el.VariableContextElResolverorg.cibseven.bpm.impl.juel.RootPropertyResolverorg.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
getFeatureDescriptorswith@Override; - it calls
super.getFeatureDescriptors(...); - it uses
ELResolver.TYPEorELResolver.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 asengine-restin 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. Aweb.xmlthat you customized for the Jakarta variant of 2.2 (cibseven-engine-rest-jakarta, Tomcat 10) keeps working. Aweb.xmlfrom the Java EE variant of 2.2 (Tomcat 9) needs the context parameterjakarta.ws.rs.Applicationinstead ofjavax.ws.rs.Application. The war no longer containsangus-activation: the pre-packaged Tomcat distribution provides it inlib/, 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:
AbstractBindermoved fromorg.glassfish.jersey.internal.inject(jersey-common) toorg.glassfish.jersey.inject.hk2(jersey-hk2);jersey-container-servlet-coreis no longer released and is part ofjersey-container-servlet;jersey-apache-connectoris replaced byjersey-apache5-connector.
Users of the
-4starters of 2.2 already run on Jersey 4.0. -
JAX-RS 4.0 removed the classes
Link.JaxbLinkandLink.JaxbAdapterand 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-vertxandresteasy-reactor-netty. This affects you if you run the REST API on one of these adapters.
Migration steps
- Replace
Link.JaxbLinkandLink.JaxbAdapterwith your own JAXB types. - Replace
@ManagedBeanon JAX-RS resources and providers with a CDI scope annotation, for example@RequestScopedor@ApplicationScoped. - If you run the REST API in an embedded RESTEasy server with Netty, Vert.x or Reactor Netty, switch to
resteasy-undertoworresteasy-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-valuesbrings 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 exampletext/plainfor.txtandimage/pngfor.png. File types that 2.2 did not know either, for example.pdf,.jsonor Office files, stayapplication/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-valuesandorg.cibseven.bpm.cibseven-enginedepend on the server moduleorg.eclipse.angus.activation, withservices="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-apiandangus-activationfrom$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, excludejakarta.activation:jakarta.activation-apiandorg.eclipse.angus:angus-activation. IfWEB-INF/libcontains Angus and the Activation API, the MIME type detection of the shared process engine fails in calls from this web application, and every file getsapplication/octet-stream. - If you installed CIB seven into WildFly or JBoss EAP manually or maintain your own
module.xmlfiles, take the modulescibseven-commons-typed-valuesandcibseven-enginefrom 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-jacksonand its shaded variantcibseven-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,JsonMapperandJavaType:- Spin: the constructor
JacksonJsonDataFormat(String, ObjectMapper),getObjectMapper(),setObjectMapper(ObjectMapper)andconstructJavaTypeFromCanonicalString(String)oforg.cibseven.spin.impl.json.jackson.format.JacksonJsonDataFormat; - External Task Client:
getObjectMapper()andsetObjectMapper(ObjectMapper)of itsJacksonJsonDataFormat,ExternalTaskClientBuilderImpl#getObjectMapper()andOAuth2ClientCredentialsProvider.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 byconfigureObjectMapper(), which returns the configuredJsonMapper. Applications that registercom.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvidermust registerorg.cibseven.bpm.engine.rest.mapper.CibsevenJacksonJsonProviderinstead.
- Spin: the constructor
- CIB seven no longer brings Jackson 2.
- The Spring Boot starters no longer bring
jackson-databind2,spring-boot-jackson2andjersey-media-json-jackson. Unless your application bringsspring-boot-jackson2itself, there is no Jackson 2ObjectMapperbean. 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.
- The Spring Boot starters no longer bring
- 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.xmllets 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 .../variablesof 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)orId.MINIMAL_CLASSon properties of typeObject, 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
@JsonNamingor withjava.timeproperties.
Spring Boot applications
-
Import
cibseven-bombeforespring-boot-dependencies. Spin JSON on Jackson 3 needscom.jayway.jsonpath:json-path3.0.0 or later, while Spring Boot 4.1 manages json-path 2.10.0. Ifspring-boot-dependenciescomes first, the application does not start and the log namesSPIN/JACKSON-JSON-01018. If your project inherits fromspring-boot-starter-parent, set the propertyjson-path.versionto3.0.0instead.<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, addorg.springframework.boot:spring-boot-jackson2to 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.annotationnext to the one ofcom.fasterxml.jackson.databind.annotationon 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.annotationonce nothing on 2.x reads these variables any more. -
Lombok. Up to Lombok 1.18.42,
@Jacksonizedgenerates the annotations of Jackson 2 only. From Lombok 1.18.44, add the following lines tolombok.configto generate both:lombok.jacksonized.jacksonVersion += 2 lombok.jacksonized.jacksonVersion += 3 -
The
-jackson2artifacts. 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-jackson2artifacts.
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.DataFormatConfiguratorfororg.cibseven.spin.impl.json.jackson.format.JacksonJsonDataFormatand register the class inMETA-INF/services/org.cibseven.spin.spi.DataFormatConfigurator(see Configuring Data Formats). - For the External Task Client, implement
org.cibseven.bpm.client.spi.DataFormatConfiguratorfororg.cibseven.bpm.client.variable.impl.format.json.JacksonJsonDataFormatand register the class inMETA-INF/services/org.cibseven.bpm.client.spi.DataFormatConfiguratorof 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:
READon the task orREAD_TASKon the process definition. - Reading an attachment of a process instance or the attachment list of a process instance:
READon the process instance orREAD_INSTANCEon 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_WORKorUPDATEon the task, orTASK_WORKorUPDATE_TASKon the process definition; of a process instance:UPDATEon the process instance orUPDATE_INSTANCEon 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:
READon the task orREAD_TASKon the process definition. - Reading the comments of a process instance:
READon the process instance orREAD_INSTANCEon the process definition. Task comments the caller may not read are left out. - Adding a comment to a task:
TASK_WORKorUPDATEon the task, orUPDATE_TASKon the process definition; to a process instance:UPDATEon the process instance orUPDATE_INSTANCEon 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, contextandlang:importare 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_ENDPOINTSfor all connectors,cibseven.connect.<connectorId>.allowed-endpoints/CIBSEVEN_CONNECT_<CONNECTOR_ID>_ALLOWED_ENDPOINTSfor 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_URLto 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:typeon 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;-entryremoves 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,reportlogs a warningENGINE-25010and allows it,offdisables 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-25011if the configured expression manager is not aJuelExpressionManager,ENGINE-25012if a custom expression manager’s own policy overrides the properties,ENGINE-25013if 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.