SharePoint and OneDrive share many similarities in both migration preparation and execution, but there are some special cases and limitations for both. The following article lays these out and offers solutions where applicable.

Limitations of SharePoint Online & OneDrive for Business Migrations

OneDrive and SharePoint have several limitations which may cause migration challenges. Review the following carefully before beginning your migration and add in any of the Advanced Options necessary to support your migration.

File path limitation

SharePoint Online and OneDrive for Business have a 400 character limit that applies to file paths and file names. Character limits might not be enforced in other document storage services, like Google Drive or Dropbox. When migrating from one of those platforms to SharePoint Online or OneDrive for Business, you might need to shrink file paths and file names. Use the "ShrinkFoldersMaxLength=200" advanced option to shrink the name length.

To increase the length limits, use the MigrationWiz Advanced Option IncreasePathLengthLimit=1.
Note that not every Office 365 tenant has been updated to support the increase in the number of file path name characters. However, when you include IncreasePathLengthLimit=1 in your project, you may prevent this error from occurring. Then, if it is available in your tenant, MigrationWiz will make use of the 400-character limit.

File and folder name extension limitation

There is a list of file extensions that are not allowed to be created inside of SharePoint Online and OneDrive for Business.

Read the following articles for more information:

• Types of files that cannot be added to a list or library
• Information about the characters that you cannot use in site names, folder names, and file names in SharePoint
• Contributors are not permitted to upload SWF files onto SharePoint 2010

The list currently contains: .ashx, .asmx, .json, .soap, .svc and .xamlx as blocked by default when working with the SharePoint server.  There are currently no file type limitations for SharePoint Online. In addition, folder names may not end with any of the following strings: .files, _files, -Dateien, _fichiers, _bestanden, _file, _archivos, -filer, _tiedostot, _pliki, _soubory, _elemei, _ficheiros, _arquivos, _dosyalar, _datoteke, _fitxers, _failid, _fails, _bylos, _fajlovi, _fitxategiak

This may be changed at any time by Microsoft.

Additionally, an administrator may add other extensions to this list.

Multiple files with the same name limitation

Some environments, such as Google Drive, allow the user to create multiple files of the same name in the same folder. This is not supported by OneDrive for Business. 

Auto-shrink the folder path before migration

How does this Advanced Option work?

• This option can be set to a higher or lower value, depending upon what is acceptable to the customer.  The value is dependent upon the following criteria: the file system data, the email address that is a part of the folder path (collection root), and the domain name for permissions, etc. However, using 200 should keep a good security range to manage all edge cases, and it provides a very reasonable limit.
• This option should be enabled on a case-by-case basis. We recommend that you create a project specifically for when this option is required. Within this project, add the Advanced Option: ShrinkFoldersMaxLength=200 and then move mailboxes that get "path too long" errors into this project. It is not recommended to use it on every mailbox by default, as many mailboxes should be below the limit and being too aggressive may cause truncation, while normal migration may actually succeed.
• If a former migration has been performed without the option on, then the storage will need to be reset at the Destination, otherwise, both file system structures will appear at the Destination.
• If a user modifies the Source file system folder structure (for example, by renaming, removing, or creating a new folder) between two passes using this Advanced Option, the dynamic mapping may be totally different and the Destination may have two different file systems represented.
• If multiple folders are truncated at 10 characters in the same parent folder, they may end up being merged into a single one if the first ten (10) characters are identical.

Microsoft Office Documents Properties Limitation

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. 

Details and workaround:

Workaround (This workaround is not guaranteed to work and is using built-in Office 365 tools and not MigrationWiz)

After migrating this kind of document, the broken references to custom document properties can be fixed manually. User needs to update (reinserting will not work) links inside each document through the Microsoft Word UI ("Map the Selected Content Control").

1. Turn on the Development ribbon in Microsoft Word ( File > Options > Customize Ribbon. Select the Developer check box).

2. Turn on Design Mode for better clarity. The broken content control will be blue.

3. Select the broken content control.

4. Open the XML Mapping Pane (Developer > XML Mapping) and choose “http://schemas.microsoft.com/office/2006/metadata/properties“ in the dropdown list.

5. Under the ”Properties > documentManagement” tree find your document property.

6. Right click on your found property and choose “Map to Selected Content Control“.

