OneDrive to OneDrive for Business (with Versions and Metadata) migration guide

This is the guide for OneDrive for Business to OneDrive for Business migrations which include versions and metadata. Read the following steps carefully and ensure all the prerequisites are met before beginning the migration.

To learn more about permissions for this migration type, read our Application Permissions documentation. For more information on OneDrive migrations, see our FAQ.

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. 

Limitations

Personal site provisioning at destination is not supported. User will need to manually provision the personal site at the destination before starting a migration with this new destination endpoint. To provision your OneDrive site, follow the steps provided by Microsoft.

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.

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

Which Items Are and Are Not Migrated

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

Migrated

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)

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

When setting up the source environment there are two authentication options to choose from: 

  • Delegated admin rights

or

  • App-based authentication (the preferred method as it is more secure and avoids throttling)

Create an Administrator Account using Delegated administrator rights

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. 

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.

Process:

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

  2. Set the administrator privileges. Grant one of the permission levels listed below. 

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

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.

Export Users

Export the list of OneDrive for Business user accounts to a CSV file. This can be used when adding users on the Destination, and when adding the users to the project in MigrationWiz. 

Set up the app-based authentication in both Microsoft 365 tenants

You can elect to use an authentication app instead of delegated admin access. 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.

Important: If you opt to use app-based authentication, this app must be added in both .microsoftonline.com tenants (Source and Destination) to reduce the throttling and failures due to Microsoft throttling policy changes.

If this app is not added on both tenants, MigrationWiz will attempt to create a temporary substitute app in the tenants to be used for authentication. We do not recommend relying on this substitute app creation, as this behavior will only be a temporary transitional behavior within MigrationWiz. To avoid potential interruptions or failures in migrations, it is strongly recommended to set the app up in the tenants.

Add the App to the tenant

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

  1. Ensure you are signed in as a Global Admin.
  2. Go to either MigrationWiz-SharePoint-ReadOnly or to MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
  3. Create new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal. 
  4. Complete the following steps in MigrationWiz:
    1. Create new user.
    2. Add new user to previously created security group as a member.
    3. Create the MigrationWiz project.
    4. When creating the endpoints, enter the new user credentials.
  5. Add support option UseApplicationPermission=1 

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.

Preparing the Destination

If you are performing a GCC/China migration, use the OneDrive for Business to OneDrive GCC/China Migration Guide instead.

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

App-Based authentication

The easiest approach 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, a new user account can be created instead. This new account will then need to have a license assigned that includes OneDrive for Business and be granted either Global Administrator permissions or SharePoint Administrator privileges.

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.

Process:

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

  2. Grant the new user Global Administrator permissions or SharePoint Administrator rights in Office 365.

  3. Ensure that the administrator account is set to use Basic authentication rather than Multi-Factor authentication.

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.

Using Application permissions, it is a pre-requisite that the user's OneDrive to be pre-provisioned at Destination before Migration can begin.

If you elected to use app-based authentication, perform the following steps:

Add the App to the tenant

Steps to enable permission level at 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 new Security Group named “MigrationWiz” on the Office 365 Admin Portal.

  4. Create new user.

  5. Add new user to previously created security group as a member.

  6. Create MigrationWiz project.

  7. When creating the endpoints, enter the new user credentials.

MSPComplete Steps

Create Customer

  1. Click the Add button in the top navigation bar

  2. Click the Add Customer button on the All Customers page

  3. In the left navigation pane, select the appropriate workgroup and then click All Customers.

  4. Click Add Customer.

  5. Enter the new customer’s information in the Add Customer form. Primary Email Domain and Company Name are required. The rest are optional.

  6. Click Save.

  7. Repeat steps 1 through 4 for each customer you want to add. 

Purchase licenses

We recommend that you purchase the User Migration Bundle license for this migration scenario. User Migration Bundle licenses allow multiple types of migrations to be performed with a single license. They also allow DeploymentPro to be used to configure Outlook email profiles. For questions on licensing, visit MigrationWiz Licenses.

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 User Migration Bundle licenses.

  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.

Apply licenses

  1. Select the correct workgroup on the top of the left navigation pane. This is the workgroup that the customer and migration project were created under. Your account must be part of the workgroup if the project was not created under your account.

  2. On the left navigation pane, click Customers.

  3. Click the customer that employs the user to whom you want to apply a User Migration Bundle license.

  4. Click the Users tab at the top of the page.

  5. Check the box to the left of the email for the user(s) to whom you want to apply a license.

  6. Click the Apply User Migration Bundle License button at the top of the page. It is recommended that users be added to the Customer page with the vanity domain. 

  7. If there is at least one unassigned User Migration Bundle license available for each selected user, click Confirm.

