SharePoint to SharePoint Online Document Library Migration Guide (including Microsoft 365 Groups)

This article outlines the workflow for migrating document libraries from a SharePoint source tenant to SharePoint Online destination tenant. This migration requires licenses.  This guide may also be used to migrate Microsoft 365 Groups (Documents) and File Share instances. 

If this is your first time performing a migration, we have created a Migration Planning & Strategy Guide to walk you through planning, set-up, and general migration best practices. If you have never performed a migration before, we suggest reading that before beginning the steps outlined in this scenario. 

MigrationWiz is a migration tool, not a syncing tool. We do not have “live” monitoring of changes (as with a sync agent) and we cannot handle scenarios such as conflict resolution without user interaction. 

Due to limitations on connections allowed by GoDaddy, we do not support migrating to or from GoDaddy using this migration type.

GCC High and MFA

We are not able to support migrations with 2-factor or multifactor authentication. This endpoint does not support GCC High migrations at this time. 

Information about the types of item migrated with this scenario, including metadata and versions, can be found in the following dropdown. More information about metadata and versions is found later in the article.

Microsoft 365 Groups (Document) Migrations

Effective June 28, 2021, Microsoft 365 Group (Documents) source and destination endpoints will be deprecated. Microsoft 365 Groups will be migrated as part of SharePoint to SharePoint migrations. For additional information about Microsoft 365 Group (Documents) migrations, please see Current Release Notes.

Which Items Are and Are Not Migrated

MigrationWiz supports migration of documents, folders, permissions, versions, and metadata set at document library levels.


Document libraries

  • Documents

  • Folders / Folder Structure

  • Permissions

  • Versions (Max total 25 versions)

  • Custom Metadata

    • Single line of text

    • Choice

    • Currency

    • Date and time

    • Number

    • Person or Group (User/Group should be available at destination)

    • Yes/No

    • URL/hyperlink

    • Picture

    • Location

    • Calculated (Supported for calculation based on other supported columns)

  • Migrations of over 15GB are now supported, but this must be set up in Advanced Options. These settings will prevent timeout errors when a Speedster import takes more than 10 minutes to complete.
    • Set LargeFileMigrations = 1
    • Set LargeFileMigrationsTimeout=7200000
      • 720000 value is an example; time is measured in milliseconds

Custom metadata limitations

  • Multiple lines of text: Migrated as single lines of text; migrated values cannot be updated at the destination

  • Task Outcomes: Migrated as single line of text to destination

  • External data: Not supported

  • Managed metadata: Not supported

  • Lookup: Not supported

Not Migrated

  • Site/Site Collection

  • Site logos and customization

  • Document library settings

  • Custom permissions

  • Lists

  • Custom task

  • Newsfeed

  • Any metadata referencing information from outside the document library (such as lists or other site-level data) is not migrated. For example: external data, managed metadata, lookup, retention policy tags/retention labels.
  • Shared permissions for files/folders with symbols in name 
  • Links giving access/Link sharing

Preparing the Source

Optional: Save library templates. This step is only required if you want to apply templates from your source libraries onto your destination libraries. 

Application Permissions for SharePoint

Follow the steps to enable permission level at the source. This authentication process gives you control over who is entitled to use the source.

  1. Sign in as a Global Admin.
  2. Go to MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
  3. Navigate to the Microsoft 365 Admin Portal and create a new Security Group named “MigrationWiz”. 
  4. Create new user.
  5. Add new user to previously created MigrationWiz security group as a member. These user credentials are also required during setup of the SharePoint source endpoint.
  6. Add the following advanced option to the project during the advanced option phase: UseApplicationPermission=1 

Steps to remove these permissions are provided below in the Post-Migration section.  

Full-Control vs Read-Only

Why does the source require consent to a Full-Control application permission?

All AMR migrations require full-control permission. If you have a specific need to not allow full-control permissions, you can use MigrationWiz-SharePoint-ReadOnly (only for the source). However, please note that with read-only permissions, MigrationWiz will not export document permissions, versioning or metadata, and cannot use AMR.