Now the selected content control has been fixed and will be yellow.

7. This procedure has to be done for each migrated document with this issue. 

Shared With Me migration issues for OneDrive For Business with Versions and Metadata

To be able to migrate “Shared With Me“ content from Google Drive to OneDrive, the user must select Files+Permissions before beginning the full migration.

Permission mapping in non-English tenants

Use “PermissionLevelMapping“ and “MembershipMapping” options to map non-English tenant permission levels and membership/group names respectively, for SharePoint/OneDrive migrations.
These options can be used if the source and tenant have the same non-English language (e.g. Japanese to Japanese) or non-English language at source (e.g. German to English). It cannot be used if they have different non-English languages (e.g. Japanese to German).

PermissionLevelMapping:
Normally this will require all permission levels i.e. Full Control, Design, Edit, Contribute, Read to be added individually (or at least the permission levels which are used in the source site).
Only the front part of the mapping should be updated according to the language at source tenant i.e. the second part needs to be either one of these - Full Control/Design/Edit/Contribute/Read.
Example Usage:
PermissionLevelMapping="フルコントロール->Full Control"
PermissionLevelMapping="デザイン->Design"
PermissionLevelMapping="編集->Edit"
PermissionLevelMapping="投稿->Contribute"
PermissionLevelMapping="閲覧->Read"

MembershipMapping:
This will require all three types i.e. Owners, Members, Visitors to be added individually.
Only the front part of the mapping should be updated according to the language at source tenant.
Example Usage:
MembershipMapping="所有者->Owners"
MembershipMapping="メンバー->Members"
MembershipMapping="閲覧者->Visitors"

SharePoint Migration FAQ

The following section refers to questions commonly raised during a SharePoint migration. 

Verifying administrator access

The Office 365 account that you use to perform a SharePoint Online or OneDrive for Business migration must have one of the following Office 365 roles assigned to it:

• Global Administrator (preferred)
• SharePoint Administrator

Follow the steps in the Assign admin roles in Office 365 for business article from Microsoft to verify or assign a Global Administrator or SharePoint Administrator role to the account that you plan to use for the migration.

Read the About Office 365 admin roles article from Microsoft to learn more about the administrator roles available in Office 365.

Find the SharePoint URL

When creating a Document Migration project with SharePoint as either the Source or the Destination, the correct SharePoint URL must be provided in the endpoint settings.

Most commonly you'll have a custom site collection created, if you navigate to the SharePoint site you want to migrate data from, the URL format you should see is:

https://tenant.sharepoint.com/sites/site-name

This would be the URL to specify in the endpoint of the project. If you see something like this:

https://tenant.sharepoint.com/sites/site-name/SitePages/page-name.aspx

You would exclude `SitePages/page-name.aspx`.

You'll follow the same formatting to migrate from a subsite so you would use https://tenant.sharepoint.com/sites/site-name/sub-site-name in the endpoint.

Finding Document Library Name

Most commonly all of the data for a SharePoint site is within the default library which will simply be Shared Documents. 

To verify or find out what to input as the Document Library in the project, navigate to the to the SharePoint site and open one of the libraries, usually on the left hand side of the main page, and the URL will be formatted as:

https://tenant.sharepoint.com/sites/site-name/Library%20Name/Forms/AllItems.axpx

The Document Library name is Library%20Name, you'll remove the %20 and use Library Name for the project.

Migrating sublibraries

To specify a SharePoint sublibrary without migrating the parent library, simply enter the path of the sublibrary when you set up the items in your project.

For example, you have a library named "Documents" and a sublibrary within that, named "MigrationWiz". To migrate only the "MigrationWiz" sublibrary, enter "Documents/MigrationWiz". This way, only contents of "MigrationWiz" will be migrated.

The parent library "Documents" will be migrated for the sole purpose of storing the "MigrationWiz" library. However, no other files or folders stored in "Documents" will be migrated.

You will need to add a new line item in your project for every sublibrary to be migrated.

For example, "Documents/MigrationWiz" and "Documents/Special" are two separate libraries that will need to be migrated separately. Be aware that this will require two separate licenses.

Also note that when specifying the parent library, all sublibraries within it will be migrated automatically.​​

Migrating SharePoint Subsites

