> ## 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 order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.
## Upgrading existing third parties
Update existing infrastructure to at least the new supported versions:
| Component | 4.7.8 | FlowX.AI 5.1.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.1.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.
***
## 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.1.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.1.0 to ensure workspace functionality works correctly.
### 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.
### Prerequisites for migration
Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:
```json theme={"system"}
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
### 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
### 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.1.0.
***
## Organization admin user
Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).
Details on how to configure the organization admin user:
***
#### Pre-migration preparation
You must configure the authorization-system service before migration. There are two supported approaches:
Set the following authorization-system environment variables:
* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.
Set the following environment variables:
* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
To get the subject ID of the admin user, 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.1.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",
"manage-realm"
]
}
}
```
***
## 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.