Prepare Azure Environment

Microsoft-provided Azure storage

We recommend using Microsoft-provided Azure storage for this migration. Refer to Microsoft documentation for more details. If you choose this option, skip to Prepare Destination Environment.

Own Azure storage

If you plan to use your own Azure storage, refer the following steps to prepare your Azure environment. We recommend that you create your Azure storage account in the same Microsoft data center as the destination Microsoft 365 tenant. You do not need to create any Azure containers for this migration.

  1. Estimate Azure storage costs. This step is optional but is useful in order to provide the customer with up-front storage costs ahead of time. 
  2. Buy an Azure subscription (or use the free one-month trial, and be aware that this option is only viable if you are performing a very small migration). 
  3. Create an Azure storage account. You will need to set up a STORAGE (General Purpose v2) account rather than a storage blob.
  4. Take note of the storage account name and the primary access key. (In Azure, from the storage screen, click Manage Access Keys at the bottom of the screen.) These need to be entered into the MigrationWiz migration project when specifying the destination settings. 

To create the Azure storage account:

    1. Visit the Azure portal.
    2. Click New.
    3. Select Storage > Storage account.
    4. Enter a name for your storage account.
    5. Choose Resource manager for the Deployment model.
    6. Choose STORAGE (General Purpose v2)
    7. Record the storage account name (-accesskey, example: “accountname”) and primary access key (-secretkey, example: “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==”)
    8. In the Replication field, select Locally Redundant Storage (LRS).
    9. Select the subscription in which you want to create the new storage account.
    10. Specify a new resource group or select an existing resource group.
    11. Select the geographic location for your storage account.
    12. Click Create to create the storage account.

Now the storage account appears in the storage list.

Prepare Destination Environment

  1. Create a SharePoint Online administrator or Site Collection administrator account to be used for migration or use the global admin account for the tenant.
  2. Create a SharePoint site and make a note of the site URL where the document libraries are stored.
  3. Ensure all necessary users/groups are set up at the destination SharePoint site.

If you wish to maintain the same look, feel, and design of your source libraries on your destination, follow these additional steps before starting the migration project:

  1. Create the structure of the document libraries.
  2. Create the actual document libraries on the destination SharePoint Online site. To learn how, follow the steps from Microsoft: Create your document library.
  3. Save library templates from the source and apply them to your destination libraries.

Application Permissions for SharePoint

Follow the steps to enable permission levels at the destination. This authentication process gives you control over who is entitled to use the destination.

  1. Ensure you are signed in as a Global Admin.
  2. Go to MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
  3. Create a new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal.
  4. Create new user.
  5. Add the new user to the previously created MigrationWiz security group as a member.
  6. Record these credentials for use during destination endpoint setup.

Steps to remove these permissions are provided below in the Post-Migration section.  

MigrationWiz Steps


This migration scenario uses the Shared Document License type. 

  • This license type is used only for SharePoint Online to SharePoint Online migrations.
  • One license per line item in project (i.e. per document library migration)
  • Data limit: 50 GB per license

To purchase licenses:

  1. Sign in to your BitTitan account. 
  2. In the top navigation bar, click Purchase.
  3. Click the Select button and choose the license type you need.
  4. Enter the number of licenses you want to purchase. Click Buy Now.
  5. Enter a Billing address if applicable.
  6. Click Next.
  7. Review the Order Summary and enter a payment method.
  8. Click Place Your Order.

​​Licenses are released once payment has been received:

  • If you purchase via credit card, licenses will be available immediately upon payment.
  • If you purchase via wire transfer (100+ licenses), licenses will be available once payment has been received and accepted.