​To migrate SharePoint subsites with MigrationWiz, a separate project must be created for each subsite to be migrated. Use the path of the subsite as the SharePoint site URL when you configure the project.​

For example, if your subsite URL is https://tenant.sharepoint.com/​MainSite/Subsite, you will enter that as the site URL when setting up your project.​

SharePoint documents shown as "checked out"

Some versions of SharePoint have a default setting that automatically marks documents as "checked out" when for editing. This is important because the process of migration acts as "editing" the contents of the library. It is possible to configure a library that requires that documents are "checked out" so they can be manually edited. In both of these scenarios, the documents that are part of the migration will show up in the destination library as "checked out".

This setting can be changed by turning off the enforced check-in/check-out option before migrating your documents.  

The enforced check-out of documents causes the last modified date of the documents to be overwritten by the migration.  To keep the proper information on the document, we recommend that you remove the previously migrated files from the destination, change the settings or create a new library, and perform the migration again. 

1. Create a new Document Library in your SharePoint destination.
2. Click Library Settings.
3. On the Library Settings page, under General Settings, click the Versioning settings.
4. In the Require Check Out section, under the "Require documents to be checked out before they can be edited?" question, select No.
5. Click OK to close the dialog box and return to the Library Settings page.
6. Change the settings for your SharePoint migration destination to point to the new Library that was just created.
7. Reset migration statistics.
8. Migrate your files.
9. You can enable the check-out requirement after the migration completes.

Alternatively, if the last modified date is not a concern for your documents, you can also perform a bulk check-in of the files, using the instructions provided here: "Check out or check in files in a document library".

Data discrepancies after migration

When migrating permissions, MigrationWiz will report almost exactly double what is displayed in your Destination SharePoint environment because of the way SharePoint reports back data when it applies the migrated permissions.

When going to SharePoint as a Destination, permissions are migrated independently from the files and are only applied after the original file is fully migrated. When the permission is migrated and applied to the corresponding file, SharePoint detects it as a new version of the same file. When this happens, rather than reporting the actual size of the permission that was applied, SharePoint returns the size of the entire file a second time. In turn, MigrationWiz reports the size of the original file again, as if it had been migrated twice.

When you look at the statistics for the items in your project, the document sizes are actually correct. The permissions are the cause for the discrepancy in the total size reported. If they were to be reported correctly, the size of the permissions would be almost negligible when compared to the document sizes. The size of permissions are so small, in fact, that the two ultimately reported sizes appear identical.

There is no workaround at this time, because this is the way SharePoint reports data to us. However, although your data is being reported twice, it is only being migrated once.

OneDrive and SharePoint permissions migrated

When OneDrive for Business or SharePoint is configured as the source on a document migration, the only permissions migrated are for files and folders that are shared by using Direct Access and not shared via link.

Files or folders in OneDrive for Business and SharePoint can be shared in one of four ways:

• With specific people
• With anyone
• With an organization
• Direct Access

​​When files or folders are shared with a link that is generated for the items, these links are not accounted for by MigrationWiz and are not migrated to any destinations, including other OneDrive for Business accounts and SharePoint

The Office 365 account that you use to perform a OneDrive for Business migration must have one of the following Office 365 roles assigned to it:

• Global Administrator (Delegated permission)
• SharePoint Administrator (Delegated permission)
• App-based Authentications for SharePoint and OneDrive (Only the Full-Control application used in the source tenant can be used for migrating permissions. The Read-Only application will not migrate permissions)

Follow the steps in the Assign admin roles in Office 365 for business article from Microsoft to verify or assign a Global Administrator or SharePoint Administrator role to the account that you plan to use for the migration.

Read the About Office 365 admin roles article from Microsoft to learn more about the administrator roles available in Office 365.

Granted Permissions

The default behavior for OneDrive for Business and SharePoint is that all folders and items inherit permissions settings from the folder that is directly above them in the hierarchy. This means folders inherit permissions from the root, and subfolders inherit permissions from their parent folder.

Unless specifically configured to do so, MigrationWiz does not remove permissions during a migration. If you find that folders or items are shared inappropriately after migration, you may add the following option to your migration project in order to break permission inheritance, remove existing permission, and finally migrate only explicit permissions:

RemoveExistingPermissionsWhenUnspecified=1

This option can be added in Advanced Options, in the Support options text field, under the Support section.