Introduction
SPMT stands for ‘SharePoint Migrator Tool’, which is a free tool for O365 subscription users, which helps in migrating the content from on-prem locations to Office 365 Teams, SPO, OneDrive locations. It comes as free of cost. This comes with a .exe tool that is available to SharePoint Admin or Tenant Admin. This tool can be shared with end-users allowing them to perform migration or this can be done by Global Admin or Tenant Admin by following the below guide. The best part is this migration comes free of cost. :)
In this article we will go through the following
- How to get this tool
- What is the recommended configuration
- How the tool works
- The tool architechture for migration
- Steps to perform the migration.
- Summay and references.
How To Get the Tool
One way is to download it from the
MSFT site at the below location.
The other way is that it is available to Global Admin or Tenant Admin via the admin portal. Then can go to the 'Admin Center' and in the quick launch under section 'migration', there is a direct link to download the tool.
Recommended Configuration
The below table shows the recommended configuration settings from MSFT for smooth and hassle-free migration.
Authentication Supported
This supports NTLM, Kerberos, ADFS, Multi-Factor Authentication, SAML, etc. Please note that if your on-prem server is configured to support Windows authentication, then windows authentication via this tool is not supported. More information can be found
here.
Sources that are supported by SPMT:
- SP2013 on-prem environment
- SP2016 on-prem environment
- SharePoint Server 2010 (Foundation and Enterprise editions)
- Local Folder
- Network Shared Folder
Destination
- Self Service Sites (Teams, Communication, O365 Groups)
- One Drive
- Stand-alone sites.
Tool Architechture
Below is the tool architechture.
Home Page of Migration Tool
Below is the home page of the migration. The very first time, you will see the below screen.
If you already performed previous migration and saved the schema, you will see the below screen with a 'Show saved migration' option. This will be used in doing migration using 'Incremental Mode'.
Modes in Migration
There are the following modes in the migration
Basic Mode
Which is self-driven by giving the users the option to select the source and destination and perform the migration. In the basic mode, the user will select the first 2 options as shown in the screen capture
Advanced Mode
In the advanced mode, users can have the CSV or JSON file created that have the following properties defined:
If you are planning to upload the migration job settings via CSV you need to make sure to have the following properties defined.
- Source
Required. Enter either a file share path or an on-premises SharePoint Server site URL.
- Source DocLib
Optional. Enter the name of the SharePoint Server document library you are migrating. If you leave this field empty, all document libraries will be migrated. If you are migrating a file share, leave this column empty.
- Source SubFolder
Optional. Enter the name of the subfolder in the document library. If this column is left empty, the migration starts from the root. If there is a value in this column, the migrations start from the subfolder and down. This column is used only for SharePoint Server sites. It is ignored for file share migration.
- Target Web
Required. Enter the SharePoint site URL where the files are to be migrated.
- Target DocLib
Required. Enter the name of the document library with the SharePoint site where the files are to be migrated.
- Target SubFolder
Optional. Enter the name of the subfolder in the document library. If this column is left empty, then the files will be moved to the root level.
If you are using the JSON for your migration Job, you need to have the following properties defined
- SourcePath
path of the local share. Please note that you need to append extra ‘\’ for escape characters
- TargetPath
The URL of the o365 (Teams, SPO, Office 365 groups)
- TargetList
The name of the document library. It should be an internal list name.
- TargetListRelativePath
If there is internal folder structure Documents\\Parent1\\Parent2
Incremental Mode
This incremental mode gives the option of running an updated migration on a saved migration template. Whenever the migration is complete while running in basic mode and advanced mode, the user will get the option to save the current migration schema. Once this schema is saved, it will be shown in the ‘Saved Migrations’ option which will appear at the start of the tool.
User Mapping
User mapping is avaialble here in the advanced settings. Here, you can have the existing users from local share or SharePoint locations to be replaced/updated with another user entry in SPO. For instance, the ideal case is if you have files from a local share from one of the users who left the company their accounts can be replaced with any existing service accounts or user accounts. By default, it will be mapped to ‘BUILTIN\Administrators’ if no mapping is given.
For instance, when the files are stored in the ‘Shared Drives’ the author filed will be mapped to ‘BUILTIN\Adminstrators’, in the user mapping csv you can update to account in Azure AD in the following format.
- Column A: Enter the login name/author from the source. This value is required.
- Column B: Enter the upn/email of the user where the value needs to be mapped in O365. This value is required.
- Column C: Enter ‘TRUE’ if the account exists in AD. Enter ‘FALSE’ if the account does not exist in Azure AD.
This is mostly in the cases when migrating from SharePoint On-Prem to O365, where some of the users left the company, then we can map the inactive accounts with active accounts and upload the user mapping file before the migration starts.
Performing Migration
After all the settings are configured, you can start the migration by clicking on ‘Migrate’.
During the process, it will display the status and you can view the reports. This will be useful mainly in long-running migrations. The reports will be stored at c:\users\userid\appdata\local\roaming\microsoft\
Types of Migration
Currently, this tool supports following types of migrations
- One to One
Where you have a single source and a single destination. The source and destinations could be from any of the supported environments that are mentioned in the beginning.
- Many to One
Where the migration can have multiple sources, which are supported, and the destination could be one single location.
- Many to Many
Where the migration can have multiple sources and multiple destinations within the same site collection or multiple site collections. Here for instance you multiple sources from On-Prem, Shared drive and then destination can be multiple locations such as O365 groups, SPO, Teams, OneDrive.
Issues
The following are the issues that were being experienced during the migration operation.
Unable to sign in with org ID
When trying to sign in to SPMT tool, it is giving the following message 'Unable to sign in'. Below is the screen capture for your reference.
This is due to the TLS 1.2 channel where MSFT supports all the authentication APIs via TLS 1.2. To update the settings, go default browser in server / local machine and under security make sure the Tls1.2 security channel option is checked.
After that restart the tool, it should take you to the authentication window where you need to enter your UPN and password.
Migration Job stuck
Migration job stuck for 2 hours and then the following error occurs which says ‘several packages failed to upload. Pause the task (ErrorCode: 0x02070009).
Error Message
2020-07-28 17:26:35.3765|DEBUG|GLB|ARIA|Request to send message.
2020-07-28 17:26:35.3765|DEBUG|GLB|ARIA|Request to send message.
2020-07-28 17:26:35.3765|ERROR|GLB|5|Csom call with TraceCorrelationId 5b9b6a9f-e022-b000-422f-26df08d3da91 from SPO
Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPServerException: Server Issue when doing SP Query ---> Microsoft.SharePoint.Client.ServerException: Current user is not a tenant administrator.
at Microsoft.SharePoint.Client.ClientRequest.ProcessResponseStream(Stream responseStream)
at Microsoft.SharePoint.Client.ClientRequest.ProcessResponse()
at Microsoft.SharePoint.Client.ClientContext.ExecuteQuery()
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.WrapExceptions(Action logicToRetry)
--- End of inner exception stack trace ---
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.WrapExceptions(Action logicToRetry)
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.ExecuteQuery(String callerMemberName, String callerFilePath)
2020-07-28 17:26:35.3765|DEBUG|GLB|ARIA|DispatchMessages - Done. Count:2
2020-07-28 17:26:35.3765|DEBUG|GLB|ARIA|DispatchMessages - Done. Count:0
2020-07-28 17:26:35.4220|ERROR|GLB|5|Could not get tenant setting for user
[email protected] Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPServerException: Server Issue when doing SP Query ---> Microsoft.SharePoint.Client.ServerException: Current user is not a tenant administrator.
at Microsoft.SharePoint.Client.ClientRequest.ProcessResponseStream(Stream responseStream)
at Microsoft.SharePoint.Client.ClientRequest.ProcessResponse()
at Microsoft.SharePoint.Client.ClientContext.ExecuteQuery()
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.WrapExceptions(Action logicToRetry)
--- End of inner exception stack trace ---
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.WrapExceptions(Action logicToRetry)
at Microsoft.SharePoint.MigrationTool.MigrationLib.SharePoint.MigSPClientContext.ExecuteQuery(String callerMemberName, String callerFilePath)
Reason
This issue happens due to the following reasons:
- Throttling enforced by MSFT during peak hours or to have stability on overall tenant features
- Network slowness at your local network or corporate network. The VPN has oftentimes slower network speeds which could cause this operation.
- The upload limits enforced by your local ISP which could have the job stuck in the middle.
The fix is to run the migration from the server where the Shared Drive is hosted. I'm not sure if this is practical all the time. If that isn’t possible then try to map the Shared Drive from one of the VM which is LAN connected or running the migration on PC which is LAN connected. I tried the former approach and it looks promising.
Here, the test was done with 25 GB of migration. Even though it took around 3 hours, it finished successfully.
The folder you selected doesn’t exist:
If there is formatting wrong in json or the target and source destinations are not given properly this issue occurs. Please ensure that source and destinations or correct and the file is valid json. Also, refer to the section ‘Advanced Mode’ and
this link that talks about how to format your CSV/JSON file for migration.
The source parameter in CSV is not defined properly:
Check the source and see if this is accessed or not. Again make sure the network shares are accessible and the formatting is done correctly. Refer to this
link for more information.
Migrating OneNote
When migrating OneNote Notebook from a shared location, it is required to have the setting ‘Migrate OneNote Folder as OneNote notebook’ is set to ‘On’. By default, it is set to ‘Off’. Please note that this comes under ‘Advanced settings’ which can be opened by ‘View all settings’ before the migration is started.
Below is the screen capture when set to On. Once done, click on ‘Save’.
Points to Consider
- This tool is not available in China with O365 powered by 21vianet.
- Recommended running off the business hours and higher network speed.
- If there is more than 100 TB of migration, we need to open a service request with MSFT before we start the operation.
- There is a special setting in one note. This is an advanced setting in the tool, which needs to be checked by end-user before starting the migration operation.
Summary
Thus in this article we have gone through process of migrating the on-prem data from to O365 cloud using the SharePoint Migration Tool from Microsoft.
References
- https://docs.microsoft.com/en-us/sharepointmigration/sharepoint-online-and-onedrive-migration-speed
- https://docs.microsoft.com/en-us/sharepointmigration/spmt-prerequisites
- https://docs.microsoft.com/en-us/sharepointmigration/migrate-onenote-spmt
- https://docs.microsoft.com/en-us/sharepointmigration/how-to-use-the-sharepoint-migration-tool
- https://docs.microsoft.com/en-us/sharepointmigration/how-to-format-your-csv-file-for-data-content-migration