Set up a Document Migration project

  1. Sign in to your MigrationWiz account.
  2. Click Go To My Projects.
  3. Click Create Project.
  4. Click on Document Project to create new project.
  5. Click Next Step.
  6. Enter a project name and select a Customer. 
  7. Click Next Step.
  8. Select a Source Endpoint from the endpoint dropdown menu.
  9. If you have not already added the source endpoint, you will need to click New to create the source endpoint. Fill in the fields below to set up a new source endpoint:
    1. Name: Type any name you want for the endpoint.
    2. Endpoint Type: Select SharePoint from the source endpoint type drop-down list.
    3. URL: Enter the URL for the source SharePoint tenant.
    4. Administrator Username/Password: Enter the email for the user authorized to run the migration for the source tenant. This is the user added to the MigrationWiz security group for source tenant.
    5. Click Add.
  10. Click Next Step.
  11. Select a destination endpoint from the endpoint dropdown menu.
  12. If you have not already added the source endpoint, you will need to click New to create the destination endpoint. Fill in the fields below to set up the destination endpoint:
    1. Name: Type any name you want for the endpoint.
    2. Endpoint Type: Select SharePoint Online from the destination endpoint type drop-down list.
    3. SharePoint Online Tenant URL: Enter the URL for the destination SharePoint tenant.
    4. Office 365 Username / Password: Enter email for the user authorized to run the migration for the destination tenant. 
    5. Use the credentials of the Microsoft 365 user which was added to the MigrationWiz security group for the destination tenant.
    6. Click Add.
  13. Click Save and Go to Summary.
  14. Click Save Project.

Add Line Items

There are two options for adding items. Choose which one you will use, then follow the steps below.

Quick Add: This option allows you to add items o​ne at a time. You have to enter Source library and destination library path for each line item.

Bulk Add: This option allows you to add multiple items at once by copying and pasting from a spreadsheet or by importing a CSV file.

Add Items

Add the source and destination Document Library path for each line item. We recommend that you use the document library path from the URL.

The following examples show the breakdown of each type of URL.

Example 1: Document library located under a site:


Example 2: Document library located under a sub-site:


Example 3: Document library located directly under SharePoint Online root site:


Example 4: Document library located directly under SharePoint Online root sub-site:


Example 5: Site and Document Library names may contain special characters, but the URL may not reflect the same. It’s important that the document library path is captured correctly from the URL.


Set the Project Advanced Options

In the Support tab, add:

  • InitializationTimeout=8- This increases the initialization timeout window to eight hours. This value is in hours, up to a maximum of 100 hours. Values above 100 are in milliseconds. For example:​
    • InitializationTimeout=2 will increase the timeout to 2 hours.
    • InitializationTimeout=8 will increase the timeout to 8 hours.
    • InitializationTimeout=14400000 will increase the timeout to 4 hours.
    • InitializationTimeout=21600000 will increase the timeout to 6 hours.
  • Add UseApplicationPermission=1 if you did not do so during the app permissions phase. This is required for the application permission to function at the source.
  • Add UserMapping to customize the name for each user as required.
    • UserMapping=">" 

Under Source/Destination tab

Set number of Versions to be migrated as per project requirement and click Save.

  • The minimum number of versions is 1, the maximum number is 25. 

Verify Credentials

You may verify the credentials of items in MigrationWiz without migrating data or consuming any licenses.

  1. Open the project containing line items you wish to validate​.

  2. Select the items you wish to validate.

  3. Click on the Start button in your dashboard.

  4. Select Verify Credentials from the drop-down list.

  5. Once complete, the results of the verification will be shown in the Status section.

Perform a Full Migration

  • SPO Migration API migrates documents and permissions together. We recommend you select & migrate Documents and Document Permissions together.

  • To migrate metadata, the metadata checkbox must be selected during the first migration run.  

To initiate migration of document libraries:

  1. Open the Project containing the items you wish to migrate.

  2. Select the items to migrate.

  3. Click on the Start button in your dashboard.

  4. Select Full Migration from the drop-down list.

  5. Ensure that the Documents, Document Permissions, Metadata, and Versioning checkboxes are selected. By default, the latest three versions will be migrated. The number of versions to migrate can be updated in the Advanced Options section on the source/destination tab. See the Versions section below for more information.

  6. Click Start Migration.

  7. Once complete, the results of the migration will be shown in the Status section.

Post-Migration Steps

  1. To prevent users from inadvertently using the Source SharePoint libraries, decommission the Source SharePoint server, libraries, or user accounts.

  2. Delete all the Azure containers used for this migration. This will prevent incurring post-migration costs. Be careful to only delete the containers created for this migration.

