Skip to main content
Four configuration areas need attention during the 5.1.x → 5.9.x upgrade: the ORGANIZATION_ID Liquibase parameter on services that backfill organization_id columns, the new license microservice that connects self-hosted deployments to FlowX SaaS, the deployment-time env vars that replace the legacy “Configure Environment Info” UI, and the organization registration step at first launch.
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.

​
ORGANIZATION_ID: where it is actually required

ORGANIZATION_ID is a Liquibase parameter used to backfill new organization_id columns on existing tables. It is NOT a service-wide config. Only the services that ship a Liquibase changeset reading ${organization-id} consume it. Set the UUID issued by FlowX (see Prerequisites) on these 9 services:
  • application-manager
  • authorization-system
  • cms-core
  • document-plugin
  • integration-designer
  • notification-plugin
  • organization-manager
  • process-engine
  • scheduler-core
Each of these services refuses to start without ORGANIZATION_ID set in a non-SaaS deployment. Behavior depends on the deployment scenario: The remaining services (admin, advancing-controller, audit-core, data-search, data-sync, email-gateway, events-gateway, license, nosql-db-runner, runtime-manager, task-management-plugin, webhook-gateway) do NOT declare ORGANIZATION_ID as a Liquibase parameter. Setting it on those is harmless but unnecessary.
Do not set ORGANIZATION_ID on a SaaS deployment (FLOWX_SAAS=true). The value is intended only for self-hosted upgrades and will conflict with the SaaS provisioning flow if set.

​
The license service uses a separate env var

The license service does NOT read the Liquibase ORGANIZATION_ID parameter. Instead, it consumes FLOWX_LICENSE_ORGANIZATIONID at runtime as the OAuth client-id for the FlowX SaaS license handshake. Both env vars carry the same UUID value, but they bind to different Spring properties on different services. See the next section for the full license service env var table.

​
Liquibase migration

When you boot 5.9.x for the first time against your 5.1.x databases:
  • Active process instances are migrated automatically. The default organization is replaced with your registered Organization UUID.
  • Inactive and archived process instances are not migrated automatically. FlowX provides custom migration scripts on demand. Request these from your FlowX representative before resuming runtime traffic, otherwise inactive instances will not be visible to users post-upgrade.
Plan the upgrade window with enough margin for Liquibase to complete; large deployments with many active instances will see migration runtime measured in minutes per service.
Verify migration completion by running the data-sync job after services boot. It surfaces any migration that failed silently or was skipped.
Run the data-sync job before users log in. Organizations provisioned on 5.1.x do not have the “All end-users” runtime group — it is created during organization provisioning or by the data-sync job. Until data-sync finishes, every login (including FlowX Designer) fails with an Internal Server Error in authorization-system:
Once data-sync completes, the group is created and the next login succeeds automatically — no cache clearing is required (the failed lookup is no longer cached).On authorization-system versions older than 10.97.0, the failed lookup is cached in Redis until the cache TTL (REDIS_TTL) expires. On those versions, clear the authorization-system cache entries (key prefix flowx:core:cache:authorization-system:) after data-sync completes, then log in again. FlowX.AI 5.9.1 ships authorization-system 10.103.0 or later, which includes this fix.

​
The license microservice

5.9.x ships a license service (PostgreSQL + Redis + Kafka + SpiceDB) that connects self-hosted deployments to FlowX SaaS for:
  • License validation against the registered Organization UUID.
  • Usage reporting (process instances, active users, AI usage counters).
  • Receipt of license events (renewal, expiry, plan changes).
Configure the connection. All four values are provided by FlowX licensing for the self-hosted deployment; none are derivable from the self-hosted environment:
The license service authenticates against two Keycloak instances. Inbound authentication uses the self-hosted Keycloak (configured via SECURITY_OAUTH2_BASE_SERVER_URL like every other service). Outbound calls to FlowX SaaS use a separate OAuth client, configured via the FLOWX_LICENSE_* env vars above.
Outbound HTTPS to the FlowX-provided license endpoints must be open from the license service. Confirm with your network team before the upgrade. Restricted environments may need an outbound proxy and an allow-list entry for the endpoints supplied with your license key.

​
Required self-hosted env vars

The legacy environment-info UI is no longer available. Its values move to deployment-time env vars, set on the services below:
LLM_ENCRYPTION_MASTER_KEY must be changed from its default value before going to production. The default default-dev-key-change-in-prod encrypts BYOK LLM provider credentials in the AI Providers UI. Leaving it in place means anyone with read access to the source code or default deployment manifests can decrypt your provider keys.
Env var naming convention. Spring relaxed binding accepts both the canonical UPPER_SNAKE form (FLOWX_DEFAULT_DESIGNER_HOMEURI) and the squished form (FLOWX_DEFAULT_DESIGNER_HOMEURI). Examples in this guide use the canonical form to match the k8s base templates; if you copy env vars from an older Helm chart and see the squished form, both bind to the same property.
In addition, the authorization-system service requires master-realm admin credentials and service-account secrets. See Authentication & IAM migration for the full list.

​
Creating the self-hosted organization

FlowX licensing provisions the organization and license for your deployment. After the platform is deployed, the Designer’s first-time Environment Setup wizard captures the environment name and organization-admin credentials, then completes provisioning automatically.
Environment Setup wizard with environment name and organization admin details
For environments where FlowX drives the installation, your FlowX representative leads this step. Self-installing operators receive the required values directly from FlowX licensing.
Outbound HTTPS connectivity to FlowX SaaS is required during provisioning. The wizard validates the license token and retrieves the subscription via the FlowX-provided endpoints. Without that connectivity the organization row is created and Keycloak realms are provisioned, but license validation fails. Restricted or air-gapped deployments must coordinate an offline-licensing path with FlowX before provisioning.
Manual Keycloak alternative. If your environment does not allow the self-hosted platform to administer Keycloak (no master-realm admin available), follow the Manual Keycloak Configuration recipe instead of the wizard. Realms, clients, and roles are then created manually in Keycloak; the platform reads them on first boot.

​
Deprecated: “Configure Environment Info”

The Configure Environment Info UI in Designer is no longer available. Environment naming now happens during organization registration with FlowX. The following API surface is changed; update any custom client tooling that relied on it:
  • PATCH /api/platform/environment. Endpoint removed.

​
Verify the configuration

After services boot on 5.9.x, confirm:
Every service shows the new Organization UUID in its startup logs (search for ORGANIZATION_ID log lines).
Designer → Platform Status shows all components at their 5.9.x target versions.
Liquibase migrations completed on every service. No service is in a “migration pending” state.
The license service is reachable from your network to FlowX SaaS. License validation succeeds and usage events are being published.
LLM_ENCRYPTION_MASTER_KEY is set to a non-default value before any LLM provider is configured.

v5.9.0 deployment guidelines

Component versions, third-party dependency versions, and the complete env var diff.

License engine setup

Full license service setup including PostgreSQL, Redis, and Kafka topology.

Organization manager setup

Deeper reference for organization-manager configuration.

Authentication & IAM migration

Prerequisite. The Keycloak transition that supports this configuration.
Last modified on June 26, 2026

Related topics

FlowX.AI 5.7.0 Release NotesRuntime authorization migrationDeployment guidelines v5.7.0FlowX.AI 5.8.0 Release NotesFlowX.AI 5.9.0 Release Notes