1. BitTitan Help Center
  2. Perform a Migration
  3. Microsoft OneDrive & SharePoint Migrations
  4. SharePoint Online

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

This is the complete workflow for migrating from SharePoint Online to SharePoint Online. SharePoint On-Premise is not supported.

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

We recommend reading through the complete guide before starting the migration to understand the process, timeline, and prerequisites.

First Time?

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

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. 

Prerequisites

It is important to highlight the following prerequisites for a smooth migration project.

Licensing

The SharePoint Online to SharePoint Online document migration is supported by the Shared Document License type.

  • Both licenses Shared Document 50GB or Shared Document 100GB can be utilized.
  • Each license allows up to the maximum quantity of data it permits to be migrated per Site.
  • If more than 100GB of data per Site is being migrated, purchase enough licenses to cover the total data being migrated. For example, if you have six Sites and two have 200GB of embedded data you must purchase eight licenses. 
Purchase licenses Considerations

Purchase licenses by following the steps below.

  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.

Limitations

Consider the following limitations when performing this type of migration.

  • This guide does not support GCC High or China migrations. For a GCC High or China migration, use the steps in the following migration guide instead: SharePoint to SharePoint Migration Guide for GCC High/China Migrations.
  • We are not able to support migrations with 2-factor or multifactor authentication. Information about the types of items migrated with this scenario, including metadata and versions, can be found in the following dropdown. More information about metadata and versions can be found at Versions & Metadata Migration for SharePoint & OneDrive.
  • App password usage, MFA/2FA, and ADFS are not supported for the migration admin account/service account being used by this endpoint.

Autodiscovery

  • Currently, the MigrationWiz-SharePoint-ReadOnly permission at the source is not supported and will show a permission error.
  • The autodiscovery process might take a bit longer for sites with a large number of items (Document libraries + subsites). A higher number of subsites is more likely to increase this time than a high number of document libraries, although there are exceptions. 
    For example, our tests show that, for 3k+ items, it takes between 30 minutes and an hour to auto-discover.
  • If the root URL is provided, it will show all the sites under it (including all subsites).
    • This will exclude Teams Site URLs, but still include Teams Private Channel URLs due to a Microsoft limitation. 
    • After importing, the specific document libraries can still be removed from the line items before starting a migration.
  • On-premises SharePoint is not supported.

Document Properties

Microsoft Word document properties in Content Controls are not retained at the destination after migration. References to custom metadata values within a document appear broken after being migrated to the destination document library. This is a Microsoft limitation and can be replicated by copying a basic document to a new document library within the same tenant without the use of MigrationWiz. 

We have provided a workaround for this issue.   

Custom Metadata Limitations

When performing a SharePoint Online to SharePoint Online Document Library Migration, consider the following points related to custom metadata:

  • Multiple lines of text are migrated as single lines of text, migrated values cannot be updated at the destination.
  • Task Outcomes are migrated as a single line of text to the destination.
  • External data is not supported.
  • Managed metadata is not supported.
  • Lookup is not supported.

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. 

Migrated Items

Which items are migrated

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

  • Document libraries.
  • Documents.
  • Folders / Folder Structure.
  • Permissions are set at the individual folder or item level.
  • Versions (Max total 25 versions).
  • Custom Metadata.
    • A 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.
Which items are 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.
  • Permissions that are set at the site or tenant level (this includes Owner/Membership permissions for O365 Groups sites).  MigrationWiz is only able to migrate permissions for individual folders/files with this migration type.
  • Shared permissions for files/folders with symbols in names.
  • Links giving access/Link sharing.

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 before 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. 

On the other hand, keep in mind that you can set up your source or destination endpoints with site-level URLs. 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: https://tenant.sharepoint.com/sites/site-name 

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. 

Prepare the Source Environment

