Skip to main content
The topic pages in this guide each cover what changes. This page covers when to do each thing. Follow the steps in order; each links into the detailed page for that step.
The single ordering that most often breaks an upgrade: run the data-sync job before anyone logs in (Step 7). Until it completes, every login — including FlowX Designer — fails with Could not find all end-users group for this organization. Do not skip ahead to login.

Confirm the plan and gather inventory

Agree the upgrade path with FlowX, get your Organization UUID, and request the custom migration scripts for inactive/archived process instances before the upgrade window. If you are arriving from 4.7.x, first land on the latest 5.1.x patch, not an arbitrary one. See Prerequisites & upgrade path.

Verify the source environment is fully functional

Start the upgrade only from a healthy 5.1.x environment: Designer → Platform Status shows every service up, and the data-sync job from any previous upgrade completed successfully. Upgrading over a partially migrated environment produces data inconsistencies that surface much later. See Start from a fully functional environment.

Set all required configuration before first boot

These must be in place on the relevant services before you start 5.9.x — several services refuse to boot or fail silently otherwise:

Deploy the new and reorganized services

Bring up the four new backend services (email-gateway, organization-manager, webhook-gateway, license) and apply the AI Platform reorganization (drop the 9 deprecated services, add the new ones). See the service list in the overview.

First boot — let Liquibase migrate

On first boot against your 5.1.x databases, active process instances migrate automatically and ORGANIZATION_ID backfills run. Inactive/archived instances need the FlowX-provided scripts from Step 1 — do not resume runtime traffic until those have run. See Liquibase migration.

Provision the organization

Complete the first-launch Environment Setup wizard (or the Manual Keycloak Configuration recipe if the platform cannot administer Keycloak). Requires outbound HTTPS to FlowX SaaS for license validation. See Creating the self-hosted organization.

Run the data-sync job — before any login

Run data-sync and let it finish. It creates the “All end-users” runtime group that 5.1.x organizations lack. Until it completes, all logins fail (see the warning above). On authorization-system older than 10.97.0, also clear the cache after it completes. See the data-sync warning.

First login and runtime authorization migration

Now log in. Org-level roles become project-version-scoped and end-user groups move from Keycloak into FlowX. See Runtime authorization migration.

Verify

Confirm Organization UUID in startup logs, Designer → Platform Status at 5.9.x versions, Liquibase complete on every service, license reachable, and LLM_ENCRYPTION_MASTER_KEY non-default. Full checklist in Verify the configuration. Then migrate the renderer SDKs (Android, iOS, React, Angular).

Prerequisites & upgrade path

What to gather before you start.

License and organization configuration

The provisioning, data-sync, and license steps in detail.
Last modified on September 11, 2026