MigrationWiz Steps

Create a Document Project

  1. Log in to MigrationWiz.

  2. Click the Go to My Projects button.

  3. Click the Create Project button.

  4. Select the Document project type. 

  5. Click Next Step.

  6. Enter a Project name and select a Customer.

  7. Click Next Step.

  8. Select endpoints or follow the steps below to create new endpoints. 

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.

You may either use existing endpoints, or create new ones. 

To create a new source endpoint:

  1. Click Endpoints

  2. Click Add Endpoint

  3. Select OneDrive for Business. 

  4. Enter the administrator username and password in the proper fields.

  5. Enter the Azure Storage Account Name and Azure Access Key or select Microsoft provided Azure Storage.

  6. Click Add Endpoint. 

To create a new destination endpoint:

  1. Click Endpoints

  2. Click Add Endpoint

  3. Select OneDrive for Business. 

  4. Select OneDrive for Business (Office 365 User) - Documents, Permissions, Versions and Metadata

  5. Enter the administrator username and password in the proper fields.

  6. Enter the Azure Storage Account Name and Azure Access Key or select Microsoft provided Azure Storage.

  7. Click Add Endpoint. 

OD_1.png

Add Items to the Project

To add the user accounts (also called "Line Items") that will be migrated into the project using the CSV file created in the Prepare 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 users Source and Destination address must be entered as 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.

Advanced & Support Options

Add the following options in the Advanced Options and Support Options tabs: 

  • For non-standard URL endpoints, add OneDriveProExportAdminUrl=<non-standard URL> and OneDriveProImportAdminUrl=<non-standard URL> (replace "<non-standard URL>" with your custom URL). 

  • InitializationTimeout=8 - This increases the initialization timeout window to eight hours. This is especially useful for large migrations.

  • Set the Advanced Option to send a notification to end users after the migration pass completes. (This is optional.)

    1. Notifications

    2. Send successful migration and notification to:

    3. Source email address (if users are still using the original Source Office 365 tenant) or Destination email address (if users are already using the Destination Office 365 tenant).

    4. Customize notification email. Checkmark the Customize "successful migration" email Add your own customization text and company name to this email.

    5. Notifications should only be set up before the final pass. If performing a single, Full pass, set this up now. If you are following a Pre-Stage migration strategy, only set this up prior to the final Full (Delta) pass.

  • If the migration project is a long-term project, it may be necessary to add an additional Advanced Option for use during the final migration pass to verify the contents of previously migrated items. For more information, contact Support.

  • If App Based Authentication is in use at the Destination, add DestPersonalSiteIsProvisioned=1

Map Permission Email by Pairs

In scenarios where usernames change during a migration, you will need to run the following command to ensure permissions map to the new username:

Option Command: MapPermissionEmailByPairsInProject=1

Environment(s): OneDrive (Destination)

Migration Type(s): OneDrive as destination only.

Important: Permissions generally cannot be migrated unless the prefix of the mail address is the same in the source and the destination. However, choosing Support Option MapPermissionEmailByPairsInProject=1 will allow permissions to be migrated without identical mail addresses.

Description: When OneDrive is the destination, this option can be used to map permissions by pairs in the project. user@domain.com to firstinitial.lastname@domain.com.

Under the 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. The default number of versions is 3.

OD_2.png

Run Verify Credentials

  1. Open the Project containing the 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.

Notify Users

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 and incomplete migration.

Run Migration

From the MigrationWiz interface:

Pre-Stage pass

  1. Select the users you wish to migrate.

  2. Click the Start button from the top.

  3. Select Pre-Stage Migration.

  4. Under the Migration Scheduling section, from the drop-down list, select 90 days ago.

  5. Click Start Migration.

Perform a Full Migration

  1. Select the users.

  2. Click the Start button from the top.

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

  4. Ensure that the DocumentsDocument PermissionsMetadata, 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.

    OD_3.png
  5. Click Start Migration.

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

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.

SPO_1.png

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.

Run Retry Errors

Look through the user list and click any red "failed migration" errors. Review the information and act accordingly.

If problems persist, contact Support.

Request Statistics

Click the pie chart icon in the MigrationWiz dashboard to receive an email containing all the project migration statistics.

Post Migration Steps

Remove the Authentication App

To remove the BitTitan Enterprise app, perform the following steps:

  1. Launch PowerShell.

  2. Connect PowerShell to Microsoft 365.

  3. Enter the command: Connect-AzureAD

  4. Enter the admin credential 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>

Click the bar chart icon in the MigrationWiz dashboard to receive an email containing all the project migration statistics. 

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 their passwords.

Notify users

Notify users once the migration has 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.

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