Skip to main content

​
Audience and scope

This guide is for operators of self-hosted FlowX.AI 5.1.x LTS deployments upgrading to 5.9.x LTS. The 5.9.x LTS family opens with 5.9.0 (target 2026-06-02) and continues with monthly LTS patches from July 2026 onward.
  • In scope: Self-hosted deployments running any 5.1.x patch level.
  • Out of scope: SaaS deployments. They are continuously upgraded on the SaaS line and do not perform this migration. Any other self-hosted source version requires a FlowX-assisted custom migration plan.
The upgrade jumps directly from the 5.1.x LTS line to the 5.9.x LTS line.
Confirm your upgrade plan with FlowX before starting. Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.

​
Get your Organization UUID

FlowX issues an Organization UUID when your organization registers with FlowX SaaS for license validation and usage reporting. Request it from your FlowX representative before the upgrade window starts. You will need this single UUID for:
  • The ORGANIZATION_ID Liquibase parameter on 9 services (application-manager, authorization-system, cms-core, document-plugin, integration-designer, notification-plugin, organization-manager, process-engine, scheduler-core). See Organization & deployment configuration for the full behavior.
  • The FLOWX_LICENSE_ORGANIZATIONID runtime env var on the license service (OAuth client-id for the FlowX SaaS license handshake. Different env var, same UUID value).
  • The Fx-Organization-Id Kafka header on every custom producer.

​
Inventory to gather

Before the upgrade window, capture the following from your current 5.1.x deployment:
1

Current component versions

Open FlowX.AI Designer → Platform Status and record the version of each FlowX component. You will compare these against the 5.9.x targets in the v5.9.0 deployment guidelines after the upgrade.
2

Current SDK versions

