> ## 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.
# Prerequisites
> This section contains the steps in the order 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+** |
***
## 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 installing DGraph. SpiceDB is still mandatory.
***
## 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 run two operations on all existing Elasticsearch indices:
1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)
These operations are 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
```json theme={"system"}
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:
```json theme={"system"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```
Monitor async tasks with:
```json theme={"system"}
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:
```json theme={"system"}
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
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:
Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./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`= `` (recommended method, default: `admin@flowx.ai`)
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`= ``
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:**
```json theme={"system"}
{
"clientRoles" : {
"realm-management" : [
"manage-users",
"query-users",
"view-users"
]
}
}
```