Remove App Permissions

  1. Remove the newly created user.

  2. Remove the MigrationWiz Security Group.  

  3. To remove the app from the source or destination, perform the following steps:

    1. Launch PowerShell.

    2. Connect PowerShell to Microsoft 365.

    3. Enter the command: Connect-AzureAD

    4. Enter the admin credentials in the prompt.

    5. Enter the command: Get-AzureADServicePrincipal -SearchString Migration

    6. Look for the ObjectId of the app you want to remove and enter the following command: Remove-AzureADServicePrincipal -objectId <the object id>

FAQ & Resources

Group Permissions

MigrationWiz will migrate group permissions if the same group name exists at the destination. If the identically named group is not created at the destination prior to migration, group permissions will not migrate. MigrationWiz will not create groups at the destination, this must be done manually during destination setup.

Group permission migration does not support the RecipientMapping or UserMapping advanced options. 


Update the appropriate number of versions to be migrated from advanced options before running the migration. Migration of up to 25 versions (minor + major versions), including current version, is supported. To migrate versions, ensure that the Versioning checkbox is selected before starting the migration. Documents must always be selected to migrate versions.

Multi-pass behavior

During the first migration pass/run, a file and its associated versions will be migrated to destination. In subsequent passes, the destination will be overwritten only with the latest version only if the source file has a new version at the source.



If the source file content has not been modified in subsequent passes, files & versions will not be migrated, i.e. there will be no change at destination.

If a version is deleted for a source file, it is not identified as a change in file content. This change (reduction in versions at source) will not be migrated in subsequent passes unless the source file has a new version due to content change at the source.

Handling of minor versions at destination

SharePoint allows for a file to have minor versions. This setup is possible through document library settings. Document library settings are not migrated by MigrationWiz.

It is possible for a source file to have the latest versions as minor versions at the time migration.

  1. When the latest minor version has received content changes after the initial migration, then the file is migrated with versions to a destination where the existing document library settings don't have minor versions enabled, the final version at the destination will be a major version.
    1. For example, if File B, along with latest minor versions 1.1, 1.2, and 1.3, is migrated to a destination document library where minor versions are not enabled, the destination versions will set as 0.1, 0.2, 1.0. The latest minor version (1.3) is set as major version at destination (1.0).
  2. When the latest minor version exists without content change (e.g. metadata value change) then the destination version continues to be a minor version.

If the content of a file migrated by MigrationWiz in the initial pass is updated by users at the destination, then the subsequent migration pass will not overwrite this file even if the source file has a new version available.


MigrationWiz supports the migration of metadata, which is set and available at the specific document library level. Any metadata referencing information from outside the document library (such as lists or other site-level data) is not migrated. For example, these types are not migrated: external data, managed metadata, lookup.

Multi pass behavior

Supported metadata is migrated in the first pass, along with the documents. In subsequent passes, any new metadata changes will not be migrated beyond the initial migration, as metadata is technically part of the document file. This also applies to folder metadata.

New metadata changes for files will be migrated with new versions on subsequent passes. Folders do not have a version history, so no metadata changes will get migrated.

Metadata checkbox behavior

Selecting the Metadata checkbox will ensure that columns are created for supported custom metadata at the destination document library before metadata values are migrated. If the destination document library already has custom metadata columns at the time of migration, the custom metadata values (for supported metadata types) will be migrated to the destination even when the Metadata checkbox is not selected.

MigrationWizId column at destination

As part of the migration, an additional column named MigrationWizId is created at the destination as a watermark for migrated documents.

Can I set up source & destination endpoints with SharePoint site URL?  

Yes, you can set up your source or destination endpoints with site-level URL.  

For example, if all of your document libraries at the source or destination are directly under a single site, you may prefer to set up the endpoint URL in this format: 

If your source/destination endpoint is set up with a SharePoint site URL, your line item should only include the library name and not the site path. 

Was this article helpful?
0 out of 0 found this helpful