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:
- Authentication & IAM —
SECURITY_TYPEon every service, service-account secrets, the two-realm setup. The largest break. See Authentication & IAM migration. ORGANIZATION_ID— on the 9 services that backfillorganization_id. See License and organization configuration.licenseservice + env-info replacement vars —FLOWX_LICENSE_*,DEFAULT_ORGANIZATION_NAME, the home URIs. See License and organization configuration.- Kafka, ingress/CORS, engine partitioning — see Kafka migration, Ingress routing and CORS, Engine partitioning.
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).Related resources
Prerequisites & upgrade path
What to gather before you start.
License and organization configuration
The provisioning, data-sync, and license steps in detail.