Prepare the destination environment by following the steps below:

  1. Create the SharePoint site and make a note of the site URL where the document libraries are stored.
  2. Create the document libraries on the destination SharePoint Online site (optional). To learn how to create it, follow the steps from Microsoft: Create your document library.

    Save Library Templates

    This is an optional step and it is only required if you want to apply templates from your source libraries to your destination libraries. 

  3. Ensure all necessary users/groups (including external users, if any) are set up at the SharePoint site and available for your destination document library.

Application Permissions for SharePoint

Continue configuring your destination environment by selecting one of these application permissions options and following the steps to enable permission levels at the destination.

Delegated Authentication App-Based Authentication

The easiest approach is to use the global admin account set up at the time of tenant creation. However, if you do not wish to use this global admin account during migration, then a new user account can be created instead. This user account needs to have a license assigned that includes SharePoint and be granted Site Collection Administrator privileges to the SharePoint site in the project.

  1. Create a user in Microsoft 365 and assign a license that includes SharePoint. For step-by-step instructions, see the Microsoft article Add users individually or in bulk to Office 365.

  2. Set the administration privileges. Grant one of the permission levels listed below to the user account to be user as the administrator for the endpoint in the project.

  3. Add the admin account, created in step 2, as a Site Collection Admin to the endpoint.

    Important

    The Global Admin or SharePoint Admin role does not automatically grant Site Collection Admin rights to a SharePoint site.
  4. Go to MigrationWiz-SharePoint-Delegated and consent to the app access when prompted. Once you click on Accept, you will be redirected to the BitTitan login page. This is normal and the page can be closed.

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 to the following steps to prepare your Azure environment. We recommend creating 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 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.) When specifying the destination settings, these need to be entered into the MigrationWiz migration project. 

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 a 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

Follow these steps before starting your migration.

  1. Create a migration service account.  You can use an existing account/admin if desired, but it is not required.  The account used here does not need any special permissions outside of what is outlined in the "Application Permissions for SharePoint" section below.
  2. Ensure that SharePoint has been provisioned within your environment and that the default. SharePoint site is created.
  3. Ensure all necessary users are set up at the destination. If any permissions have been applied to groups, ensure that matching groups have been created on the destination.

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 to follow the steps from Microsoft: Create your document library. 

    Important

    MigrationWiz can create the subsites and libraries as part of the migration if needed. You only need to pre-create them yourself if you want to apply special templates/formatting them.
  3. Save library templates from the source and apply them to your destination libraries.

Application Permissions for SharePoint

Follow the steps in the Sharepoint App-based Authentication tab to enable permission levels at the destination. This authentication process gives you control over who is entitled to use the destination.

MigrationWiz Steps

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 a new project.
  5. Click Next Step.
  6. Enter a project name and select a Customer. 
  7. Click Next Step.
  8. Choose or create your endpoints.
  9. Click Save your Project.

Endpoints

Endpoints are created through MigrationWiz. If you select an existing endpoint from the dropdown, it will only show ten endpoints. If you have more than ten, you may need to search it.

Consider that endpoint search is case and character-specific. For example, Cust0mer will not show up if the search is customer. We recommend keeping a list of endpoints you have created and any unique spellings or capitalization you may have used.

You may either use existing endpoints or create new ones. 

Create your Endpoints

Please review the following tabs to create your destination and source endpoints.

Source Endpoint Destination Endpoint

Create your source endpoint by following the next steps:

  1. Click New.
  2. Enter endpoint name.
  3. For the endpoint type, select SharePoint.
  4. Enter the Site Collection URL for the top-level SharePoint document library, in other words, the site URL displayed in the SharePoint Admin Center.
  5. Enter the administrator username and password in the fields. This must be either a Global administrator, SharePoint Online administrator, or a Site Collection administrator account.
  6. Click Add. 
  7. Click Next Step.

Region of Destination Tenant

MigrationWiz displays a dropdown to select the Preferred Region of the Tenant at the destination endpoint. This value updates the Preferred Region of the Destination Tenant field in the project's Advanced Options, and vice versa. You will notice that both values are always the same.

The Region of Destination Tenant feature optimizes the migration performance and speed when choosing the region closest to the destination tenant.

Tip

