​
Redis cache clearing

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.

​
Endpoint

POST {{baseUrlAdmin}}/api/internal/cache/clear

​
Body:

{
    "cacheNames": [
        "flowx:core:cache"
    ]
}

Clear cache endpoint

​
Authentication & authorization

​
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.
This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

​
Role mapping guide

FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

Legacy Role Mapping

FlowX.AI 4.7.x → FlowX.AI 5.0
  • FLOWX_ADMIN → workspace_admin
  • FLOWX_CONFIGURATOR → workspace_user or project_editor
  • FLOWX_UI_DESIGNER → theme_editor
  • FLOWX_VIEWER → project_viewer
  • Custom Keycloak roles → Manual review required

Migration Considerations

Important Changes
  • Roles are now workspace-scoped
  • More granular permission structure
  • Database-stored instead of token-based
  • New role hierarchy requires review

​
Migration process

1

Inventory Current Roles

Document all existing Keycloak roles and their assigned users before migration
2

Map to New Structure

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs
3

Plan Workspace Structure

Decide how to organize users into workspaces based on business requirements
4

Assign New Roles

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces
5

Validate Access

Test user access to ensure proper permissions are granted and restrictions are enforced

​
For existing customers

1

Automatic Default Workspace Creation

The auth-system will automatically:
  • Create default organization and workspace
  • Import the admin user from Keycloak
  • Assign organization admin privileges
  • Set up default roles and groups
2

data-sync Migration Process

The data-sync service will:
  • Migrate existing projects from app-manager database to CAS database
  • Assign all existing resources to the default workspace
  • Preserve all existing functionality
  • Require temporary write access to CAS database
Note: This is the only exception to the exclusive write access rule.

​
Header migration: Fx-BuildId to Fx-Build-App-Version-Id

​
Background

The header Fx-BuildId has been renamed to Fx-Build-App-Version-Id to accurately reflect that it contains an application version identifier, not a build identifier.

​
Migration strategy

During the transition period, both headers are supported:
  • New messages: Include Fx-Build-App-Version-Id with the application version ID
  • Legacy support: Fx-BuildId is still accepted for backward compatibility
  • Priority: FlowX.AI platform reads Fx-Build-App-Version-Id first, then falls back to Fx-BuildId if not present

​
Implementation guidelines

  1. New integrations: Use Fx-Build-App-Version-Id header
  2. Existing integrations: Will continue to work during migration period
  3. Client considerations: Existing client instances may continue sending Fx-BuildId until they are updated

​
Timeline considerations

Client applications with long-running instances may continue using the legacy Fx-BuildId header until those instances complete their processes and are updated to use the new header format.