Edit

Share via


Step 6: Start a OneDrive cross-tenant migration

This article is Step 6 in a solution designed to complete a Cross-tenant OneDrive migration. To learn more, see Cross-tenant OneDrive migration overview.

Important

Microsoft recommends that you use roles with the fewest permissions. Using lower permissioned accounts helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role.

Now you're ready to start your OneDrive migration. Before starting any cross-tenant migration, do the following steps.

  1. Make sure you verified the compatibility status. If you see a status of either Compatible or Warning on your source tenant, you can continue. Run:

    Get-SPOCrossTenantCompatibilityStatus –PartnerCrossTenantHostURL [Target tenant hostname]
    
  2. To start the migration, a SharePoint Admin or Microsoft 365 Global Admin of the source tenant must run the following command:

Start-SPOCrossTenantUserContentMove -SourceUserPrincipalName <...> -TargetUserPrincipalName <...> -TargetCrossTenantHostUrl <...>
Parameters Description
SourceUserPrincipalName User principal name of the user who owns the OneDrive on the Source tenant.
TargetUserPrincipalName User principal name of the user who owns the OneDrive on the Target tenant.
TargetCrossTenantHostUrl The Cross-tenant Host URL of the target tenant. To find the TargetCrossTenantHostUrl, run Get-SPOCrossTenantHostUrl on the tenant.

Example:

Start-SPOCrossTenantUserContentMove -SourceUserPrincipalName DiegoS@M365x016651.OnMicrosoft.com -TargetUserPrincipalName Test-Diego@M365x946316.OnMicrosoft.com -TargetCrossTenantHostUrl https://m365x946316-my.sharepoint.com/ 

To Schedule a migration for a later time, you can use and append the previous command with the one of the following parameters:

Parameter Description
PreferredMoveBeginDate The migration likely begins at this specified time. Time must be specified in Coordinated Universal Time (UTC).
PreferredMoveEndDate The migration likely completes by this specified time, on a best effort basis. Time must be specified in Coordinated Universal Time (UTC).

These commands can be useful when planning bulk batches of OneDrive migrations. You can queue/migrate up to 4,000 OneDrive migrations per batch. If your user count exceeds 4,000, create separate batches, and schedule them to run once the current batch is close to completion.

OneDrive status premigration

Before you start the migration, the users' current source OneDrive status is similar to the following screenshot. This example is from the users' source tenant, showing their current files and folders.

A screenshot showing a premigration status. There are files and folders displayed in a window, and a red box is drawn around the address of the OneDrive.

Cancelling a OneDrive migration

You can stop the cross-tenant migration of a user's OneDrive by using the following command, provided the migration doesn't have a status of In Progress, Rescheduled, or Success.

Stop-SPOCrossTenantUserContentMove – SourceUserPrincipalName [UPN name of user who you wish to stop]

Example:

Stop-SPOCrossTenantUserContentMove – SourceUserPrincipalName DiegoS@M365x016651.OnMicrosoft.com

Determining current status of a migration

After starting your migration, you can check its status using the following command on either the source OR target tenant:

Source command format:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL [Target URL]

Example:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL https://m365x946316-my.sharepoint.com/

Target command:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL [Source URL]

Example:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL https://m365x016551-my.sharepoint.com/

To find the status of a specific user's migration, use the SourceUserPrincipalName parameter:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL <PartnerCrossTenantHostURL> -SourceUserPrincipalName <UPN>

Example:

Get-SPOUserAndContentMoveState -PartnerCrossTenantHostURL https://m365x946316-my.sharepoint.com -SourceUserPrincipalName DiegoS@M365x016651.OnMicrosoft.com

To get the status of the move based on a particular user's UPN but with more information, use the -Verbose parameter.

Example:

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL https://ttesttenant-my.sharepoint.com -SourceUserPrincipalName User3@stesttenant.onmicrosoft.com -Verbose 

Migration States

Status Description
NotStarted The migration isn't started.
Scheduled The migration is now in the queue and is scheduled to run when a slot becomes available.
ReadytoTrigger The Migration is in its preflight stage. The Migration starts shortly.
InProgress The migration is in progress in one of the following states:
- Validation
- Backup
- Restore
- Cleanup
Success The Migration completed successfully.
Rescheduled The migration may not be completed and is requeued for another pass.
Failed The migration failed to complete.

Post-migration status checks

Target tenant: After the migration successfully completes, check the status of the user on the target tenant by logging into their new OneDrive account.

Source tenant: Since the user was successfully migrated to the target tenant, they no longer have an active OneDrive account on the source.

Step 7: Post migration steps