You can find the region of your destination tenant directly in the Microsoft Entra admin center by going to Identity > Overview > Properties, and using the Country or region or the Data location.

Country or region.png

For more information on this topic, review this article. In case you need the multi-geo information you can refer to this article.

Warning

If you do not complete this field you will not be able to save your project and the “This field cannot be left blank.” error will appear.

Add Line Items

There are three options for adding items. Choose which one you will use and follow the steps below. While Autodiscover is recommended, Bulk Add and Quick Add may also be used.

Discovered Sites

Autodiscovery discovers both Communication and Team sites but it filters out the Team sites that are linked to Microsoft Teams channels. Currently, a Microsoft Teams site can be created in one of two ways:

  1. Adding Team site from SharePoint - which can be later linked to Teams channels.

  2. Creating a Teams channel - which creates a SharePoint site by default.

Autodiscover filters out the second one automatically and may filter Team sites connected to some Microsoft Teams channels in the first case. 

Important

Currently, autodiscovery cannot filter out Teams Private channels, so those need to be manually removed.

Autodiscover Prerequisites

The source tenant must have one of the following permissions enabled:

  1. MigrationWiz-SharePoint-FullControl - Recommended. Use with the Advanced Option set as UseApplicationPermission=1 or UseApplicationPermissionAtSource=1

  2. MigrationWiz-SharePoint-Delegated

Important

If you use Delegated permissions with Global Admin credentials, this process only discovers the SharePoint sites for which the Global Admin is also the site admin. For example, the Global Admin should be present here under Site Admin in Permissions for this site to be discovered.AD1.png

Steps to Enable Autodiscover

This section outlines the workflow to use the SharePoint Autodiscover option to automatically discover all document libraries for the sites and subsites available for migration under the SharePoint site URL provided in the source settings.

  1. Create a new Document Project and set the URL under the source endpoint to the required root site. Details on allowed source URL configuration can be found later in this article.

  2. If MigrationWiz-SharePoint-FullControl permissions are being used at the source, set the UseApplicationPermission=1 or UseApplicationPermissionAtSource=1 as Advanced Options.
  3. Click the Autodiscover-items button. AD2.png
  4. Click Start Autodiscover.
  5. Once discovery is complete, click on ‘Import Items’ to add the discovered sites and document libraries as line items to the project. AD3.png
  6. Once imported, the discovered items will show up as line items. AD4.png

Source URL Configuration

Source Endpoint URL Settings Discovered Items
Root_url
Example
https://mdbttest123.sharepoint.com 		Discovers all the document libraries under the root URL and its subsites (both Team and Communication sites).

Important

This will exclude MS Teams Site URLs (URLs linked to Teams), but will not exclude Teams Private Channel URLs.
Example. This below site and its corresponding Document Libraries will be filtered out:
 5.png
Root_url/sites
Example
https://mdbttest123.sharepoint.com/sites 		This is an incorrect format and will return an error.
Root_url/sites/site_name
Example
https://mdbttest123.sharepoint.com/sites/TestSite2 		Discovers all the document libraries under this site and its subsites.
Autodiscover FAQ

The Document Library name has special characters but that item is not showing when importing items
If the Document Library has special characters, the URL may not reflect that. Additionally, the imported item in the project is based on the URL, not the name.

AD5.png

The count of Import Items seems to be different if different permissions are used
MigrationWiz-SharePoint-FullControl has more permission access than MigrationWiz-SharePoint-Delegated. It is possible when using Delegated permissions that the global admin may not have permission to access some sites, meaning those will not get auto-discovered. Thus the count may differ.

Autodiscovery shows team URLs
SharePoint Autodiscovery will discover both Teams and Communication Sites.
But it will automatically filter out Teams SharePoint sites that are not Private Channels. Teams Private Channel SharePoint URLs need to be manually removed by the customer after importing them as line items.

How long will it take to autodiscover all items?
The following are time estimates to discover all document libraries under the provided site URL. These are estimations only, your results may vary.
~100 items - <1 minute
~900 - 1k items - <5 minutes
~2k - 3k+ items - <0.5 - 1 hour

