Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

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:
ScenarioIs ORGANIZATION_ID required?What happens
Upgrade from 5.1.x (this guide)Required on the 9 services aboveLiquibase backfills organization_id on existing rows with your UUID, then enforces NOT NULL. Missing → migration fails.
Fresh 5.9.x install (empty databases)Not requiredEach affected Liquibase changeset pre-checks for rows; with no rows to backfill, it skips the value-required step.
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.
Environment VariableDescriptionDefault Value
ORGANIZATION_IDOrganization UUID issued by FlowX. Liquibase backfill parameter on the 9 services above.- (FlowX-provided)

​
The license service uses a separate env var

The license service does NOT read the Liquibase ORGANIZATION_ID parameter. Instead, it consumes FLOWX_LICENSE_ORGANIZATION_ID 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.

​
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:
Environment VariableDescriptionDefault Value
FLOWX_LICENSE_KEYLicense key issued by FlowX. Required — without it the license service cannot authenticate to FlowX SaaS, and the wizard’s token validation step fails.-
FLOWX_LICENSE_ORGANIZATION_IDOrganization UUID issued by FlowX. Same value used as the ORGANIZATION_ID Liquibase parameter. The default notset must be replaced before the license service starts.notset
FLOWX_LICENSE_AUTH_SERVER_URLAuth endpoint provided by FlowX licensing.-
FLOWX_LICENSE_SERVER_URLLicense API endpoint provided by FlowX licensing.-
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:
Environment VariableDescriptionDefault ValueComponent
DEFAULT_ORGANIZATION_NAMEOrganization code registered with FlowX. Used for Designer routing and display.''designer
FLOWX_DEFAULT_DESIGNER_HOME_URIURL of the Designer container app served to this deployment.-organization-manager
FLOWX_DEFAULT_RUNTIME_HOME_URIURL of the generic runtime container app served to end users.-organization-manager
FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URISComma-separated list of redirect URIs allowed on the user realm. If empty, derived from the Designer/Runtime home URIs above.[]organization-manager
SECURITY_OAUTH2_BASE_SERVER_URLSelf-hosted Keycloak base URL.-organization-manager
SECURITY_OAUTH2_PUBLIC_SERVER_URLPublic-facing Keycloak URL. Falls back to SECURITY_OAUTH2_BASE_SERVER_URL if unset.-organization-manager
LLM_ENCRYPTION_MASTER_KEYMaster key used to encrypt AI Provider credentials at rest. Change from default before production.default-dev-key-change-in-prodorganization-manager
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_HOME_URI) 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 legacy env vars are deprecated and still read for backward compatibility. Plan to remove them once organization registration is complete:
Environment VariableReplaced by
FLOWX_CLIENT_NAMERegistered organization code (DEFAULT_ORGANIZATION_NAME)
FLOWX_ENVIRONMENT_NAMECaptured during organization registration; no env var equivalent
The following API surface is changed; update any custom client tooling that relied on it:
  • PATCH /api/platform/environment. Endpoint removed.
  • /api/init response. The environmentDetails section is deprecated; values now come from organization registration rather than the legacy env vars. The field continues to be returned during the upgrade window.

​
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 2, 2026