Prerequisites

This section contains the steps in the order that we recommend for migrating data from FlowX v4.7.x to v5.0.0.

Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

Component	4.7.6	FlowX.AI 5.0
Kafka	3.2 - 3.9	3.8 - 3.9
Redis	7.2 - 8.0	7.4 - 8.0
Elasticsearch	7 - 9	8 - 9
Keycloak	22,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.

Before upgrading to FlowX.AI 5.0, you must update the mappings for all existing Elasticsearch indices to include the workspaceId field to ensure workspace functionality works correctly:

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

Note:
If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also 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.

---

Authorization System Prerequisites

Before deploying the authorization-system service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

Bootstrap Organization Admin

Organization Admin Roles & Workspace Access

Tip: Configuration of the organization admin user must be completed before deploying the authorization-system service (see the Install Services section for service deployment steps).

---

Pre-migration preparation

Required configuration for the authorization-system service:

• SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE= true (mandatory for migrations)
• SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME= <admin-username> (recommended method, default: [e-mail])

The system will search for this username in Keycloak and automatically copy the user’s subject ID to the authorization-system database.

Fallback method: If the username method fails or you prefer to specify the subject ID directly:

• SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID= <subject-id-of-admin-user>

To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

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"
    ]
  }
}