You can only upgrade from version 4.7.6 to 5.0.0. If you’re on an earlier version, upgrade to 4.7.6 first.

​
Success factors

Take care when following steps are mandatory and will prevent service startup if skipped:
  1. SpiceDB and DGraph must be installed before any FlowX.AI services
DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
  1. Organization admin user must be configured before authorization-system service deployment
  2. Service accounts must have SA_FLOWX role assigned
  3. Data migration must complete before service upgrades

​
Migration process

Follow these steps in the exact order specified to ensure a successful migration:
1

Prerequisites

​
Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

​
Installing new third parties

New mandatory infrastructure components:
  • SpiceDB - Authorization and permission management backend
  • DGraph - Graph-based data operations and relationships

​
Upgrading existing third parties

Update existing infrastructure to the new supported versions:
  • Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

​
Organization admin user

Configure the organization admin user before deploying the authorization-system service.

​
Service accounts

Assign SA_FLOWX role to all service accounts used by FlowX services.

Prerequisites

See the details on prerequisites for migration
2

Installing new services

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.Required installation sequence:
  1. Authorization System (CAS) - Must be installed first to validate SpiceDB connection
  2. NoSQL DB Runner - Backend service for FlowX.AI Database
Service Startup Dependency: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

Install services

Step-by-step installation with validation procedures
Installing Authorization System first allows you to validate all critical configurations before proceeding.
3

Update environment variables

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.Configuration updates include:
  • New Kafka topics and consumer groups
  • Updated Elasticsearch settings and index configurations
  • Enhanced security and authorization parameters
  • New service integration endpoints

Update environment variables

Update environment variables for all existing FlowX.AI services
4

Install new versions for existing services

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.
5

Container apps (Renderers SDKs)

Container apps (Renderers SDKs)

See the details on container apps (Renderers SDKs)
6

Post-deployment steps

Perform the post deployment steps:
  • Validate data-sync migrations
  • Clear cache with endpoint
  • Remove deprecated configuration roles (optional)
  • Add users to default workspace

​
Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

​
Clear cache with endpoint

Required: Clear Redis cache using the dedicated endpoint with organization admin token.
Cache Clearing:
  • FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
  • After the library-to-library migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document, which is required for various operations.

​
Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

​
Add users to default workspace

Process:
  1. User Re-login: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
  2. Workspace Assignment: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources
Access Restoration: Without workspace assignment, existing users will lose access to previously available resources and projects.

Post-deployment configuration

Complete post-deployment procedures and validation