As organizations transition to cloud-based solutions, migrating mailboxes to Microsoft 365 (formerly Office 365) is a common task. While the process can be complex, PowerShell provides powerful tools to automate and simplify this migration. In this post, we’ll explore a script that helps you migrate on-premises Exchange mailboxes to Microsoft 365.

The Problem: Manually migrating multiple mailboxes to Microsoft 365 is time-consuming and prone to errors.

The Solution: A PowerShell script that automates the process of creating migration batches and initiating the migration to Microsoft 365.

Here’s the script:

# Import required modules
Import-Module ExchangeOnlineManagement

# Connect to Exchange Online
Connect-ExchangeOnline

# Define variables
$CSVFile = "C:\Scripts\MailboxesToMigrate.csv"
$OnPremisesCredential = Get-Credential -Message "Enter on-premises Exchange admin credentials"
$TargetDeliveryDomain = "contoso.mail.onmicrosoft.com"  # Replace with your Microsoft 365 domain
$EndpointName = "OnPremEndpoint"  # Name for the migration endpoint

# Import list of mailboxes to migrate
$Mailboxes = Import-Csv $CSVFile

# Create a migration endpoint (if it doesn't exist)
if (!(Get-MigrationEndpoint -Identity $EndpointName -ErrorAction SilentlyContinue)) {
    New-MigrationEndpoint -ExchangeRemote -Name $EndpointName -Autodiscover -EmailAddress $OnPremisesCredential.UserName -Credentials $OnPremisesCredential
}

# Create a migration batch for each department
$Departments = $Mailboxes | Select-Object -ExpandProperty Department -Unique

foreach ($Dept in $Departments) {
    $BatchName = "Migrate-$Dept-$(Get-Date -Format 'yyyyMMdd')"
    $DeptMailboxes = $Mailboxes | Where-Object { $_.Department -eq $Dept }

    $MigrationBatch = New-MigrationBatch -Name $BatchName -SourceEndpoint $EndpointName -TargetDeliveryDomain $TargetDeliveryDomain
    
    foreach ($Mailbox in $DeptMailboxes) {
        $MoveRequest = New-MoveRequest -Identity $Mailbox.EmailAddress -Remote -RemoteHostName $TargetDeliveryDomain -TargetDeliveryDomain $TargetDeliveryDomain -RemoteCredential $OnPremisesCredential -BatchName $BatchName
    }

    # Start the migration batch
    Start-MigrationBatch -Identity $BatchName
    
    Write-Host "Migration batch $BatchName created and started for department: $Dept"
}

Write-Host "Migration batches created and started for all departments."

# Disconnect from Exchange Online
Disconnect-ExchangeOnline -Confirm:$false

How it works:

1. The script connects to Exchange Online using the ExchangeOnlineManagement module.
2. It reads a list of mailboxes to migrate from a CSV file.
3. A migration endpoint is created if it doesn’t already exist.
4. The script creates migration batches for each department.
5. For each mailbox in a department, it creates a move request.
6. Each migration batch is then started.

To use this script:

1. Ensure you have the ExchangeOnlineManagement module installed (Install-Module ExchangeOnlineManagement).
2. Prepare a CSV file (MailboxesToMigrate.csv) with columns: EmailAddress, Department.
3. Modify the $CSVFile variable to point to your CSV file.
4. Update the $TargetDeliveryDomain variable with your Microsoft 365 domain.
5. Run the script in PowerShell with appropriate permissions.

Example CSV content:

CopyEmailAddress,Department
john.doe@contoso.com,Sales
jane.smith@contoso.com,Marketing
mike.johnson@contoso.com,IT
sarah.brown@contoso.com,Sales

Important considerations:

1. Permissions: Ensure you have the necessary permissions both in your on-premises Exchange environment and in Microsoft 365 to perform migrations.
2. Network bandwidth: Large-scale migrations can consume significant bandwidth. Plan your migration during off-peak hours if possible.
3. Testing: Always test the migration process with a small batch of mailboxes before proceeding with a full-scale migration.
4. User communication: Inform users about the migration process, potential downtime, and any actions they need to take.
5. Verification: After migration, verify that all mailboxes have been moved successfully and that users can access their data.
6. Cleanup: Once the migration is complete and verified, you may need to decommission the on-premises mailboxes and update DNS records.

Customizing the script:

• You can modify the script to include additional parameters in the New-MoveRequest cmdlet, such as BadItemLimit or LargeItemLimit, to handle problematic items during migration.
• Add error handling and logging to capture any issues that occur during the migration process.
• Implement a progress bar or more detailed status updates for larger migrations.

Post-migration steps: After running this script and completing the migration, you should:

1. Monitor the migration batches using the Get-MigrationBatch cmdlet.
2. Check for any errors or warnings in the migration logs.
3. Verify that all expected content has been migrated for a sample of users.
4. Update user guides or documentation to reflect the new Microsoft 365 environment.
5. Consider implementing additional Microsoft 365 features now that mailboxes are in the cloud.

Migrating mailboxes to Microsoft 365 can be a complex process, but PowerShell scripting can significantly streamline the operation. This script provides a solid foundation for automating your migration, allowing you to move mailboxes efficiently and in an organized manner.

Remember that while this script automates much of the process, it’s crucial to thoroughly plan your migration, prepare your environment, and test thoroughly before executing a large-scale move. Each organization’s needs may vary, so don’t hesitate to adapt this script to your specific requirements.

By leveraging PowerShell for your Microsoft 365 migration, you can ensure a more controlled, efficient, and error-free transition to the cloud. Happy migrating!