Step 6: Start a SharePoint site cross-tenant migration (preview)
Note
Cross-Tenant SharePoint migration is currently in a private preview stage of development. As an unfinished project, any information or availability is subject to change at any time. Support for private-preview customers will be handled via email. Cross-Tenant SharePoint migration is covered by the preview terms of the Microsoft Universal License Terms for Online Services.
This is Step 6 in a solution designed to complete a Cross-tenant SharePoint migration. To learn more, see Cross-tenant SharePoint migration overview.
- Step 1: Connect to the source and the tarIPs tenants
- Step 2: Establish trust between the source and the target tenant
- Step 3: Verify trust has been established
- Step 4: Pre-create users and groups
- Step 5: Prepare identity mapping
- Step 6: Start a Cross-tenant SharePoint migration
- Step 7: Post migration steps
Now you're ready to start your SharePoint migration. Before starting any cross-tenant migration, do the following steps.
Start a SharePoint Cross-tenant site migration
Make sure you've verified the compatibility status. If you see a status of either Compatible or Warning on your source tenant, you may 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-SPOCrossTenantSiteContentMove-SourceSiteUrl <…> -TargetSiteUrl <…> -TargetCrossTenantHostUrl <…>Parameters Description SourceSiteUrl Full URL of the SharePoint Site of the Source tenant, for example: https://sourcetenant.sharepoint.com/sites/sitename.TargetSiteUrl Full URL of the SharePoint Site of the Target tenant, for example: https://targettenant.sharepoint.com/sites/newsitename.TargetCrossTenantHostUrl The Cross-tenant host URL of the target tenant. The target tenant Admin can determine the TargetCrossTenantHostUrl by running Get-SPOCrossTenantHostUrl on their tenant.
Start a SharePoint Microsoft 365 Group connected site cross-tenant migration
Ensure to verify the compatibility status. If you see a status of either Compatible or Warning on your source tenant, you may 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-SPOCrossTenantGroupContentMove -SourceGroupAlias <…> -TargetGroupAlias <…> -TargetCrossTenantHostUrl <…>Parameters Description SourceGroupAlias Alias of the Microsoft 365 Group connected to the SharePoint Site on the Source tenant. For example: SourceGroup1 TargetGroupAlias Alias of the Microsoft 365 that was created on the target tenant TargetCrossTenantHostUrl The Cross-tenant Host URL of the target tenant. The target tenant Admin can determine the TargetCrossTenantHostUrl by running Get-SPOCrossTenantHostUrl on their tenant
Schedule a migration for a later time
To schedule a migration for a later time, add one of the following parameters to the command.
For example:
Start-SPOCrossTenantGroupContentMove -SourceGroupAlias <…> -TargetGroupAlias <…> -TargetCrossTenantHostUrl <…> -PreferredMoveBeginDate <…>
These commands can be useful when planning bulk batches of site migrations. You can queue and migrate up to 4,000 migrations per batch. If your count exceeds 4,000, then separate batches can be created and scheduled 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). |
SharePoint status pre-migration
Before you begin the migration, the users current source SharePoint status will be similar to the following. This example is from the users source tenant, showing their current files and folders.
Cancelling a SharePoint site migration
You can stop the cross-tenant migration of either a SharePoint site or SharePoint Microsoft 365 Group by using the following command, provided the migration doesn't have a status of In Progress or Success.
To cancel a SharePoint site migration:
Stop-SPOCrossTenantSiteContentMove – SourceSiteURL [URL of Site you wish to stop]
To cancel a SharePoint Microsoft 365 Group migration:
Stop-SPOCrossTenantGroupContentMove – SourceGroupAlias [Alias of Group connected to site you wish to stop]
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 pre-flight 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 has 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 has successfully completed, check the status of the user on the target tenant by logging into their new SharePoint account.
Source tenant: Once the user has successfully migrated to the target tenant, they no longer have an active SharePoint account on the source.