Skip Ribbon Commands
Skip to main content

File Server (Home Directories) to OneDrive for Business Migration Guide, Using PowerShell

Last Update: 7/21/2017 11:32 AM
This article has been moved to our new Help Center. Please update your bookmarks.

​​​​​​File Server (Home Directories) to OneDrive For Business Migration Guide, Using PowerShell

Important: When you sign in to MigrationWiz, you are redirected to the Getting Started page in MSPComplete. To go to a migration project created before April 4, 2017, click the Go to Projects button on the Getting Started Page. To create a new project for the migration scenario documented in this article, go to the Delivery Center and add an Doc: File Server Home Directories to OneDrive for business (PowerShell)​ service to the customer. Read the Delivery Center article for more information about adding services to a customer.


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

We recommend this strategy when migrating a large number of home directories. When migrating a smaller number of home directories, follow the steps in KB005477.

When migrating file shares from the file server, follow the migration guide specific to that scenario. Typically, file shares will be migrated to SharePoint Online Site libraries.

The diagram below provides a high-level overview of the steps involved in migrating a large number of home directories. The key difference for this type of migration scenario is that this requires an Azure subscription, and the use of the BitTitan UploaderWiz utility to upload the home directories to Azure, before they can be migrated into the OneDrive for Business accounts using MigrationWiz. It also uses a combination of a PowerShell script and a CSV file, which automates the building of the MigrationWiz projects, with all of the Advanced Options preset. There is also no need to create endpoints in MSPComplete prior to running MigrationWiz, because the PowerShell script automates the creation of the endpoints on the first run, and includes checks for subsequent runs so that it can use the existing endpoints that were created from the first run.


