​
Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:
Component4.7.6FlowX.AI 5.0
Kafka3.2 - 3.93.8 - 3.9
Redis7.2 - 8.07.4 - 8.0
Elasticsearch7 - 98 - 9
Keycloak22,26+26+

Third parties components versions

​
Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.
  • SpiceDB - Required for authorization management (Must be accessible by the authorization-system service)
  • DGraph - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don’t have an AI deployment), you can skip this step.

SpiceDB setup guide

​
Elasticsearch workspace migration

The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment. This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0. Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.
Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.0 to ensure workspace functionality works correctly.

​
Prerequisites for migration

Before upgrading to FlowX.AI 5.0, you must update the mappings for all existing Elasticsearch indices to include the workspaceId field: 
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
This mapping update is required for:
  • Process instances indices (you can find the indices in the flowx-process-engine setup guide at FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME environment variable, if not set, the default is process_instance)
  • Audit log indices (you can find the indices in the audit-core setup guide at SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM environment variable)

​
Migration execution methods

You can execute these migration queries using:
  • Kibana Dev Tools: Execute queries directly in the Kibana interface
  • Elasticsearch API: Use direct API calls to perform migrations

​
Migration timing

Recommended approach: Complete these Elasticsearch migrations before upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

​
Process instances migration

Process instances indices require manual migration using Elasticsearch’s update_by_query API to assign them to the default workspace:

​
Synchronous migration

POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}

​
Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration: 
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
Monitor async tasks with: 
GET /_tasks/{task_id}

​
Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace: 
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}

​
Performance optimization

  • Use slices=auto for automatic parallelization based on primary shards
  • For multiple indices, use patterns: POST /my_pattern-*/_update_by_query?slices=auto
  • Batch processing with size parameter: ?size=1000
  • Monitor large operations using asynchronous execution

​
Post-migration impact

Without proper Elasticsearch migration, you will experience:
  • Some process instances may not appear in search results
  • Data-search functionality may not return complete results
  • Workspace-scoped queries will fail for unmigrated data
  • Existing resources will not be visible or accessible within the new workspace structure

​
Default workspace ID

The migration uses the default workspace ID: 00000000-0000-0000-0000-000000000001 All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

​
Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the Install Services section). Details on how to configure the organization admin user:

Authorization system

Workspaces access rights

​
Pre-migration preparation

Required configuration for the authorization-system service:
  • SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE= true (mandatory for migrations)
  • SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID= <subject-id-of-admin-user> (mandatory for migrations)
To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.
JWT token
Make sure the admin user is created in Keycloak before deploying the authorization-system service.

​
Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.
All service accounts used by FlowX.AI services must have the SA_FLOWX role assigned. Services will not authenticate properly without this role.
—

​
Additional Keycloak roles requirements for authorization-system service

Before deploying the authorization-system service, you must assign additional roles to its service account in Keycloak to enable user management operations. Required client roles for the service account: 
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}

​
Process instances migration

All active process instances will be migrated under default workspace.
For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.