This is the guide for OneDrive for Business to OneDrive for Business migrations which include versions and metadata. Review ALL steps and dropdown lists carefully and ensure all the prerequisites are met before beginning the migration.
For more information on OneDrive migrations, it is recommended to review our FAQ.
If you are performing a GCC High/China migration, use the OneDrive for Business to OneDrive GCC High/China Migration Guide instead.
The source endpoint for this migration must be OneDrive for Business and the destination endpoint must be OneDrive for Business (with Versions and Metadata). No other endpoints are supported for this migration type.
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 is found later in the article.
Migrations from a GoDaddy tenant are supported. In most cases, the steps are exactly as outlined below. However, in some cases, special steps may be needed for a GoDaddy hosted O365 tenant. Those steps are outlined in this article.
On-Premise OneDrive for Business is not supported.
The maximum single file size for migration through MigrationWiz varies by migration type and environment, but may never exceed 60GB.
Which Items Are and Are Not Migrated
- Shared Folders
- Permissions set at the individual folder or item level that have been granted to specific users/email addresses
- Code Files
- Audio Files
- Original metadata and BitTitan migration metadata (author, editor, created time, modified time, name, file size, type, MigrationWizId, MigrationWizPermissionId)
- Document attributes (Created by (person) and (time)
- Modified by (person) and (time))
- Versions & Metadata migrations only: Creation Date
The following metadata types will be migrated:
Single line of text
Multi select Currency
Date and Time
Person or Group (should be available at destination)
The following metadata types are currently not supported:
Any metadata referencing information from outside the document library (such as lists or other site-level data) is not migrated.
Retention policy tags/retention labels
- Non-Versions & Metadata migrations:
- Creation date (Creation date gets changed to the "date of migration" date)
- Version History
- Links giving access
- Shared permissions for files/folders with symbols in the name
Administrator Permission Options
- Both options require a Global Administrator for the configuration steps.
- Of the two options available, the more recommended is the App-Based Authentication, as it is more secure and incurs less throttling during the migration. This option also has the benefit of not requiring the account being used to migrate the data to have any administrator roles assigned to it.
BitTitan uses app-based authentication for SharePoint, OneDrive for Business, Microsoft 365 Groups (Documents), and Teams migrations. This provides greater security and reduces the potential of Microsoft throttling. It replaces the previous Microsoft 365 authentication, which has been subject to increased throttling by Microsoft. This app-based authentication method is specific for Microsoft 365 tenants. Using this option, including steps for uninstalling, can be found outlined here: App based authentication using Application Permissions for SharePoint and OneDrive Migrations
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. Additionally, OneNote files will be migrated, but will not contain content, due to a lack of permissions when preparing the files to migrate.
Steps for enabling app-based authentication permissions
- Ensure you are signed in as a Global Admin.
Go to MigrationWiz-SharePoint-FullControl 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.
Create a new security group named MigrationWiz in the Office 365 Admin Portal. (The name of the security group must be an exact match)
Create a new user that is not having data migrated in the project. This account does not require any administrator roles to be assigned. (If you already have an existing user, that should be fine) This user must have a SharePoint/OneDrive license applied.
Add the new (or existing) user to the previously created security group as a Member (Adding as an Owner will not work here).
Create MigrationWiz project.
When creating the source and destination endpoints, enter the user credentials for the user in step 4 that corresponds with the endpoint the user belongs.
- Add the support option UseApplicationPermission=1 to the advanced options of the MigrationWiz project under Support Options.
Create an Administrator Account to use Delegated Authentication
The easiest approach to follow is to use the global administrator account that was 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 will then need to have a license assigned that includes OneDrive for Business and be granted Site Collection Administrator privileges to the user OneDrives being migrated in the project. Using this option, including steps for uninstalling, can be found outlined here: Using Delegated App Permissions
Important: We strongly recommend that you use an administrator account that isn’t one of the users being migrated, as it can cause issues with missing shared permissions.
Create a user in Microsoft 365 and assign a license that includes OneDrive for Business. For step-by-step instructions, see the Microsoft article Add users individually or in bulk to Office 365.
Set the administrator privileges. Grant one of the permission levels listed below to the user account to be used as the administrator for the endpoint in the project.
Global Administrator. Microsoft has instructions to set these permissions here: Assign admin roles.
Site Collection Administrator. For specific permissions and project settings to be used with a Site Collection Administrator, see MigrationWiz Permission Requirements.
Add the support options UseApplicationPermissionAtSource=0 and UseApplicationPermissionAtDestination=0 to the advanced options of the MigrationWiz project under Support Options.
- Ensure you are signed in as a Global Administrator account in the tenant.
- 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.
After you perform these steps, the specified user will be visible in the Microsoft 365 administrator center. Full provisioning of the user account can take up to 24 hours.
Preparing the Source
- Users being migrated need to be licensed to use OneDrive in the source tenant
- Users being migrated must not be blocked from signing into the source tenant
- Source OneDrives must not be set to read-only (This is initially for setup. Steps for setting up for read-only can be found under the Run Verify Credentials section later in the guide)
- If electing to use Delegated Authentication (outlined under Administrator Permission Options above) for the administrator account performing the migration, it must be set as Site Collection Admin of the source OneDrives
Export the migrating user list to a CSV file
This can be used when bulk-adding users to your MigrationWiz project later. You can copy and paste the user list into the Source and Destination Email columns within your MigrationWiz project dashboard under Add > Bulk Add.
To export the user list:
- Go to the Microsoft 365 admin portal.
- Click Users.
- Click Active Users.
- Click Export.
- Click Continue.
Be sure to save the csv somewhere you can access it for upload of users into the migration project
Preparing the Destination
- Users being migrated need to be licensed to use OneDrive in the destination tenant
- Users being migrated must not be blocked from signing into the destination tenant
- Destination OneDrives must not be set to read-only
- If electing to use Delegated Authentication (outlined under Administrator Permission Options above) for the administrator account performing the migration, it must be set as Site Collection Admin of the Destination OneDrives
Prepare Azure Environment for Destination Endpoint
An Azure Storage account is required when creating the destination endpoint for this project type (steps for setting up the endpoints are listed later in the guide)
Using Microsoft-provided Azure storage
We recommend using Microsoft-provided Azure storage for this migration. Refer to Microsoft documentation for more details. If you choose to not use this option, see Using your own Azure storage below.
Using your 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 Office 365 tenant. You do not need to create any Azure containers for this migration.
- 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.
- 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).
- Create an Azure storage account. You will need to set up a STORAGE (General Purpose v2) account rather than a storage blob.
- 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:
- Visit the Azure portal.
- Click New.
- Select Storage > Storage account.
- Enter a name for your storage account.
- Choose Resource manager for the Deployment model.
- Choose STORAGE (General Purpose v2)
- Record the storage account name (-accesskey, example: “accountname”) and primary access key (-secretkey, example: “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==”)
- In the Replication field, select Locally Redundant Storage (LRS).
- Select the subscription in which you want to create the new storage account.
- Specify a new resource group or select an existing resource group.
- Select the geographic location for your storage account.
- Click Create to create the storage account.
Now the storage account appears in the storage list.
Create a Document Project
Log in to MigrationWiz.
Click the Go to My Projects button.
Click the Create Project button.
Select the Document project type.
Click Next Step.
Enter a Project name and select a Customer. (If no customer exists yet other than the Default customer. Click on New and create a customer for the project)
Click Next Step.
Select endpoints or follow the steps below to create new endpoints.
Endpoints are now created through MigrationWiz, rather than through MSPComplete. The steps for this section outline how to create the endpoints in MigrationWiz.
If you are selecting an existing endpoint, keep in mind that only ten endpoints will show in the drop-down. If you have more than ten, you may need to search. 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, along with any unique spellings or capitalization you may have used.
To create a new Source Endpoint in MigrationWiz:
Click SOURCE SETTINGS
- Name the endpoint. It is recommended that the name of the endpoint be unique for the project.
Under Endpoint Type, select OneDrive for Business from the dropdown menu
Enter the administrator username and password in the proper fields.
To create a new Destination Endpoint in MigrationWiz:
Click DESTINATION SETTINGS
Under Endpoint Type, select OneDrive for Business
Select the radio button named OneDrive for Business (Office 365 User) - Documents, Permissions, Versions and Metadata
Enter the administrator username and password in the proper fields.
Enter the Azure Storage Account Name and Azure Access Key (if using your own Azure storage) or select Microsoft-provided Azure Storage. If entering the Azure Storage Account Name for the destination endpoint, only numbers and lowercase letters can be used. If you enter an upper case letter, your migration will fail.
Click Add Endpoint.
Add Items to the Project
You can add the user accounts (also called "Line Items") that will be migrated into the project using the CSV file created in the Preparing the Source section, click "Add" in the menu dashboard and select "Bulk Add".
If you're also running a Mailbox Project for the users that will be migrated here, you can use the "Add from MSPComplete" option. Verify the users are licensed in MSPComplete or in the Mailbox project before adding them.
Important: The user's Source and Destination address in the OneDrive project must match the current username (User Principal Name) for their account in the Microsoft 365 tenant or authentication errors may result. It may be necessary to edit the addresses in your MigrationWiz project after you have imported your users. This will be required if you have already applied the User Migration Bundle to an address that is not the User Principal Name. Read the Cannot Authenticate article for more information.
Applying User Migration Bundle licenses:
In your OneDrive project, make sure you are in the correct workgroup (this can be found in the upper left-hand corner).
Select the checkbox next to the users in your project that are to be assigned a User Migration Bundle license.
On the toolbar at the top of the project screen, select Apply Licenses
Select Apply User Migration Bundle License from the dropdown list.
If there is at least one unassigned User Migration Bundle license available for each selected user, click Confirm. Processing User Migration Bundle licenses can take time. Once the status under User Migration Bundle Active shows a status of Yes, the assignment of the User Migration Bundle license has been successfully applied.
Advanced Options & Support Options
Add the following Support Options by navigating to the Advanced Options of the project. Each individual Support Option includes the "=" character and is to be entered under the Support tab in the section named Support Options. To add additional blank fields for entering the Support Options, click on the "+" button.
InitializationTimeout=8 This increases the initialization timeout window to eight hours. This is especially useful for large migrations.
- 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.
- LargeFileMigrationsTimeout=7200000 (720000 value is an example; time is measured in milliseconds)
Required for Multi-Geo migrations: For custom non-standard URLs being used for the SharePoint Admin center in O365, add OneDriveProExportAdminUrl=<non-standard URL> (Source tenant) and/or OneDriveProImportAdminUrl=<non-standard URL> (Desination tenant). Replace "<non-standard URL>" with your custom URL (do not include the ") being used for the SharePoint Admin center.
Permission mapping for files and folders
The two Advanced Options outlined below function independently of each other. However, they are complementary options that can be used together. We suggest using MapPermissionEmailByPairsInProject as your primary auto-mapping option and then adding UserMapping to take care of any outliers and avoid interruptions to your migration.
Map Permission Email by Pairs
In scenarios where the prefix of the User Principle Names are to change during a migration, you will need to add the following for automapping of permissions based on the source and destination User Principle Names you have entered in the project. This option is only valid where OneDrive for Business is the destination.
Support Option: MapPermissionEmailByPairsInProject=1
Environment(s): OneDrive (Destination)
Migration Type(s): OneDrive as destination only.
Important: If you have user OneDrives migrating for the same customer in multiple projects, you must enter the following support option in each project instead of MapPermissionEmailByPairsInProject: MapPermissionEmailByPairsInCustomer=1
Description: When OneDrive is the destination, this option can be used to map permissions by pairs in the project. firstname.lastname@example.org to email@example.com.
Use the UserMapping advanced option when you want to customize the permission mapping for a user or group.
Please note that the destination user/group (firstname.lastname@example.org) must have been commissioned and be available at the destination document library before migration.
Set Number of Versions to Migrate in the Advanced Options Under the Source/Destination tab
Set the 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. The default number of versions is 3.
Multi-Pass Behavior for Migrating File Versions
During the first migration pass/run, a file and its associated versions will be migrated to the 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 the destination. If a version is deleted for a source file, it is not identified as a change in the 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.
Run Verify Credentials
Open the Project containing the items you wish to validate.
Select the items you wish to validate.
Click on the Start button in your dashboard.
Select Verify Credentials from the drop-down list.
Once complete, the results of the verification will be shown in the Status section.
To lock (set to ReadOnly) the OneDrive items prior to migration:
Make sure all OneDrive line items are not locked.
Run Verify Credentials pass for all OneDrive line items. This will add the provided credentials as a site collection administrator for these items.
You can now lock all the OneDrive line items.
Run a full migration pass.
Send out the final notification that the migration is beginning. Include when the migration will start, expected duration, any usage instructions during migration, and any expected steps or notifications for the post-migration timeline. Remind them to avoid modifying any documents at the Source, as this may cause corrupt data or an incomplete migration.
From the MigrationWiz interface: (If you do not wish to perform a Pre-Stage pass, skip to the Full Migration Pass steps)
Select the users you wish to migrate.
Click the Start button from the top.
Select Pre-Stage Migration.
Under the Migration Scheduling section, from the drop-down list, select 30, 60, or 90 days ago.
Click Start Migration.
Perform a Full Migration
Select the users.
Click the Start button from the top.
Select Full Migration from the drop-down list.
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. (Steps outlined earlier in this migration guide)
Click Start Migration.
Once complete, the results of the migration will be shown in the Status section.
Addressing Project Errors
Look through the user list and click any red "failed migration" errors. Review the information and act accordingly.
If problems persist, contact using the steps outlined in this link: Support.
On the All Projects page in MigrationWiz, click the pie chart icon for the project you want to request a statistics report (far right-hand side of the page). An email containing all the project migration statistics will be sent to the BitTitan account for the project.
Post Migration Steps
Remove the Authentication App
To remove the BitTitan Enterprise app, perform the following steps:
Connect PowerShell to Microsoft 365.
Enter the command: Connect-AzureAD
Enter the admin credential in the prompt.
Enter the command: Get-AzureADServicePrincipal -SearchString Migration
Look for the ObjectId of the app you want to remove and enter the following command: Remove-AzureADServicePrincipal -objectId <the object id>
Decommission source accounts
To prevent users from inadvertently logging in and using their Source accounts, decommission their Source OneDrive for Business user accounts, or change the passwords for the source accounts.
Notify users once the migration has been completed. If you set the MigrationWiz Advanced Option for Notifications, they will receive an email upon migration completion. Assist them with setting up access to their OneDrive for Business accounts, and setting up their synchronization settings.