Skip to main content

Upgrading Flowable

This page describes how to upgrade a Flowable installation from one version to another. The recommended procedure differs for Service Packs and major releases.

Versioning scheme​

Flowable releases follow a MAJOR.SERVICEPACK scheme, where MAJOR is itself a YYYY.X pair (for example 2025.1, 2025.2). The year is not a separate versioning level on its own; it is part of the major version.

  • Major release (change in MAJOR, i.e. in YYYY.X): may contain breaking changes to the public API, database schema additions, major dependency upgrades (Spring Boot, Java, Jakarta EE) and behavioral changes. Always review the release notes for the target version before upgrading.
  • Service Pack (change in SERVICEPACK): contains bug fixes and security updates within the same major line. Service Packs are designed to be drop-in replacements and do usually not introduce breaking changes to the public API. See the Public API and backwards compatibility page for the exact API scope. (These are also commonly referred to as patch releases.)

Before you upgrade​

Regardless of whether you are applying a Service Pack or a major upgrade:

  1. Read the release notes for every version between your current and target version, in particular the Upgrade information section.
  2. Verify that your runtime environment still meets the system requirements of the target version. Major releases occasionally raise the minimum Java, Jakarta EE or database version.
  3. Test the upgrade in a non-production environment that mirrors production as closely as possible, including the database engine and version, identity provider, Elasticsearch, and any custom extensions.
  4. Make sure you have a working backup and restore procedure, and an actual recent backup to restore from if anything goes wrong.

Upgrading your code (Flowable Spring Boot Starters)​

When you embed Flowable in your own Java application via the flowable-spring-boot-starter-* artifacts, an upgrade is in the first place a dependency bump.

tip

Stick to the public API. Using internal classes and packages outside the public API surface is not recommended: they carry no backwards-compatibility guarantee and may change or be removed in any release, including Service Packs. Code that depends on internals tends to make every upgrade more painful than it needs to be.

Service Pack upgrade​

For example, going from 2025.2.10 to 2025.2.11.

  1. Update the Flowable version property (or BOM import) in your pom.xml / build.gradle:

    <properties>
        <com.flowable.platform.version>2025.2.11</com.flowable.platform.version>
    </properties>

  2. Rebuild and run your existing test suite. No code changes should be required.

  3. Review the Service Pack entry in the release notes for security advisories or fixes that affect your application.

Flowable Service Packs are typically aligned with a new Spring Boot patch version (e.g. Spring Boot 4.0.1 → 4.0.2) to pick up upstream security fixes. Bumping the Flowable version does not automatically bump Spring Boot because the Spring Boot version is controlled by your own project. If your project uses spring-boot-starter-parent as its parent POM (or pins the Spring Boot version another way), make sure it is at least the Spring Boot version listed in the Service Pack entry of the release notes. A newer patch in the same minor family will usually also work (for example, if the Service Pack ships with Spring Boot 4.0.2, any 4.0.x with x >= 2 is generally fine), but this is not a hard guarantee and should be verified by your own testing.

Major upgrade​

For example, going from 2025.1.10 to 2025.2.01. Any change in the YYYY.X major version is a major upgrade and follows this procedure.

  1. Bump the Flowable version. Note that this does not automatically change your Spring Boot version. If your project uses spring-boot-starter-parent as its parent POM (or pins the Spring Boot version another way), bump it explicitly to the version documented in the target release notes, along with any other transitively managed dependencies. A major Flowable release is typically aligned with a Spring Boot major upgrade, as opposed to the Spring Boot patch bumps shipped in Flowable Service Packs. When the upgrade includes a Spring Boot major bump, also read the Spring Boot release notes and migration guide for the new major version, since they might list upstream breaking changes that the Flowable release notes do not repeat. A Spring Boot major upgrade may in turn require:
    • A newer Java version.
    • A newer Jakarta EE compliant servlet container (e.g. a newer Tomcat version)
    • Updated Spring Security configuration.
  2. Apply the breaking changes listed in the Upgrade information section of the target release notes. Common categories are:
    • Custom Spring Security configurations that need to be migrated to the newer matcher API.
    • Custom auto-configuration exclusions that are no longer needed.
    • Customizations of the Elasticsearch REST client.
  3. Re-run your test suite and pay special attention to:
    • Custom REST controllers, filters and security configurations.
    • Custom Java service tasks, listeners and expressions that use Flowable internals outside the public API.
    • Any database-specific behavior (custom queries, native SQL).
  4. Build a new artifact (jar / Docker image) for deployment.

