Summary: Use Windows PowerShell to upload and start staged migrations.

Note  This is a five-part series that includes the following posts:

• Using Windows PowerShell with Staged Migrations: Part 1
  Use Windows PowerShell to add and verify email domains in Office 365.
• Using Windows PowerShell with Staged Migrations: Part 2
  Use Windows PowerShell to upload and start staged migrations.
• Using Windows PowerShell with Staged Migrations: Part 3
  Use Windows PowerShell to obtain the status and statistics from staged migrations.
• Using Windows PowerShell with Staged Migrations: Part 4
  Use Windows PowerShell to convert mailboxes to mail-enabled users in Office 365.
• Using Windows PowerShell with Staged Migrations: Part 5
  Use Windows PowerShell to license users and correct the login ID for Office 365. 

Honorary Scripting Guy, Sean Kearney, is here to get you up and running with staged migrations in Office 365. There are some prerequisites you’ll need, of course:

• An Active Directory account with full read and write access to mailboxes within Exchange Server.
• An endpoint that is the connection in Office 365 to the on-premise Exchange server.
• Synchronization of data between the on-premise Active Directory and the Office 365 environment.

With these in place, you can perform a staged migration. The staged migration builds content in Office 365 by synchronizing selected user mailboxes via Outlook Anywhere. When the synchronization process is complete, it establishes forwarding email from the on-premise Exchange server to the Office 365 environment.

The actual process of a staged migration is simple:

• Upload a CSV file with the email addresses of users to migrate to Office 365 and start the migration.
• Check for the status of the migration in Office 365, identify any errors, and mitigate them.
• When the migration is complete, convert the on-premise mailboxes to enabled users.
• License the users and, optionally, change their login IDs.

So your first task is to provide a CSV file. The formatting is quite simple. In our example, this file is for three users who are being staged to Office 365:

EmailAddress,Password,ForceChangePassword

zbeeblebrox@contoso.com,,False

fprefect@contoso.com,,False

adent@contoso.com,,False

If you have DirSync with password sync, or ADFS, the last fields stay as displayed. If you had to supply passwords, you would enclose them in the second field. If you’d like the password to change when the user logs in change the False to True.

Following is an example with a provided password that the user must change after the first login to Office 365:

EmailAddress,Password,ForceChangePassword

tmacmillan@contoso.com,PasswordNew1,True

At this point, if you were logged in to Office 365, you would access your Exchange environment and select Mailboxes under Recipients:

After you click Mailboxes, click the Migration tab. From here you can click the plus sign ( + ) and choose Migrate to Exchange Online:

You would then choose the option for a staged migration:

On the next screen, browse to the CSV file you created earlier. As you can see in our example, it has identified that you are going to migrate three mailboxes:

The next few screens that appear allow you to verify the internal name of your Exchange server and the Outlook Anywhere endpoint. Finally, you will be asked if you want to start the staged migration automatically or manually.

As you can see, the process is not actually difficult. There are, however, no scheduling options within the Office 365 interface if you set it up manually.

The good news is that we can use Windows Powershell to reproduce all of this! We can use the Office 365 cmdlets for managing the remote migrations, and we can use the New-MigrationBatch cmdlet.

For a staged migration, we capture the currently available migration endpoint in Office 365 with the Get-Migration endpoint cmdlet:

$MigrationEndpoint=Get-MigrationEndpoint

Then we capture the CSV file in binary format for the cmdlet:

$MigrationBatch=’C:\Migration\HSG-Staging-1.csv’

$CSVData=[System.io.file]::Readallbytes($MigrationBatch)

$Batchname=’StageBatch1’

New-MigrationBatch –name $Batchname –sourcendpoint $MigrationEndpoint.identity –csvdata $CSVData

After the migration batch is created, you can access it by using the Start-MigrationBatch cmdlet:

Start-MigrationBatch –identity ‘StageBatch1’

Or you could write this into a Windows PowerShell script to schedule it. You could (if you had access to an Azure Automation instance) even schedule it and other batches to launch at the times you prefer.

But how do we tell what is the result? How do we know what did or did not happen? How do we know how long it took?

…that is a story for tomorrow.

I invite you to follow The Scripting Guys on Twitter and Facebook. If you have any questions, send an email to The Scripting Guys at scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then remember eat your cmdlets every day with a taste of creativity.

Sean Kearney, Windows PowerShell MVP and Honorary Scripting Guy