Migrate Distribution Groups from Exchange On-Premise to Exchange Online

Admins who are about to move their organization’s infrastructure to the cloud may want to migrate distribution groups from Exchange on-premise to Exchange Online.

This process is not as simple as the regular Exchange to Office 365 transition for a very simple reason lack of native methods. So, we have to deploy custom scripts.

As many admins may not be familiar with the said approach we have prepared this writeup which explains each and every detail of the manual PowerShell scripting method. Moreover, to fast-track the transition we also provide a professional solution. First, let us start with the preparatory steps.

Preparations Before You Migrate Distribution Groups from Exchange On-Premise to Exchange Online via PowerShell

Think of this as a checklist that will help you determine the progress status. As the method i quite complex building a pre-migration checklist is a must. We combine the preparation and planning in a single unit for easy understanding.

As End of Life announcement for both Exchange 2016 and 2019 versions has been made it now becomes even more important to move dl’s from the on-premise to online systems.

The entire operation must be conducted in a hybrid environment so that a direct communication channel exists between the two endpoints

For that to happen download and install the Microsoft Entra Connect app on your Windows Server hosting the On-Premise Exchange

Every other workload i.e. users, calendars, and contacts should already be on the cloud before you start the distribution group migration. Otherwise, the distribution groups won’t be able to populate the users correctly and migration will end up in failure.

This goes without saying but still, double-check that you are using the Global Admin for On-Premise and Exchange Admin roles in Microsoft 365. You don’t want any RBAC restrictions during the migration.

Have a copy of the entire distribution group structure with all the nested subfolders and other details(group owners, group types, etc) in a backup CSV or equivalent format. This serves as a reference point to ensure all settings and member allocation are happening correctly.

All stakeholders especially the users must be aware of the migration and should be made ready for the potential downtime. Communication is key for avoiding unnecessary disruptions during the migration.

Set up a test lab with synthetic user IDs to see if the plans are valid or if some changes are required. Only when all test cases pass should you conduct a full migration.

Steps to Use PowerShell Commands And Migrate On Premise Distribution Groups to Office 365

Step 1. Export On-Premises Distribution Groups

The following PowerShell command is a sample script that can export all existing distribution lists from an on-premise Exchange Server. It will scan and pull out the property details of all different types of distribution lists including static, dynamic, and mail-enabled security groups, and generate a CSV file format.

# Export-DGs.ps1
$Csvfile = "C:\temp\DGs.csv"
$Groups = Get-DistributionGroup -ResultSize Unlimited
$Report = [System.Collections.Generic.List[Object]]::new()
foreach ($Group in $Groups) {
    $GroupDN = $Group.DistinguishedName
    $ReportLine = [PSCustomObject]@{
        DisplayName                            = $Group.DisplayName
        PrimarySmtpAddress                     = $Group.PrimarySmtpAddress
        EmailAddresses                         = ($Group.EmailAddresses -join ',')
        Members                                = (Get-DistributionGroupMember $GroupDN -ResultSize Unlimited).PrimarySmtpAddress -join ','
        ManagedBy                              = ($Group.ManagedBy -join ',')
        HiddenFromAddressListsEnabled          = $Group.HiddenFromAddressListsEnabled
        ModerationEnabled                      = $Group.ModerationEnabled
        SendModerationNotifications            = $Group.SendModerationNotifications
        GrantSendOnBehalfTo                    = ($Group.GrantSendOnBehalfTo -join ',')
        RecipientTypeDetails                   = $Group.RecipientTypeDetails
        DynamicFilter                          = if ($Group.RecipientTypeDetails -eq "DynamicDistributionGroup") { (Get-DynamicDistributionGroup $GroupDN).RecipientFilter } else { $null }
    }
    $Report.Add($ReportLine)
}
$Report | Export-CSV -Path $Csvfile -NoTypeInformation -Encoding UTF8

Step 2: Prepare the CSV File and Validate it

The raw CSV file obtained from the last script cannot be used directly for migration purposes. So admin needs to open and edit the CSV via a spreadsheet program like Excel. This is a mandatory process done in order to make sure that all the fields are populated correctly.

See if the columns for ManagedBy users and corresponding members exist in Microsoft 365.

If you have dynamic groups, check the accuracy of DynamicFilter and its compatibility with the Exchange Online environment.

Once done Save the newly formed CSV.

Step 3: Before you migrate on prem distribution group to Office 365 create it in Microsoft 365

Use the following PowerShell script to create DGs in Microsoft 365.

# Import-DGs.ps1
$Csvfile = "C:\temp\DGs.csv"
$GroupsData = Import-Csv -Path $Csvfile
Connect-ExchangeOnline
foreach ($GroupData in $GroupsData) {
    if ($GroupData.RecipientTypeDetails -eq "DynamicDistributionGroup") {
        New-DynamicDistributionGroup -Name $GroupData.DisplayName -PrimarySmtpAddress $GroupData.PrimarySmtpAddress -RecipientFilter $GroupData.DynamicFilter
    } else {
        New-DistributionGroup -Name $GroupData.DisplayName -PrimarySmtpAddress $GroupData.PrimarySmtpAddress -Type ($GroupData.RecipientTypeDetails -eq "MailUniversalSecurityGroup" ? "Security" : "Distribution")
    }
}

Step 4: Add Members and Permissions Data

Add members and configure permissions (e.g., ManagedBy, Send As, Send on Behalf) using PowerShell.

