Walkthrough: Migration Manager

In this post we will take a detailed look at the Migration Manager, it’s capabilities, limitations and how to create pre-scan and migration tasks for the first time.

Contents

Overview

So the good news is, if you have a Microsoft 365 subscription then you also have the Migration Manager too! The Migration Manager went into general availability in June 2020 for all customers as part of the SharePoint Online offering.

The Migration Manager is a part of the SharePoint admin center and is really simple and easy to get set up and begin using. Microsoft have this handy image to demonstrate how easy the process is:

Set up migration agents
Credit: https://docs.microsoft.com/en-gb/sharepointmigration/mm-get-started

Current limitations

Currently, the Migration Manager only supports file share migrations, this means that if you are planning to migrate any other content you hold, for example: on-premise SharePoint content or cloud based content you would need to use a separate tool.

Microsoft also offer several other tools that can facilitate the migration of that content too. Microsoft provide a table which recommends which tool to use here, but I’ve whittled them down to the main options below:

  • Migration Manager: used for network and local file share migrations, easy to set up via the SharePoint admin center
  • SharePoint Migration Tool: used for SharePoint Server 2010, 2013 & 2016 (Public Preview), network & local file shares, requires some prerequisites configuring before installation
  • Mover: Service for cloud to cloud migration (Dropbox, Google Drive etc.), easy to set up via web platform

Another limitation of the Migration Manager is that it currently does not support third party multi-factor authentication.

Setup considerations

So as the above breakdown of each Microsoft migration tool suggests, the Migration Manager is easy to get going. The key consideration when using this tool to migrate file share content is around the volume of data you are migrating.

If you are using the Microsoft FastTrack service, they will recommend that you set up a number of migration machines relative to the total number of files you are migrating.

The recommendation they offer for scoping this is below:

Total file countMigration machines required
Less than 200,0002
Between 200,000 and 500,0003
Between 500,000 and 1,000,0006
More than 1,000,000To be discussed with FastTrack

Once you decide how many migration machines will be required, you will then need to setup the migration agents on each machine, check the prerequisites and required endpoints have been reviewed and met, and also have the relevant accounts being used as part of the migration process given access to the file share content and SharePoint admin roles.

File and folder permissions

When prepping for your file share migration, another consideration will be the permissions of a file once it is migrated. For most organisations it comes down to the following scenarios:

1. We want all file/ folder permissions preserved when they migrate to SharePoint Online

2. We only want specific file/ folder permissions mapped into SharePoint Online

3. We don’t want any of the permissions migrating, we want to start again!

Yes, I know the third option is highly unlikely, but I’ll include it anyway. When using the Migration Manager, the syncronization between your Active Directory on-premise and Azure Active Directory is key to how permissions migrate across.

It is important to note that if your organisation uses security groups in Active Directory to manage permissions for their file shares, they must be syncronized with Azure Active Directory in order for the user permissions to map across like-for-like.

If not, then you will be required to create a user mapping file to map user permissions for the relevant files or folders.

The Migration Manager also takes into account the same permissions conditions and results as the SharePoint Migration Tool. This table lists all the conditions and the corresponding results.

Demo: create a scan only task

Before you run any sort of migration task you will first want to get a handle on the current situation of your file share content, what areas will migrate easily and which will require remediation.

Both the scan and migration actions sit within Tasks in the Migration Manager and the initial setup for both actions is the same:

  • Press add task > under Method select the default single source and destination (unless you wish to scan multiple sources)
  • Under Source, enter the file share path that you wish to scan using the correct format
  • Under Destination, leave the SharePoint site URL and location as the default as we are only performing a scan
  • Under Settings, give your task a name > under common settings ensure perform scan only is checked
  • Press Run Now

Demo: create a migration task

So once you have ran a pre-scan of your file share source and you are happy with the results, it is now time to create a migration task! This again is very similar to how we approached creating the pre-scan task but here are the steps:

  • Press add task > under Method select the default single source and destination (unless you wish to scan multiple sources)
    • If you wish to do a bulk upload, you will need to provide a CSV or JSON file which is well documented here
  • Under Source > enter the file share path that you wish to migrate using the correct format
  • Under Destination > enter the URL of the SharePoint site, then select the library you wish to migrate to
  • Under Settings > enter a name for you task and configure your migration task based on the following check boxes:
    • Preserve file share permissions
    • Migrate hidden files
    • Migrate files created/modified after specified date
    • Do not migrate files with specific extensions
    • Migrate files and folders with invalid characters
    • Migrate OneNote folder as OneNote notebook
    • Azure Active Directory lookup
    • User mapping file
    • Automatically rerun failed tasks up to 4 times
  • Press Run Now

Reports analysis

Whether you have performed a pre-scan or migration in Migration Manager, each task once complete will provide a “task report” zip folder that is available to download. Microsoft break the reports down into Summary, Task level and Performance reports, but in fact all reports are included as part of the task report download.

The Microsoft breakdown of each report is very thorough, so I won’t bother adding any more detail, however I will highlight the reports that I found useful when using the Migration Manager:

  • Summary Report: contains a single row of data that gives the total picture; including total size, number of files migrated, duration
  • Item Failure Report: contains any errors found resulting in a file being unable or failing to migrate
  • Item Report R1: detailed report with data on each file within a task. If large number of files migrated, split into separate, sequential reports (R1, R2, R3 etc.)

An interesting aside I did notice was on the task details pane for a pre-scan I ran it showed under files scanned with issues as 0, but within the task report ZIP there was, in fact several files and folders listed as having failed due to a variety of reasons. So I’m not really sure how accurate the files scanned with issues is, or what it actually defines as issues.

Troubleshooting

Microsoft documentation includes a page on troubleshooting Migration Manager issues and errors here, but typically during a recent migration I experiencing issues that weren’t including in the above.

Error: the source file share does not exist (but it does)

This error I received recently during a home drive – OneDrive migration I was conducting. I was using windows virtual machines with the migration agents installed previously and had logged into the machine and SharePoint admin center as accounts with the relevant permissions and roles as described here by Microsoft.

When I set up my migration tasks as demo’ed above they were instantly failing. The only errors I would receive were these:

Microsoft have this listed as an agent error message – which was the clue, but their action was to:

Make sure the source file share is an existing network file share. Confirm that the Windows account associated with the agent has read permissions to the file share you want to migrate.

Troubleshoot Migration Manager issues and errors

What I found was in my case, even if the migration agents were showing as enabled, because I had originally installed and configured the agents some time ago (1-2 months prior), they need to be repaired and re-authenticated:

  • Download the migration agent setup file
    • Microsoft documentation hasn’t yet been updated, but to get to the agent download you need to open Migration Manager > Press Agents > + Add
  • Run the agent setup file
  • Press continue to reinstall the agent
  • The installer will then begin the installation prerequisites
  • Enter account credentials for the SharePoint Admin, then Windows account
  • The installer will authenticate, then prompt you to test permissions with a file share, press OK to close

Now, when I re-ran my migration task with my agents repaired and re-authenticated, the tasks completed successfully.

One thought on “Walkthrough: Migration Manager

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s