Migrating the term store (taxonomy) between tenants
A managed metadata column does not store a label but a term ID. If the term does not exist in the target with the right ID, the value is lost.
Short answer
Global term groups are recreated in the target with the same GUIDs, so values stay valid with no translation. Groups that belong to a site collection get new GUIDs, and a mapping table is applied to columns and values.
Two kinds of group
| Global group | Site collection group | |
|---|---|---|
| Where it lives | The tenant term store | Attached to a site collection |
| In the target | Recreated with the same GUIDs | Copied into the target site’s local group, new GUIDs |
| Columns and values | Valid as they are | Re-mapped with the mapping table |
| Within one tenant | Shared: nothing to migrate | Migrated to the target site |
Choosing what is migrated
Four modes: none, global, site collection, or both. For global groups, list those to include or exclude; system groups (People, Search Dictionaries, System) are excluded by default. The taxonomy-list command shows the source groups to help prepare the list.
Order matters
- TaxonomyTerms exist in the target.
- StructureManaged metadata columns are created and point to the right term sets.
- ContentValues are written with term IDs that exist.
Running content before taxonomy produces empty columns. The tool runs the phases in this order; a phase run on its own assumes the previous ones have run.
Prerequisites
- The migration account is term store admin in the target tenant.
- Term sets already created by hand in the target with other GUIDs are not merged: clean them up first, or exclude those groups.
Frequently asked questions
What happens to a value whose term was not migrated?
Are term translations kept?
Test it on your own tenant
The 14-day trial migrates 10% of every library, with versions, metadata and permissions. After you subscribe, an incremental run migrates the rest.