Step 6: Start a OneDrive cross-tenant migration
This is Step 6 in a solution designed to complete a Cross-tenant OneDrive migration. To learn more, see Cross-tenant OneDrive migration overview.
- Step 1: Connect to the source and the target tenants
- Step 2: Establish trust between the source and the target tenant
- Step 3: Verify trust has been established
- Step 4: Precreate users and groups
- Step 5: Prepare identity mapping
- Step 6: Start a Cross-tenant OneDrive migration
- Step 7: Post migration steps
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.
Ensure you have 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]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 above command with the one of the following parameters.
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.
| Parameter | Description |
|---|---|
| PreferredMoveBeginDate | The migration will likely begin at this specified time. Time must be specified in Coordinated Universal Time (UTC). |
| PreferredMoveEndDate | The migration will likely be completed by this specified time, on a best effort basis. Time must be specified in Coordinated Universal Time (UTC). |
OneDrive status premigration
Before you start the migration, the users current source OneDrive status is similar to the example below. This example is from the users source tenant, showing their current files and folders.
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 hasn't yet 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 and will start the Migration 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 have completed and has been 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 has successfully migrated to the target tenant, they no longer have an active OneDrive account on the source.