Michael's technical ramblings....

Interesting things I've found throughout my technical journey.

Office 365 Hybrid Mailbox Migration Management

Office 365 Hybrid Mailbox Migration Management

  • Comments 29
  • Likes

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. hybrid.contoso.com
  • Target Delivery Domain – the target delivery domain ex. contoso.mail.onmicrosoft.com
  • 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 -  technicalramblings@outlook.com or ask in the comment section below.

Happy mailbox migations! 

Michael Hall

  • Nice tool

  • Do you have to wait till the user has completed migration until you can assign them a license? Or with this tool can you assign them the license as a they finish migrating?

  • Jeremy,

    The tool will assign a license automatically depending on the licenses you select.


  • BRAVO.  Do you take donations in beer, paypal, or interesting souvenirs?

  • This is absolutely brilliant.

  • Michael,

    Recommendation for the mailbox move script after using it a while..   If there is not a matching proxy address, it would be awesome if it prompted you to go ahead and add one.  Now granted, that would require the local change to occur as well as a dirsync, so I understand why it might not be plausible...  but it would be awesome if it did.

    Thanks again for this tool.

  • Michael, I think I love you :)

  • Don't get me wrong Michael, still love you buddy, but can this tool in some way add a 'largeitemlimit' to each mailbox move command as well as the baditemlimit? I don't mind adding it in myself, but I'm a little unsure of the VB structure behind the scenes :)

    Aside from that, I'd like to report that I've managed my first batch using your tool successfully (apart from the users with large items of course). It's a very nice piece of kit. This might seem like a security threat, but is there any way we could embed the tenancy and on premises credentials somewhere. Just for temporary use?

    Yours very gratefully - Gavin

  • Sure could use large item limit options, unless I missed it.

    Looks awesome though, going to test a batch in a few minutes

  • I'm digging around in the VB Macro that does the mailbox migrations, trying to remember how to form a command call with references to variables so I can add -LargeItemLimit into it. Can anyone help?

    Michael has the variable "BadItemLimit" set at the top of his 'Migrate_Mailboxes' macro:

    BadItemLimit = wsPlanned.Range("L18").Value

    It gets it's value from the cell on the Planned Batch sheet L18. I've added another variable into the declarations, anjd I've prepared a call for this config on the spreadsheet. I'm using L24:

    LargeItemLimit = wsPlanned.Range("L24").Value

    I now need to alter the Call Shell Line in the macro to include the -LargeItemLimit switch and input the number from the variable. Sound easy right? ;)

    There is a bit of 'If Then' logic to choose the right command, dependent on what O/S you are using, and whether or not you've selected 'suspendmoves' but in short, this is the command. I'm focusing on the one tailored for 'suspendmoves':

    Call Shell("C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -noexit -file " & FileName & " -exportpath " & ExportPath & " -SuspendMovesWhenReady 1 -baditemlimit " & BadItemLimit, vbMaximizedFocus)


  • Hey Gavin,

    I added the large item limit functionality, new version is 1.0. Grab it while its still hot.


  • Another tab I would love.. domain add/verify. Usually not a problem, but have recently had 150+ domains project and I made an XLS to build all the cmdlets. Im trying to reverse engineer the XLS marco's/script building you did here, but might be easier for you to add it :)

  • Michael, you're a gent and a scholar. Right in time for my next department's migration too :)
    Thanks heaps :)

  • thanks for sharing.

  • This is fantastic!...bless you :-)

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment