Office 365 Hybrid Mailbox Migration Management

2014/10/02 Update: New Version 1.1 has been released - fixed a bug that always causes moves to be suspended.

If you are going to use the Large Item Limit switch, please use it cautiously and ensure your users have the large items backed up.

I wanted to share a small personal project I've been working on with you.

I was finding it cumbersome and painful to keep track of my migrations into the cloud at my customers so I decided to build something quick and easy that can be executed from anywhere.

The aim of this was to allow me to:

  1. Migrate batches of On-premise mailboxes to Exchange online in a Hybrid deployment by using a centralized location.
  2. Get some idea of how long the moves will take,
  3. Keep track of the mailbox moves,
  4. License the mailboxes,
  5. Suspend moves if required and resume them when you need to.
  6. Get an overview of all the license assignments in the tenant.

The outcome was a simple spreadsheet that uses VBA to call PowerShell code depending on the functionality you want.

It’s relatively straightforward, the Excel file contains the following main sheets:

Mailboxes – this sheet contains the main mailbox data that the other areas use to build csv files for the PowerShell scripts.

Planned_Batch – this sheet is where most of the functionality is. In here you can Activate Licenses, Export Scripts for manual execution, initiate the mailbox migrations, show current moves, resume any suspended moves or just open a remote PowerShell session to Office 365.

The following buttons exist on this sheet:

  • Refresh: Updates list based on Move_Variable in Mailboxes sheet
  • Activate Licenses: Assigns a license to the users in this list.
  • Export Scripts: Exports scripts for manual running.
  • Migrate Mailboxes: Kicks off migrations for listed mailboxes.
  • Show InProgress Moves: List current In Progress Moves
  • Resume Suspended Moves: Resume move requests that have been previously suspended.

You will need to populate all the areas marked with yellow with your relevant tenant details:

  • Megabyte per minute during testing – What is your average MB/min that you achieved during the testing\pilot phase? You can get this value from the Move_Request_Statistics sheet – you obviously will need to have moved some mailboxes with data to get a more accurate value here.
  • Hybrid Namespace – your on-premise hybrid namespace ex.
  • Target Delivery Domain – the target delivery domain ex.
  • License – The license you want to assign to the mailboxes.
  • Tenant name – Name of your tenant.
  • Bad Item Limit – the BadItemLimit you want to use during migrations.
  • Large Item Limit - the Large Item Limit for the move request. WARNING: This will result in items being skipped that are larger than the threshold allowed.
  • UsageLocation – the short name for your usage location for licenses. Ex. South Africa is ZA.

There are two option buttons:

  • Suspend moves on completion – this will suspend the move request once the move is ready to be finalized.
  • Finalize moves on completion – Mailboxes will finalize immediately once they are in final stages of the migration.

Moved – Once your planned batch has been successfully migrated you mark the batch completed by changing the Move_Variable to “Moved”. This will allow the moved sheet to be updated with the relevant mailboxes that have been migrated to help you keep track of your migrations.

Move_Request_Statistics – This sheet allows you to track the data on the all your move requests. When you click on the Get-Statistics button it opens a remote PowerShell session to get some data from your current move request and export that to a csv file to the location you specified. You can then import this file and use the Average MB/min to help with the timing calculation in the Planned_batch sheet.

License Report - The two Licensing sheets allows you to export the raw license data from your tenant and import the data into the file. You can then use this report to reconcile your licenses and get an overview of the license situation.


Ok, so that covers the sheets and their functionality. So how would I start with this:

First download and install the Windows Azure Active Directory Module for Windows PowerShell:

When you open the Excel spreadsheet you will first need to populate the mailboxes sheet by running the following within the Exchange 2010/2013 management shell:

 $mbx=Get-Mailbox -resultsize unlimited; $mbx | foreach-object {$UPN = $_.UserPrincipalName; $EmailAddress = $_.PrimarySmtpAddress;$OU = $_.OrganizationalUnit; $Type = $_.RecipientTypeDetails; $_ | Get-MailboxStatistics | select @{Name="UPN";expression={$UPN}},@{Name="EmailAddress";expression={$EmailAddress}},@{Name="Type";expression={$Type}},@{Name="OU";expression={$OU}},DisplayName,@{Name="TotalItemSize(MB)";expression={$_.TotalItemSize.Value.ToMB()}},LastLogonTime}|Export-csv .\Mailboxes_Output.csv –notype

The above will export the required data to a CSV file which you can then import into the Mailboxes sheet by using the button provided.

When you want to target a couple of mailboxes for migration you simply mark the Move_Variable column in the mailboxes sheet with an “X”.  Refreshing the Planned_Batch sheet will populate the targeted mailboxes for migration.

I didn’t want to build an elaborate system that uses a database and a front end, because I wanted something quick and easy to use and for me this works. I’m sure there are some brilliant minds out there that will definitely have something to add so feel free to add wherever you want and share. The code is open and available to modify as you see fit.

One more thing, this spreadsheet is in no way an Official Microsoft Office 365 Tool and not maintained by Microsoft, it’s essentially a Michael maintained tool developed to make my life easier during mailbox migrations :-)

Download the tool here.

If you have any questions or want to give some feedback feel free to e-mail me here - or ask in the comment section below.

Happy mailbox migations! 

Michael Hall