Serge Huber created UNOMI-884:
---------------------------------
Summary: Migration scripts
Key: UNOMI-884
URL: https://issues.apache.org/jira/browse/UNOMI-884
Project: Apache Unomi
Issue Type: Sub-task
Components: unomi(-core)
Affects Versions: unomi-3.0.0
Reporter: Serge Huber
Fix For: unomi-3.0.0
h1. Migration to Apache Unomi V3
h2. Summary
Implement and document the migration scripts required to successfully upgrade
existing Apache Unomi installations to V3.
h2. Description
Apache Unomi V3 introduces significant improvements to the data model,
particularly around audit fields and multi-tenancy support. Migration scripts
have been developed to handle the upgrade process from previous versions to
Unomi V3.
h2. Key Changes
h3. Audit Fields Enhancement
The migration introduces standardized audit fields across all item types:
* *createdBy*: Tracks who created the item
* *lastModifiedBy*: Tracks who last modified the item
* *creationDate*: Records when the item was created
* *lastModificationDate*: Records when the item was last modified
* *sourceInstanceId*: Tracks the source instance for data synchronization
* *lastSyncDate*: Records the last synchronization time
h3. Multi-Tenancy Support
Adds native multi-tenancy capabilities:
* Creates a new index specifically for tenant management ({{<prefix>-tenant}})
* Initializes a default tenant during migration
* Adds {{tenantId}} field to all items to associate them with specific tenants
* Ensures backward compatibility by setting default tenant for existing items
h2. Migration Scripts
Two primary migration scripts handle the transition to Unomi V3:
h4. 1. migrate-3.0.0-00-itemAuditFields.groovy
* Updates all indices with standard audit fields
* Performs specialized updates for profiles, sessions, and events
* Re-indexes data with updated mappings
h4. 2. migrate-3.0.0-10-tenantInitialization.groovy
* Creates the tenant index structure
* Initializes a default tenant
* Sets up the foundation for multi-tenant operations
h2. Technical Details
* The migration process uses Elasticsearch's update and reindex operations
* Painless scripts handle the transformation of existing data
* Default values are applied where historical information is unavailable
h2. Migration Process
# Backup existing Unomi data
# Stop existing Unomi instance
# Configure migration parameters (Elasticsearch addresses, index prefix)
# Run the migration using the Karaf console command: {{unomi:migrate
<previous_version>}}
# Start Unomi V3 after successful migration completion
h2. Testing Requirements
* Test migration from different versions (2.0, 2.5) to V3
* Verify data integrity after migration
* Validate multi-tenant operations in migrated environment
* Test backward compatibility with existing integrations
h2. Documentation Needs
* Update migration guide in official documentation
* Add section on multi-tenancy features and configuration
* Document new audit fields and their implications
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