​Prepare Azure Environment

  • Estimate Azure storage costs. Note: This step is optional, but it is useful in order to provide the customer with up-front storage costs ahead of time. KB005177
  • 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). KB004996
  • Create an Azure storage account, and take note of the Storage Account Name and the Primary Access Key: in Azure, from the storage screen, click on Manage Access Keys at the bottom of the screen. These need to be entered into the authorizationsettings.csv file under the columns of the same name. We recommend that you create an Azure Storage Account in the same Microsoft data center as the Destination Office 365 tenant. Note: There is no need to create any Azure containers for this migration. Separate containers are created on a per-home directory basis. During migration, MigrationWiz will create two separate metadata files (with 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. KB004832

Prepare machine(s) for PowerShell and UploaderWiz  (Note: We recommend that you perform these steps from a domain-joined computer, when logged in with local admin rights.)

  • Set up the BitTitan PowerShell.


    • Prerequisites for installing BitTitan PowerShell are detailed in KB005158. These are:

      • Microsoft Windows PowerShell 4.0

      • Microsoft Framework 3.5,

      • Microsoft.NET Framework 4.6.21 

      • Uninstall any previous versions of MigrationWiz PowerShell, or BitTitan PowerShell, on the machine that you will be running the PowerShell scripts from.

        • Notes:

          • Older versions will be listed as "MigrationWiz PowerShell" under your program list in Control Panel. This was because earlier versions were known as "MigrationWiz PowerShell" rather than "BitTitan PowerShell".

          • Versions that were installed after October 5, 2016 will be listed as "BitTitan PowerShell".

    • Install the BitTitan PowerShell msi package from hereNote: At the Windows Protected your PC prompt, click on More info > Run anyway. Accept defaults during installation and answer to prompts. This will install to the default directory: c:\Program Files (x86)\BitTitan\BitTitan Powershell\ .
  • Create the directory c:\apps\uploaderwiz, and then download and extract the Uploaderwiz utility from here (e.g., extract into the c:\apps\uploaderwiz directory).
  • Create directory c:\scripts and then download the zip file containing the three (3) PowerShell scripts and authorizationsettings.csv file ​from ​here (e.g., create and save into c:\scripts directory, then extract all into the same scripts directory).   


    • The folder name must be one word only. It must also be text only, and not contain any spaces.
    • The three (3) scripts, which will be run under the MigrationWiz steps section, are: Log_Functions.ps1,, and RunSubmission.ps1.
  • Map a network drive to the home directory root folder on the file server.

Prepare the Destination Office 365 Environment

  • Set up the Office 365 tenant. The Destination must be OneDrive for Business, not the free personal OneDrive version that comes with (a.k.a.
  • Add users and assign SKUs. This is required if permissions are being migrated.
  • Assign a SKU to the Office 365 global admin account being used for migration; often this will already have a SKU assigned. This is required for MigrationWiz to provision the OneDrive for Business accounts during migration.

Upload Files to Azure  (Note: These steps are performed from the machine that was prepared for PowerShell and UploaderWiz)

  • From Windows Explorer, go to the mapped network drive for the file server. Set the home directory migration batch to read-only access by user, and inform each user that a migration is occurring and that their home directory is now read-only. This will prevent users from adding any files to their home directory during the migration.   KB005479
  • If migrating home directories in batches, then from Windows Explorer, go to the mapped network drive for the file server. Under the home directory root folder, create a directory named staging_batch.  Copy the batch of home directories that will be migrated, into this staging_batch directory. When running UploaderWiz, this is referred to as -rootpath.  Note: Make sure that any previous batches are deleted from this staging directory prior to copying new directories into here; otherwise, they will also be included in the upload to Azure.
  • From a command console, change to the directory that Uploaderwiz was extracted into (e.g., c:\apps\uploaderwiz), and run the following command. Note: Replace the x's with your own information. KB004997 

UploaderWiz -accesskey "xxxxxxxx" -secretkey "xxxxxxxxxxxxxxxxxxxxxxx" -type azureblobs -rootpath "xxxxxxxx" -homedrive true

    • Notes: 
  • If there are problems with the upload, for troubleshooting help, refer to KB005473.
  • 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, and the rootpath needs to match this drive letter, followed by the directory path, e.g., "x:\staging_batch" (if there are spaces in the path, you need to surround the path with quotes).

MSPComplete Steps   (

  • Create the customer. KB005421
  • Purchase Document licenses. Purchase >Document Migration >MigrationWiz-Document licenses.  KB004647

Migration Steps   (Note: these steps are performed from the machine that was prepared for PowerShell and UploaderWiz)

  • Fill in all columns in the AuthorizationSettings.csv file for the user home directories that will be migrated in the migration batch.
    • Notes:
      • The recommended directory, specified in the Prepare Machine(s) for PowerShell and UploaderWiz section above, was c:\scripts.
      • Here is the list of BitTitan data centers that can be set: Canada, NorthEurope, NorthAmerica, WesternEurope, AsiaPacific, Australia, Japan, SouthAmerica. 
      • Once you have completed the first entry row, copy the entries for AccessKey, SecretKey, ODFBAdmin, ODFBPwd, BitTitanDatacenter and CustomerName into each subsequent row.
      • In the "SourceFolder" column, enter the name of the container that exists in Azure for each home directory to be migrated, one per row.
  • Launch Windows PowerShell, and run the following command: Set-ExecutionPolicy Unrestricted. Note: This allows scripts that are not digitally signed to run in your PowerShell window.
  • Run the projectimport.ps1 script. This sets up the projects. Upon completion, it will run a verify credentials against every MigrationWiz project that was created by the script.
    • Notes:

      • Run the script, using the Windows PowerShell. Change to the directory that you extracted the scripts into, e.g., c:\scripts:> .\projectimport.ps1

      • When prompted for credentials, enter your BitTitan credentials.

      • All projects will be created with a name set to destinationemailaddress_ps. The '_ps' is used by the Full migration pass script (RunSubmission.ps1) so that it only starts migrations for those projects matching this name criteria.

      • This script will set all the neccessary Advanced Options. These include:

        • Licensing/Maximum licenses = 5. This will allow up to 50GB to be migrated per user. If there are any users with more data than this, you will need to go into the individual project for the user, and manually set this project Advanced Option to a higher number.  KB004890
        • Add ShrinkFoldersMaxLength=200 under Support/Support optionsKB005007

        • Add RenameConflictingFiles=1 under Support/Support options.   KB005058  Refer to the section in this article with the heading "Multiple files with the same name limitation".
        • InitializationTimeout=28800000 under Support/Support optionsKB005242                     
        • Preferred BitTitan Data Center. This will reflect the entry from the AuthorizationSettings.csv file, under the BitTitanDataCenter column.   KB004268
  • Run the RunSubmission.ps1 script (e.g., c:\scripts:> .\RunSubmission.ps1). This performs a Full migration pass.

    • Notes:

      • When prompted for credentials, enter your BitTitan credentials. You can set your BitTitan account credentials within this script (but these could then be seen by others who have access to the script). This will avoid being prompted to enter your BitTitan account credentials.

      • Once the script completes, launch MigrationWiz and enter one of your projects. You can then monitor the progress of the migration.

Post-Migration Steps

  • Remove access to the Source home directories.
  • Provide training on OneDrive For Business.
  • Delete directories from the staging directory; this is the directory that home directories were copied to prior to uploading them to Azure.  Note: Once all home directory batches have been completed, and all file shares and other data have been migrated, the Source file server can be decommissioned.
  • Delete all the Azure blob containers that were created during the upload to Azure.
    • Note: 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.