Infrastructure-side upgrade procedure​

note

If you deploy Flowable with the official Flowable Helm charts, also review the chart version when upgrading the Flowable application version. The chart's major (YYYY.X) line tracks the Flowable major line, but the chart's Service Pack number is independent of the Flowable Service Pack number. Pick the latest chart Service Pack in the matching YYYY.X.x line. See Versioning Concept for details.

The Flowable database schema is, by default, updated automatically on startup when flowable.common.app.db-schema-update=true. In that case there is no separate migration tool to run; the new application version applies the schema changes itself when it boots, using the SQL upgrade scripts shipped with the engine.

If you manage the schema yourself (the application's database user does not have DDL rights, or schema changes go through a separate DBA-controlled process), set flowable.common.app.db-schema-update=false and apply the schema changes manually before starting the new version. The SQL scripts for each release, including the upgrade scripts in the upgrade/ folder of the ZIP, are available from the database scripts download. Make sure to apply the scripts in the order documented on that page.

Multi-node deployments: schema lock​

In a clustered deployment, multiple nodes can start at the same time and all of them would otherwise try to apply the same schema update concurrently. To prevent that, enable the schema lock so that only the first node performs the DDL migration and the others wait until it has finished:

flowable.use-lock-for-database-schema-update=true
flowable.schema-lock-wait-time=5m
  • flowable.use-lock-for-database-schema-update (default false) makes a node acquire a global lock before applying schema changes. Other nodes that hit the same startup phase block until the lock is released.
  • flowable.schema-lock-wait-time (default 5m) is how long a waiting node tries to acquire the lock before giving up and failing to start. Increase this if your migration is expected to take longer than the default.

We recommend keeping this enabled in any clustered environment, especially for major upgrades where the schema changes are non-trivial.

Service Pack: rolling update​

Service Packs are backwards compatible at the API and database level and can be applied with a rolling update in a clustered deployment:

  1. Take a database backup before starting the rollout. A Service Pack upgrade is unlikely to alter the schema, but having a known-good backup is cheap insurance.
  2. Replace the application artifact / image one node at a time. As each node restarts on the new version it joins the existing cluster; the remaining nodes keep serving traffic.
  3. Monitor the application logs while the rollout progresses.
  4. Once all nodes report the new version and are healthy, the upgrade is complete.

This procedure works on Kubernetes (a standard rolling Deployment update), behind a load balancer, and on any other platform where you can replace nodes one at a time.

Major release: full shutdown​

For a major upgrade we recommend a full shutdown of all Flowable nodes during the switchover. A rolling update is not supported for major releases because the schema changes applied on startup are not backwards compatible with the previous version, and because the procedure includes taking a cold backup as a rollback point.

  1. Announce a maintenance window, since the application will be unavailable for the duration of the upgrade.
  2. Stop all Flowable nodes. Database, Elasticsearch and content storage can keep running. There is no need to drain async jobs first: shutting Flowable down with running jobs is safe, see Async jobs and shutdown below.
  3. Take a full cold backup as described in Backing up and restoring. This is the rollback point if the upgrade fails. Because the application is stopped, the database, Elasticsearch and content storage backups are taken in a consistent state.
  4. Apply the database schema changes. If flowable.common.app.db-schema-update=true (the default) this happens automatically when the new version starts in step 5. If you manage the schema manually, run the upgrade SQL scripts from the database scripts download for the target version now.
  5. Deploy the new version of the application artifact / image and start the first node. Watch the startup logs and only continue if it boots cleanly.
  6. Start the remaining nodes once the first node is healthy and on the new version.
  7. Verify the deployment by checking the version on the system information endpoint, the application logs, and a smoke test of the most important user flows.
  8. Resume traffic and close the maintenance window.

If anything goes wrong during step 5, restore from the backup taken in step 3 and roll back to the previous application version before reopening traffic.

Async jobs and shutdown​

You do not need to drain or pause the async executor before shutting Flowable down for an upgrade. Two mechanisms make sure no work is lost:

  • Graceful shutdown. When Spring Boot graceful shutdown is enabled (server.shutdown=graceful), the application stops accepting new HTTP requests and waits for in-flight work to finish before the JVM exits. The maximum wait time is controlled by spring.lifecycle.timeout-per-shutdown-phase (default 30s); raise it if your jobs typically take longer than that to complete. The Flowable async executor participates in the shutdown lifecycle, so jobs that finish within the grace period are committed normally.

  • Job lock expiry. A job that is still running on a node when the JVM is killed (for example, because the grace period was exceeded or the node crashed) remains locked in the database. After the lock expires, another node picks the job up and re-executes it. The default lock duration is 1 hour and is configured per engine through the corresponding async executor property:

    • flowable.process.async.executor.async-job-lock-time (BPMN process engine)
    • flowable.cmmn.async.executor.async-job-lock-time (CMMN case engine)
    • flowable.agent.async.executor.async-job-lock-time (agent engine)
    • flowable.process.async-history.executor.async-job-lock-time (async history executor)
    • flowable.content.async.executor.async-job-lock-time (content engine)

    Lower the value if you want jobs from a killed node to be retried sooner during an upgrade; raise it for long-running jobs that should not be retried prematurely.

In practice this means a major upgrade can simply stop all nodes (with a sensible grace period), apply the schema changes, and start the new version. Any jobs that were mid-flight are picked up by the new version once the lock expires.

Schema migration duration and Kubernetes probes​

Major upgrades can include non-trivial schema changes. The time it takes to apply them on startup depends on the number and type of changes (added columns, new tables, index rebuilds) and on the amount of data already in the database. On large instances this can range from a few minutes to substantially longer.

If you run Flowable on Kubernetes, the default liveness, readiness and startup probe settings are tuned for a normal application start, not for a node that is also applying a long-running database migration. If a probe times out during the migration, Kubernetes will kill the pod and restart it, which interrupts the schema update and can leave it in a partially applied state.

Before a major upgrade on a large instance:

  • Increase startupProbe.failureThreshold (and/or initialDelaySeconds and periodSeconds) so that the pod has enough time to finish the schema update before the startup probe gives up. The startup probe is the right knob here, since it is meant for slow-starting containers and disables the liveness probe until startup completes.
  • Make sure livenessProbe does not start running while the migration is still ongoing. With a properly configured startupProbe, Kubernetes only switches to the liveness probe once startup has succeeded.
  • Estimate the migration duration on a representative copy of production data during your upgrade test (see Before you upgrade) and pick probe values with a generous safety margin.

After the upgrade has completed and the schema is up to date, the probe values can be reverted to their normal settings.

Notes on Elasticsearch and content storage​

  • Elasticsearch index mappings can change between major releases. The release notes will mention if a reindex is needed; see Reindexing.
  • Content storage layout is stable across releases. No special action is required for binary content during an upgrade.

Rollback​

For Service Packs, redeploying the previous artifact is normally sufficient because there are no schema changes.

For major releases, rolling back requires both:

  • Redeploying the previous application artifact, and
  • Restoring the database (and Elasticsearch, if it was reindexed) from the backup taken before the upgrade.

This is why taking a backup as part of the major-release procedure is non-negotiable: once the new version has applied its schema changes, the previous version can no longer start against that database.