Manually Add Items

Quick Add

This option allows you to add items one at a time. You have to enter the 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 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:

Library1.png

Example 2: Document library located under a subsite:

Library2.png

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

Library3.png

Example 4: Document library located directly under SharePoint Online root subsite:

Library4.png

Example 5: Site and Document Library names may contain special characters, but the URL may not reflect the same. The document library path must be captured correctly from the URL.

Library5.png <>Library6.png

Site Provisioning

The following section will explain how to provision sites. 

Licenses

This is a pre-migration step and does not consume licenses as long as it is done with the "Trial Migration" option.  If you run the site creation step with either a Pre-Stage or a Full Migration, a license will be used but will then continue to be used for the data migration step. With this new feature, we are now able to provision sites at the destination, similar to how we provision document libraries that do not yet exist. This is an optional step. 

Prerequisites

The source tenant must have either one of the following permissions enabled:

  1. MigrationWiz-SharePoint-FullControl (Recommended)
    (with AO set as UseApplicationPermission=1 or UseApplicationPermissionAtSource=1)

  2. MigrationWiz-SharePoint-Delegated

If using Delegated permissions with Global Admin user credentials, we recommend that the Global Admin should also be added as an administrator of the site collection. If this is not done, the site provisioning may fail. For example, the Global Admin user should be present here under site admin in permissions.Provision1.png

Create SharePoint-SharePoint Online project 

Only SharePoint source and SharePoint Online destination endpoints are supported currently. ​Provision2.png

Create a Line Item

Use Quick Add/Bulk Add/ Auto Discovery to add the source and destination library paths for a line item in the project.

mceclip2.png

Add the ‘TestSharePointWithProjectConfigUrl’ Advanced Option

Go to the Advanced Options page and add TestSharePointWithProjectConfigUrl=1 . This allows you to verify credentials even if the destination site does not exist.  If this option is not added, the site creation will fail since it will attempt to verify before it tries to create the site.Provision4.png

Select ‘Setting Up SharePoint’

To provision sites and subsites before performing a migration, click on the Full Migration, select only the Setting Up SharePoint --> Sites Creation step, and proceed with ‘Start Migration’. This will create all the required sites and subsites at the destination.

Provisioning6.png

Select Migrate Data

Once the “Setting Up SharePoint” step is complete, proceed with “Migrate Data” to complete the migration of the site content.

Supported Authentication Mode

Authentication mode* Is supported Remarks
Basic auth (User name + Password) No  
Application permission (BT app) Yes Credentials of user added to the “MigrationWiz” security group
Delegated permission (BT app) Yes GA/SP Admin credential
Delegated permission (BYO app) Yes GA/SP Admin credential
*Applies to both source and destination.

Advanced Options

Support Tab

  • TestSharePointWithProjectConfigUrl=1 This allows you to verify credentials even if the destination site does not exist.  If this option is not added, the site creation will fail since it will attempt to verify before it tries to create the site.
  • 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.
  • Migrations of over 15GB are now supported. 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
  • UserMapping="name@source.com->full.name@destination.com" By default, we match users from the source to the destination based on the prefix in their User Principle Name (UPN). For example, if the user UPN is “name@domain.com”, we match the “name” portion.
    If there are multiple people with the same prefix at the destination (e.g. name@domain1.com and name@domain2.com or the prefix of a particular user is changed in the destination (e.g. name@source.com → name.full@destination.com), it is necessary to use this setting.

Source/Destination Tab

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

Keep in mind that the minimum number of versions is 1 and the maximum number is 25. 

Advanced_Option.png

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.

  • Migrate metadata by selecting the metadata checkbox 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.

    Items_to_Migrate.png

  6. Click Start Migration.

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

Post-Migration Steps

  1. Prevent users from inadvertently using the Source SharePoint libraries and decommissioning 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.  

To remove the app from the source or destination, follow the steps outlined in this article.

Was this article helpful?
1 out of 6 found this helpful

Articles in this section