# Add-MembersDGs.ps1
$Csvfile = "C:\temp\DGs.csv"
$GroupsData = Import-Csv -Path $Csvfile
foreach ($GroupData in $GroupsData) {
    $Group = Get-DistributionGroup -Identity $GroupData.PrimarySmtpAddress
    if ($GroupData.Members) {
        $Members = $GroupData.Members -split ','
        foreach ($Member in $Members) {
            Add-DistributionGroupMember -Identity $Group.PrimarySmtpAddress -Member $Member
        }
    }
    if ($GroupData.ManagedBy) {
        Set-DistributionGroup -Identity $Group.PrimarySmtpAddress -ManagedBy ($GroupData.ManagedBy -split ',')
    }
}

Step 5: Migrate Advanced Settings (Optional)

Migrate advanced settings like moderation, MailTips, and email addresses.

# Migrate-AdvancedSettings.ps1
$Csvfile = "C:\temp\DGs.csv"
$GroupsData = Import-Csv -Path $Csvfile
foreach ($GroupData in $GroupsData) {
    $Group = Get-DistributionGroup -Identity $GroupData.PrimarySmtpAddress
    Set-DistributionGroup -Identity $Group.PrimarySmtpAddress `
        -HiddenFromAddressListsEnabled $GroupData.HiddenFromAddressListsEnabled `
        -ModerationEnabled $GroupData.ModerationEnabled `
        -SendModerationNotifications $GroupData.SendModerationNotifications `
        -EmailAddresses @{Add=($GroupData.EmailAddresses -split ',')}
}

Step 6: Unsync On-Premises Distribution Groups

Use Entra ID Connect service to de-sync the OU hosting the on-premises DGs.

Then force delta sync to remove unsynced DGs from their corresponding Entra ID values.

Start-ADSyncSyncCycle -PolicyType Delta

Step 7: Finalize and Test Distribution Groups

• Validate DGs functionality in Exchange Online.
• Perform tests on mail flow, moderation, and permissions.
• Communicate changes to users so they can resume business operations.

Why the PowerShell Method is Not Prefered to Migrate Distribution Groups from Exchange On-Premise to Exchange Online

The lack of a contingency plan is a staple of PowerShell-based methods like this one. So it is not a surprise that admins have to make a separate plan for the worst-case scenario.

If the migration fails for some reason or is not as per expectations admins have to manually delete all faulty distribution lists from the cloud.

Moreover, they have to figure out exactly what is wrong with the script, change all the parts of the script responsible for the issue, and re-do the entire operation.

And may have to reduce mailbox size in Outlook 365 before the second attempt.

This entire process is highly labor-intensive and time-consuming, not to mention the high technical knowledge barrier making it out of reach for many.

PowerShell scripts are not the only thing admins have to edit in this migration. The raw CSV they get from the on-premise systems lacks many details which the cloud requires.

So admins have to fill out all the details manually. If you have a small number of DL then it won’t take much time.

However, there is hardly any organization where the number of distribution lists stays in the single digits. Adding yet another delaying factor.

Alternative Solution to Migrate Distribution List to Exchange Online

Many admins complain about the sheer effort required to get a script working and rightly so.

If you want to stop your struggle with the scripts then use the SysTools Exchange to Office 365 Migrator.

Download Now Purchase Now

It offers the following key features absent from the PowerShell variant such as:

Supports both User and Group Mapping for Simultaneous Migration:

The tool provides multiple options to perform user mapping and gives a sample Template file for custom group mapping.

Migrate On Prem DL to Office 365 Easily with A Simplified Interface:

The tool completely eliminates all the technical complexities associated with PowerShell by providing a GUI-based system. Moreover, you can view the object count and data volume in real-time.

Multiple Error Handling Options:

The tool gives you a list of Post Migration options to choose from that includes retry failed, redo migration, and delta migration features.

Receive a Comprehensive Set of Reports:

The tool generates both summarized and detailed accounts of the migration in the form of CSV reports.

So choose this professional solution to save time, reduce manual errors, and ensure a hassle-free migration process. Next up we explain in brief how you can use the tool.

Step-by-Step Process to Use the Tool

• Step 1. Download, Install, Launch, Activate, and select the source and target endpoints as Exchange and Microsoft respectively.
• Step 2. Perform validation process for source Exchange Server.
• Step 3. Likewise do a destination-side validation.
• Step 4. Map users via any one of the available options like Fetch, Import, or Download.
• Step 5. Use the Preview Section to add Group Mapping and Migrate.

Conclusion

This write-up thoroughly explained all the options to migrate distribution groups from Exchange On-Premise to Exchange Online. We gave the preparation procedure as well as the scripts that can perform the construction. Due to the numerous limitations of the scripts we also give access to a professional tool that can perform the task with minimum disruptions

Frequently Asked Questions

• Q. Is it possible to migrate distribution groups from a very old version of Exchange (e.g., Exchange 2003, 2007)?
  A. Direct online migration may not be possible either with PowerShell or the tool. So consider a staged migration instead by upgrading to a supported version (e.g., Exchange 2013, 2016, or 2019) first before attempting the actual DL migration to Exchange Online.
• Q. What options do I have to monitor the progress of the migration with the PowerShell method?
  A. You can add custom print statement’s inside the script itself to see the progress in the PowerShell console.
  PowerShell itself has a robust error report system that tells you what when wrong during the execution of a script.
  Connect to the Exchange Online environment and use Get-DistributionGroup and Get-DistributionGroupMember to see if the DL and its underlying members are present or not.
• Q. Are there any differences in the size limits for distribution groups in Exchange Online to those that are kept on-premise?
  Although, some structural differences are there it only becomes apparent when the number of DL, or underling membership count becomes close to the prescribed limit. Which won’t happen in most practical scenarios.