List the @flowx/* web SDK package versions in each container app, plus the iOS and Android renderer versions. iOS and Android renderers ship on the 9.0.x line in 5.1.x; 5.9.x targets the 10.x line. Web @flowx/* packages follow the Designer version baseline, not the renderer 9/10 numbering.
3

Keycloak realms and clients

Export the list of realms, clients, client scopes, and protocol mappers from your current Keycloak. 5.9.x introduces a dedicated service-accounts realm and renames every service-account client to a flowx-{service}-sa pattern. See Authentication & IAM migration.
4

Kafka topic ACLs and custom producers

If you manage Kafka topic ACLs manually, list every topic and its producers/consumers. The WorkspaceCreatedEvent topic ownership changes on 5.9.x. List every custom Kafka producer your team operates. Each must add the Fx-Organization-Id header on 5.9.x.
5

Custom API clients

Identify any internal tooling that calls:
  • GET /api/process-definition/{uuid}/get-input-json. Renamed to /get-start-metadata on 5.9.x.
  • PATCH /api/platform/environment. Removed on 5.9.x.
6

Partitioning configuration

If you enabled data partitioning on 5.1.x, capture the current scheduler.dataPartitioning YAML block and the five related env vars. The structure and names change on 5.9.x; your FlowX representative will share the new YAML during the upgrade plan.
7

Backups

Take fresh backups of:
  • All Postgres databases (per-service).
  • All MongoDB databases (per-service).
  • Keycloak realm exports.
  • SpiceDB schema and relations.
These backups are the only way back. There is no in-place downgrade from 5.9.x to 5.1.x — reverting means restoring every one of these stores to its pre-upgrade state and losing everything written after it. See Rollback considerations below.
Carry forward every required configuration from your 5.1.x deployment. This guide documents what changes on 5.9.x; it does not re-list every configuration value your services already require. Values your 5.1.x services depend on — such as SpiceDB connection and credentials, Redis, and database settings — remain required on 5.9.x and must be carried over. If a service fails to start and its logs report a missing configuration, that value is required: take it from your existing 5.1.x configuration.

​
Dropped third-party dependency versions

The following third-party versions are no longer supported in 5.9.0. Upgrade them before the FlowX 5.9 upgrade window — running an unsupported version after the FlowX upgrade is not covered by the standard support process.
Versions are dropped from the supported list as upstream support is no longer provided. For the full supported-version matrix (Keycloak, PostgreSQL, MongoDB, Oracle, Elasticsearch Sink Connector, renderer SDKs), see the v5.9.0 deployment guidelines — Third-party supported component versions.

​
Infrastructure deltas

The 5.1 → 5.9 jump adds several runtime dependencies your 5.1.x environment may not already have:

​
New services to deploy

5.9.x ships several microservices that do not exist in a 5.1.x deployment. Ensure Helm charts and infrastructure are provisioned for these before upgrading:
The AI Platform is also new on 5.9.x. If your deployment uses AI features, refer to the AI Platform setup guide for the full list of AI services (agent-builder, knowledgebase-rag, embedder, and others) and their infrastructure requirements (Qdrant and S3).The AI Platform also ships a versioned documentation image (flowx-docs:5.9.0) that is mounted into the AI Assistant so it can answer from the FlowX documentation. It is a content image, not a standalone service; pull the version matching your release (see the component versions in the deployment guidelines).
Confirm minimum versions against the v5.9.0 deployment guidelines Third-party supported component versions table before scheduling the upgrade window.

​
Rollback considerations

Plan the 5.1.x → 5.9.x upgrade as a one-way move. There is no downgrade path from 5.9.x back to 5.1.x: no reverse migration, no configuration switch, no partial revert. The only way back is a full point-in-time restore of every FlowX datastore — all Postgres databases, all MongoDB databases, the Keycloak realms, and SpiceDB — to the backups taken before the upgrade window opened. Everything written after that point is discarded with the restore: process instances, tasks, documents, audit records, and every user, group, and role change.
The upgrade migrates identity, configuration, and runtime data in place across systems that reference each other, which is what rules out a partial rollback. Restoring one of them while the rest stay on 5.9.x leaves the platform inconsistent rather than recovered.

​
What the upgrade changes for good

Most of what makes the upgrade one-way sits in these areas:
  • Identity. Keycloak realms and every service account are reorganized during the upgrade. Going back means returning to the realm export taken beforehand, and with it losing the end users onboarded, passwords reset, and MFA enrolled since cutover.
  • Platform data. The database migrations are forward-only, and process instances are migrated in place. Runtime work that advanced on 5.9.x has no 5.1.x equivalent to return to.
  • Access model. End-user groups, solution sharing, and UI Flow permissions become FlowX-managed records with no 5.1.x counterpart, so the access configuration your teams rebuild after the upgrade does not survive a restore.
  • AI capabilities. Knowledge Base content is indexed into a new vector database, and the AI services it replaces leave the deployment. Returning to 5.1.x means standing the previous AI stack back up and rebuilding its indexed content.
  • Client applications. The web, iOS, and Android renderers move to a new SDK line, and custom integrations adopt a changed API surface. Reverting the platform means reverting those releases too — for mobile apps, on app-store review timelines.
Individual settings that changed shape can be reverted on their own, and each topic page notes where that applies. None of them add up to a way back to 5.1.x.

​
Plan the window around this

Because rollback costs data, the mitigations all sit before and during the upgrade rather than after it.
1

Rehearse on a full copy of production

Restore a recent production backup into an isolated environment and run the complete upgrade against it, including the restore procedure itself. The rehearsal is where you find out whether your backups are actually restorable.
2

Take the backups immediately before cutover, with runtime traffic stopped

Stop runtime traffic before the backups so the restore point sits as close as possible to the cutover. Every minute of traffic accepted after the backup is data a rollback would discard.
3

Put the go/no-go decision before first login

Everything up to and including the data-sync job is platform work on already-migrated data. Once users log in and runtime traffic resumes, new business data accumulates on 5.9.x and the cost of restoring climbs with every hour. Make the abort decision at that boundary — see the data-sync step for what has to complete before anyone logs in.
4

Agree the acceptable data loss with the business

Confirm before the window who accepts the loss of post-cutover runtime data if a restore is called, and how long the platform may stay unavailable while it runs.
This applies to crossing the LTS boundary. Moving between patch releases inside the 5.9.x family (5.9.1 to 5.9.2, for example) is a routine in-family upgrade covered by the LTS compatibility guarantee, and carries none of the migrations above.

​
Next

Authentication & IAM migration

Start with this. It is the largest single break.

Runtime authorization migration

Project-scoped roles, end-user groups, per-environment sharing.
Last modified on August 4, 2026

Related topics

Migrating from 5.1 LTSDeployment guidelines v5.8.0Deployment guidelines v5.7.0Prerequisites