The Importance of Translation tables for migration tools

In tenant-to-tenant (T2T) and Google-to-Microsoft 365 migration projects, maintaining accurate identity relationships is essential for ensuring data integrity, continuity, and security. Migration tools such as AvePoint rely heavily on mapping files (sometimes called translation tables) to link source objects to their target equivalents. Without accurate mappings, permissions break, content fails to align, and migrated users may lose access to their own data. 

What is a mapping file? 

A mapping file is typically a CSV document that defines the relationship between a source object and its corresponding target object. In most cases, this is a mapping between User Principal Names (UPNs), but it can also include: 

• Distribution or Microsoft 365 Groups 

• Shared mailboxes 

• Teams identities 

• Workstation or endpoint identities 

Mapping files are indispensable in scenarios such as mergers, acquisitions, divestitures, cloud consolidation, and crossplatform migrations—including Google Workspace to Microsoft 365. 

Who uses the mapping file and when? 

Mapping files are used primarily by migration engineers throughout the entire lifecycle of a migration project. They play a crucial role in: 

• Prestage migrations 

• Permission and content validation 

• Final cutover 

• Postmigration cleanup and verification 

The mapping file acts as the single source of truth for object correlation, ensuring that every identity from the source is correctly resolved in the target tenant. 

When Should the Mapping File Be Created? 

The mapping file is generated from the Master Migration List (MML), which is a consolidated record created after discovery, assessment, and scoping activities with the client. Once the target tenant has been provisioned and the migration scope finalised, the mapping file can be produced. Although created early, it often requires adjustments closer to cutover to reflect lastminute identity or domain changes. 

Identity mapping requirements and UPN behaviour 

AvePoint and similar tools primarily rely on the User Principal Name as the identity anchor. A typical entry might look like: 

• Source_UPN: ismail.sokolaj@nzo.com 

• Target_UPN: ismail.sokolaj@saiglobal.com 

During a migration, UPNs may change—especially when domains are removed or reassigned. In some cases, source UPNs default back to their MOERA format (e.g., name@tenant.onmicrosoft.com) prior to cutover. The mapping file must always reflect the correct UPN for the migration phase to avoid failed permission mapping or orphaned objects. 

Summary 

Mapping files are a foundational component of Migration tool driven migrations, underpinning identity correlation, permission translation, and a seamless user experience. Created early and maintained throughout the project, they provide the stability and accuracy required for controlled and reliable tenant migrations—whether moving from Microsoft 365 to Microsoft 365, or transitioning from Google Workspace.