1. BitTitan Help Center
  2. Perform a Migration
  3. Other Document Migration Types
  4. File Server Migrations
  5. File Server Home Directory Migrations

File Server Home Directories to OneDrive for Business Migration Guide

This Migration Guide provides the procedures to be followed for migrating home directories from Windows File Servers to OneDrive for Business.

This strategy is only recommended when migrating a small number of home directories. When migrating a larger number of home directories, PowerShell scripts, and a CSV file can automate the process. Refer to File Server Home Directories to OneDrive for Business Migration Guide, using PowerShell for step-by-step instructions, and to obtain the scripts and CSV file.

First migration?

We’ve created a guide on scoping, planning, and managing the migration process for your use. If this is your first migration, we recommend reading this guide carefully.

MigrationWiz

MigrationWiz is a migration tool, not a syncing tool. If changes are made at the source after migration, they will not sync to the destination, nor will changes made at the destination sync to the source. 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.

MigrationWiz supports the capability to share migration projects across a Workgroup. When the Project Sharing feature is turned on, all Agents besides those who are Inactive can view all migrations projects. 

Prerequisites

Please consider meeting the following prerequisites before starting your migration process.

Licensing

We recommend that you purchase User Migration Bundle licenses for this migration scenario. User Migration Bundle licenses allow the performance of multiple migrations with a single license. For questions on licensing, visit MigrationWiz Licenses.

To use your license by following the next steps:

  1. Purchase Licenses.
  2. Create a Customer.
  3. Apply Licenses.
  4. Review Considerations.
Purchase Licenses Create a Customer Apply 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 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.

Limitations

Please consider the following limitations for this type of migration:

  • Note that OneDrive data may not be accessible for a few days after migration, due to OneDrive's crawling and indexing process. We suggest having your users log in immediately after migration but warn them that their data may not be available immediately. For this reason, it may be best to complete the migration on a Friday so the indexing can happen over the weekend.
  • We are not able to support migrations with two-factor or multifactor authentication. 

Prepare the Azure Environment

  1. Estimate Azure storage costs. This step is optional but is useful in providing the customer with upfront storage costs ahead of time.
  2. Buy an Azure subscription, or use the free one-month trial ( this option is only viable if you are performing a very small migration).
  3. Create an Azure storage account. We recommend that you create an Azure Storage Account in the same Microsoft data center as the Destination Office 365 tenant. 
    1. Visit ​https://portal.az​ure.com​ 
    2. Click Storage accounts.​
    3. Click Storage Create.​
    4. Select the subscription in which you want to create the new storage account.
    5. Select your Resource group.​ Create a new one if it doesn't exist.
    6. Enter a name for your storage account.​
    7. Choose your datacenter Location.
    8. Choose Standard performance
    9. In the Replication field, select Locally Redundant Storage (LRS).
    10. Click Review.
    11. Click Create.
    12. Once the deployment shows as complete, click on Go to resource.
    13. Select Access keys under "Security + Networking".
    14. Copy the Storage account name and the key 1.  You will use this when running UploaderWiz and within the migration project.

You do not need to create any Azure containers for this migration. Separate containers are created on a per-home directory basis as they are uploaded. During migration, MigrationWiz will create two separate metadata files (with the extensions: -directory.metadata and -files.metadata), which will be added to each container. These are used during migration by MigrationWiz, to build the folder structure in OneDrive for Business and to migrate the permissions. They should not be deleted until after the migration.

Prepare Destination Environment

Please consider the following information when preparing your source environment.

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

OneDrive Prerequisites

  • Create an admin account in Microsoft 365 for the migration, or use the global admin account for the tenant.
  • The easiest approach to follow is to use the global admin account. This 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 be granted full access rights to each user.
  • The admin account must have a full license assigned to it, to provision OneDrive for Business profiles for each user during the migration process. 

Application Permissions for OneDrive

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 OneDrive and be granted Site Collection Administrator privileges to OneDrive 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 Administrator rights to a SharePoint or OneDrive 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.

If migrating to a GCC High tenant, the above steps will not work.  Instead, use the following steps.

  1. Ensure that the service account has a license which includes OneDrive
  2. Give the account Global Admin permissions.  If that is not possible, you can instead grant it Site Collection Admin permissions on the OneDrives that you want to migrate to.
  3. Authorize the MigrationWiz-SharePoint-Delegated app within the tenant
  4. Within the project, add OneDriveProImportEnvironment=AzureUSGovernment to the support section of the project's Advanced Options

Upload Files to Azure

Steps are performed from a file server, or a computer joined to the domain when logged in with the domain admin account, with local admin rights to the machine. This process utilizes UploaderWiz. Our guides contain information on running, configuring, and troubleshooting UploaderWiz. 

  1. (Optional, but recommended) Set the file share migration batch to read-only access by the user and inform the users that a migration is occurring and that their file shares are now read-only. This will prevent the user from adding files to these file shares during the migration.

You can restrict users to read-only access to their Home Directories through the Active Directory Users and Computers console on the AD controller, or via PowerShell.

