Tenant Migration
Tenant migration is an advanced modular feature introduced in version 26.3
Introduction
Tenant migration allows a record to be moved from one organisation to another. This covers both the record's metadata and its underlying files (originals and previews).
Schematic
How the migration works
The migration happens in two phases:
Metadata: moved immediately and transactionally. As soon as the migration is triggered, the record belongs to the target organisation.
Data (originals and previews): moved asynchronously in the background after the metadata migration completes. This part is optional.
All inputs are validated upfront. If any validation fails, the migration is rejected before anything is changed. The API response always returns the migrated record in its updated state.
Request parameters
Only the target organisation is required. All other parameters are optional and have automatic fallback behaviour.
Target organisation (required): the organisation the record is being moved to.
Migrate data (optional): migrate the original and access/browse files to the new organisation as well
New parent record (optional): a parent record belonging to the target organisation. If omitted, the target organisation's default classification is used automatically.
Zone (optional): a zone belonging to the target organisation. If omitted, the zone is managed automatically based on the record's phase (see field policies below).
Permissions (optional): new permissions for the record. If omitted, permissions are inherited from the new parent record
Worker daemon zone (optional): operate in one of the specific https://mediahaven.atlassian.net/wiki/spaces/CS/pages/4890722313
Tape migration cluster group (mandatory if the source organisation has tape storage): When the data is migrated for records stored on tape, use this cluster group as the intermediate storage, such that the https://mediahaven.atlassian.net/wiki/spaces/CS/pages/2738389023 will write the record to a new set of tapes
What happens to each field
Field | What happens |
|---|---|
Parent record | If provided, must belong to the target organisation (or be a primary-org classification when the index is shared). If omitted, the target organisation's default classification is used. |
Permissions | If provided in the request metadata, applied as-is. If omitted, inherited from the new parent record. |
Profiles | Cleared when the parent changes. |
Zone | If the record has no zone, left empty. If the record has a zone and no zone is provided: concepts automatically receive the target organisation's default zone; non-concept records have their zone cleared. If a zone is provided explicitly, it must belong to the target organisation. |
Limited categories | Automatically cleared. These concepts are organisation-specific and would not exist in the target thesaurus. |
Organisation | Automatically set to the target organisation — no input needed. |
Statusses | Normally, the record status of the object is unmodified, unless the object is written to tape; then the record status reverts to |
Children and grandchildren
When a migrated record has children, the system automatically creates new Batches to migrate its children to the same target organisation. The children are migrated with the same settings (zone, data migration, etc.), and their parent remains unchanged.
Auditing
The tenant migration generates distinct Events
RECORDS.UPDATE.MIGRATE_TENANTwhen the metadata has been migrated (synchronous with the migration API call)RECORDS.FLOW.MIGRATED_TENANT_STORAGEwhen the data has been migrated
What cannot be migrated
A record cannot be migrated if its ingest has not yet completed.
Required permissions
To trigger a migration, all three of the following must be satisfied:
The Edit All Organisations admin function (
ADMIN_EDIT_ALL_ORGANISATIONS).Write access to the record.
The Migrate Tenants module plugin must be active for the user's organisation.