Edit on Github

Update from 1.3.0 to 1.4.0

This guide covers the four areas where 1.4.0 requires a decision or an action before you upgrade: CMMN, the javax namespace, containers and runtimes, and database changes. Each section follows the same order — what was announced, what 1.4.0 delivers, and what you have to do.

For the full list of what is in the release, see the 1.4.0 release notes.

Read this before you run the migration

The 1.3-to-1.4 schema migration is irreversible. There is no downgrade script. Take a backup you have actually restored from before, not one you assume works.

Before you start

  1. Check for CMMN usage — detection queries. This is the one item that can stop the migration outright.
  2. Check your Java version. 1.4.0 requires Java 21.
  3. Check your container. The standalone distributions are Tomcat 11 and WildFly 41.
  4. Check your configuration for the three properties listed under Configuration that now fails startup.
  5. Back up the database.

1. CMMN

Announced. CMMN was named an obsolete component on the public support page on 17 April 2025, and the deprecation was repeated in the 1.3.0 release notes.

Delivered. CaseService, the CMMN Java API and model, and the /case-* REST endpoints are gone. The schema migration drops the CMMN tables and columns.

What to do. Complete or terminate every active case instance before you upgrade. The migration checks ACT_RU_CASE_EXECUTION and halts before making any schema change if it is not empty, with this message:

Cannot upgrade to 1.4: active CMMN case instances exist in ACT_RU_CASE_EXECUTION.
This migration drops CMMN history and runtime tables unconditionally;
complete or terminate all active case instances before upgrading.

The guard protects running instances only. Once it passes, CMMN history and deployed case definitions are deleted unconditionally — export anything you need to keep first. There is no migrator; the replacement path is remodeling the case in BPMN.

→ CMMN Deprecation & Removal — detection queries, the data-fate guarantees, REST and Java API impact, and a CMMN-to-BPMN pattern mapping table.

2. The javax namespace

Announced. The Jakarta-only direction was set with the Jakarta artifacts introduced in earlier releases; the javax build path was the remaining legacy branch.

Delivered. The engine, the Spring Boot and Quarkus integrations, the distributions and the clients are built exclusively against Jakarta EE. The javax-based build path is removed, and there is no javax-compatible build of 1.4.0.

What to do. Recompile your application against the jakarta.* APIs and replace every javax-targeted artifact with its Jakarta counterpart. If you use the OpenRewrite migration scripts, they handle the package moves; what they cannot do is decide for you when your container is ready.

3. Containers and runtimes

Delivered.

1.3.01.4.0
Java1721 (JDK 25 additionally verified in CI)
Tomcat distribution10.1.5011.0.25 (Servlet 6.1, Jakarta EE 11)
WildFly distribution37.0.0.Final41.0.1.Final
Tomcat 9 distributiondeprecatedremoved
WildFly 26 distributiondeprecatedremoved

What to do.

  • Java. Move to Java 21 first. This is a hard requirement, not a recommendation.
  • Tomcat 9 or WildFly 26. Upgrade the container before you upgrade EximeeBPMS — there is no 1.4.0 distribution that deploys onto them. Both were the javax-namespace distributions, and this release builds Jakarta artifacts only. This is not a statement about Tomcat 9’s own support status: Apache lists end of support for the 9.0.x line as no earlier than 31 March 2027.
  • Tomcat 10.1, using our distribution. The standalone distribution moves to Tomcat 11. Treat it as a container generation change and review any configuration you carried over.
  • Tomcat 10.1, running your own container. You are not forced onto Tomcat 11. The 1.4.0 web application archives (eximeebpms-webapp-tomcat-jakarta, eximeebpms-engine-rest-jakarta) deploy and run on Tomcat 10.1 — verified against 10.1.50; both declare a Servlet 3.0 descriptor and use no Servlet 6.1 feature.
  • Run distribution. Nothing changes. It embeds Tomcat through Spring Boot and has been on the Tomcat 11 line since 1.3.0.

→ Supported Environments

4. Database changes

The 1.3-to-1.4 migration script is the largest schema change this project has shipped. On every supported database it:

  • creates one table — ACT_RU_BUS_EVT_OBX, the business-event outbox;
  • drops 5 tables (ACT_RU_CASE_EXECUTION, ACT_RE_CASE_DEF, ACT_RU_CASE_SENTRY_PART, ACT_HI_CASEACTINST, ACT_HI_CASEINST);
  • drops 28 columns and 4 foreign-key constraints from shared runtime and history tables (ACT_RU_EXECUTION, ACT_RU_TASK, ACT_RU_VARIABLE, ACT_HI_*);
  • records the new schema version in ACT_GE_SCHEMA_LOG.

On SQL Server it additionally converts three columns from the deprecated image type to varbinary(max): ACT_ID_INFO.PASSWORD_, ACT_GE_BYTEARRAY.BYTES_ and ACT_HI_COMMENT.FULL_MSG_. Microsoft has deprecated image, text and ntext and plans to remove them.

The SQL Server column conversion needs no maintenance window

image and varbinary(max) share the same LOB storage, so SQL Server applies the conversion as a metadata-only change: no data is rewritten, regardless of how large ACT_GE_BYTEARRAY is. Measured on a purpose-built 1 GB table (4,096 rows × 256 KiB, 139,273 LOB pages; SQL Server 2022, RECOVERY FULL with an open log chain): 4 ms, not one LOB page rewritten, 60 KB of transaction log, data and log files unchanged in size.

The only scheduling consideration is the brief schema-modification lock every ALTER TABLE takes, which waits for transactions already open on the table.

What to do.

  1. Back up the database. The migration is irreversible.
  2. Clear active CMMN case instances (section 1) — otherwise the migration halts.
  3. Run the migration the way you normally do, either through the SQL upgrade script for your database or through Liquibase.
  4. New installations need none of this: the create scripts and the Liquibase baseline produce the 1.4.0 schema directly.

The halt-and-continue behaviour was verified on PostgreSQL and SQL Server: the guard stops the migration before any schema change while case instances remain, leaves every CMMN table in place, and the migration completes normally once they are gone.

Configuration that now fails startup

Three configuration surfaces changed in ways that stop the engine rather than warn.

SettingChangeWhat to do
scriptSecurityEnabled (engine)Replaced by the three-valued scriptSecurityMode (ENFORCE, AUDIT, DISABLED). An unrecognized value now fails startup.setScriptSecurityEnabled(false) becomes setScriptSecurityMode("DISABLED").
eximeebpms.bpm.script-security.cleanup-cron (Spring Boot)Removed. Violation retention is an engine job on a fixed 24-hour interval, gated on retention-days.Drop the property. The cleanup frequency is no longer configurable.
eximeebpms.bpm.admin-user.id beside an external identity provider (Spring Boot)Now fails startup when an OAuth2/OIDC client registration or a read-only identity provider is also configured.Either stop creating a local admin alongside single sign-on, or set eximeebpms.bpm.admin-user.allow-with-external-identity-provider deliberately.

After the upgrade

  • camunda:caseRef on call activities is now rejected at deploy time rather than failing when the process instance starts. Remove the attribute and redeploy those process definitions.
  • Telemetry payload. The serialized field camunda-integration is now eximeebpms-integration, and the reported product name is EximeeBPMS BPM Runtime. Update anything that parses collected diagnostics.
  • Model API. Every camunda-named method on the BPMN and DMN Model APIs has an EximeeBpms-named counterpart; the old names keep working throughout 1.4.x and are removed in 1.5.0. Nothing to do now — plan the rename during the 1.4 line.

On this page