Prerequisites

  1. Create a CSV file containing all the usernames (SAMAccountName).
  2. Install the required AD module on the machine that you're running the script from.
  3. Example script:  Import-Module 'ActiveDirectory'
    import-csv E:\usersname.csv | foreach-object{
    $homeDrive = (Get-ADUser -Identity $_.name -Properties homedirectory).homedirectory #Query AD for the HomeDirectory attribute
    $ACL = Get-Acl $homeDrive
    $ACL.setAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule($_.name, "Read", "ContainerInherit,ObjectInherit", "none", "allow")))
    Set-Acl $homeDrive $ACL
    }
  4. From the command prompt, running as administrator, from the directory that UploaderWiz was extracted into, run the following command (replace the x's with your own information): UploaderWiz.exe -accesskey "xxxxxxxx" -secretkey "xxxxxxxxxxxxxxxxxxxxxxx" -type azureblobs -rootpath "xxxxxxxx" -homedrive true

    Important

    If you are performing these steps from a domain-joined computer, a network drive needs to be mapped from the domain-joined computer to the file server (e.g. x;\File Server).

    Important

    Please consider the following information when replacing the fields with your information.
    • The AccessKey will be the name of the storage account
    • The SecretKey will be the access key for the storage account
    • The RootPath will be the path to the files that you want to migrate 
    • The parameter -homedrive true creates separate blob containers for each file share, under your top-level Azure blob container. 
      For example, if you have folders called User1 and User2 under C:\Users and you set the rootpath parameter to "c:\Users" then a container named "User1" and another named "User2" would be created in the Azure storage account and the files within those folders uploaded to each.

MigrationWiz Steps

Create a Document Project

This first project is the baseline project, from which all other projects will be cloned. We recommend that you call this "baseline", for easy reference.

  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.

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, along with any unique spellings or capitalization you may have used.

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. Name the endpoint. It is recommended that the endpoint name is unique for the project.
  3. Under Endpoint Type, select Azure File System from the dropdown menu.
  4. Enter the storage account name and access key.  This will match the account name and access key that you used in the UploaderWiz command.
  5. Click Add.
  6. 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.

Advanced Options

Support Tab

These options are added to the support section of the project's Advanced Options.  You can access this by clicking on Edit Project and selecting Advanced Options  To create new lines, simply click on the + button that you see when viewing that page.

  • ShrinkFoldersMaxLength=300  This option shrinks file path names to prevent issues during the migration. 
  • RenameConflictingFiles=1  This prevents errors due to files with duplicate names.
  • InitializationTimeout=8  This increases the initialization timeout window to eight hours.  This allows for larger migrations to complete the initialization phase without timing out.
  • If migrating to a GCC High tenant, also add UseApplicationPermissionAtDestination=0.  If you are also not using a Global Admin with the GCC High tenant, also add ForceOneDriveNonGlobalAdminAuthImport=1

There are no spaces on either side of the "=" sign, and the entries are case-sensitive, so pay special attention to the capital letters in the commands above.

Source/Destination Tab

In each cloned MigrationWiz project, set the container name that the files for that user were uploaded to.  This is done from the Source/Destination tab of the project's Advanced Options under the Source: File System/Container Name field.  By default, this is set to "migrationwiz" but it must be changed or the migration will fail. This must be set to match the name of the Azure container that was created on your Azure subscription when the home directories were uploaded in the previous step, under the "Prepare Source File Server Environment" section of this guide.

Clone the Project

  1. Click the Edit Project button.
  2. Select Clone Project from the drop-down list.
  3. Enter the name for the new Project (each new project should be named after the file share name).
  4. Click the Clone Project button.

Important

Repeat this process to create one MigrationWiz project per file share.  You should end up with one project corresponding to each Home Directory within your source environment.

Add Items

For each MigrationWiz project, add the OneDrive for Business account to migrate home directory files into. Select Add/Quick Add and enter the login name of the OneDrive for Business account within the Destination field labeled Email Address.).  This needs to be the UPN for the user in question or you could see errors occur when trying to migrate.

Run Verify Credentials

  1. Open the Project containing items you wish to validate.
  2. Select the line item within the project by checking the box next to it.
  3. Click on the Start button in your dashboard.
  4. Select Verify Credentials from the drop-down list.

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

Start Migration

  1. Select the users.
  2. Click the Start button from the top.
  3. Select Full Migration.
  4. Click Start Migration.

Run Retry Errors

If the migration is completed successfully, but there are errors, this will attempt those failed items again.

  1. Select the users.
  2. Click the Start button from the top.
  3. Select Retry Errors.
  4. Click Start Migration.

If the errors persist, click on the error count to bring up a list of the errors seen.  This can be useful in helping to determine why the items are failing so appropriate action can be taken.  If assistance is needed in investigating issues, please contact Support.

Post-Migration Steps

  1. Remove access to the Source home directories.
  2. Provide training on OneDrive For Business.
  3. Decommission file server. Perform this step only after migrating all data from the file server, such as file shares, and you are absolutely certain that you will not be returning to the file server.
  4. Delete all the Azure blob containers that were created during the upload to Azure. This will prevent incurring post-migration Azure costs for these containers. Be careful to only delete the containers created by UploaderWiz; these will be names that match the home directories and have a create date from the date of the upload.

 

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

Articles in this section