Migrate distribution lists to Office 365 Groups - Admin help

This article explains how to migrate distribution lists (sometimes referred to as distribution groups) to Office 365 groups. If you want your organization's distribution lists to get all the features and functionality of Office 365 groups, you can now migrate your distribution lists. There are a couple of ways you can migrate your distribution lists to Office 365. You can migrate them using the Exchange admin center (EAC) in Exchange Online or by using Exchange Online PowerShell. Check out Learn about Office 365 groups for more info about Office 365 groups.

Migrate a distribution list to an Office 365 group using EAC

This section explains how to migrate distribution lists using the Exchange admin center (EAC) in Exchange Online.

  1. In the EAC, go to Recipients  > Groups.

  2. Select a distribution group from the groups page.

    Select a distribution group from the groups page
  3. Choose the upgrade icon.

    Click or tap the Upgrade to Office 365 groups icon
  4. On the information dialog, choose Yes to confirm the upgrade.

    If the distribution group is eligible to be migrated, then the distribution list will be converted to an Office 365 group. See the table below for distribution list eligibility for migration.

    If the distribution list isn't eligible a dialog appears with the information that the group can't be migrated.

    If the distribution list is eligible, but there's a failure during migration, the distribution list won't be changed.

Distribution list eligibility for migration

The following table lists which distribution lists are eligible or not eligible for migration

Property

Eligibility

On-premise managed distribution list.

Not eligible

Nested distribution lists. Distribution list either has child groups or is a member of another group.

Not eligible

Moderated distribution list

Not eligible

Distribution lists with send on behalf settings

Not eligible

Distribution lists hidden from address lists

Not eligible

Distribution lists with member RecipientTypeDetails other than UserMailbox, SharedMailbox, TeamMailbox, MailUser

Not eligible

Distribution lists with member join or depart restriction as Closed

Eligible. Converted to a private Office 365 Group.

Distribution lists with custom delivery status notifications. ReportToManager = true, ReportToOriginator = false ReportToManager = false, ReportToOriginator = false

Eligible. Office 365 groups don't understand these properties, and delivery status notifications are always sent to the person that sent the email.

Migrate several distribution lists to Office 365 using PowerShell scripts

This section explains how to use scripts to migrate multiple distribution lists, but before you can run the PowerShell scripts, you'll need to download some files that'll check if your distribution lists are eligible to be migrated and then help you with the migration.

Note: You can also migrate a single distribution list to an Office 365 group using the New-UnifiedGroup PowerShell cmdlet.

  • Download the script files at the Microsoft download center. You'll also need to make sure that you're using PowerShell 3.0.

  • Run the $env:PSModulePath.Split(";")[0] command in PowerShell to output a directory path. Copy the module DlMigrationModule.psm1 and strings file DlMigration.strings.psd1 to the directory location.

Info about the migration scripts

  • Get-DlEligibilityList.ps1 - this script goes through all the distribution lists in your organization, outputs a detailed eligibility file (DlEligibilityList.txt) and lists which distribution lists are eligible or not eligible for migration. The file will contain the following info about the distribution lists: ExternalDirectoryObjectId, PrimarySmtpAddress, Alias, Name, Display Name, Eligibility, Reasons, Member Count, MemberSmtpList, OwnersDistinguishedName

  • Convert-DistributionGroupToUnifiedGroup.ps1 - this script performs the conversion and migration of the distribution lists selected in the DlEligibilityList.txt file, and writes the result to the MigrationOutput.txt file.

    The MigrationOutput.txt file will also contain the following info about the distribution lists: DL-ExternalDirectoryObjectId, DL-PrimarySmtpAddress, UG-ExternalDirectoryObjectId, UG-PrimarySmtpAddress, MigrationStatus, Error Message

  • DlMigrationModule.psm1 - This module has the logic for eligibility and migration which are used by the Get-EligibilityList and Convert-DistributionGroupToUnifiedGroup scripts.

  • DlMigration.strings.psd1 - localized messages shown by the migration script, based on your browser language settings.

Who can run the scripts?

All admins who have permissions to run the New-UnifiedGroup cmdlet can run the script.

Which distribution lists are eligible for migration?

You can only migrate cloud-managed, simple, non-nested distribution lists. The Get-DlEligibilityList.ps1 script goes through all the distribution lists in your organization and outputs an eligibility file which lists eligible distribution lists. You can use the member and owner details to send out migration notifications or determine the time taken for migration.

The table below lists which distribution lists are eligible or not eligible for migration.

Property

Eligibility

On-premise managed distribution list.

Not eligible

Nested distribution lists. Distribution list either has child groups or is a member of another group.

Not eligible

Moderated distribution lists

Not eligible

Distribution lists with send on behalf settings

Not eligible

Distribution lists hidden from address lists

Not eligible

Distribution lists with member RecipientTypeDetails other than UserMailbox, SharedMailbox, TeamMailbox, MailUser

Not eligible

Distribution lists with member join or depart restriction as Closed

Information

Will be converted to a private group.

Distribution lists with custom delivery status notifications.

ReportToManager = true, ReportToOriginator = false

ReportToManager = false, ReportToOriginator = false

Information

Groups doesn't understand these properties, and delivery status notifications are always sent to the person that sent the email.

Distribution lists with Sender restrictions

Eligible. The sender restriction doesn’t get transferred after the distribution list is migrated to a group. You can reset the sender restrictions on the group, after migration, using, Set-UnifiedGroup.

Here are the definitions of eligibility in the script.

  • Eligible - The distribution list can be migrated to Office 365 with all the functionality of an Office 365 group.

  • Information - The distribution list can be migrated to an Office 365 group, but we want to provide some additional details regarding the functionality of the group.

  • Warning - The distribution list can be migrated to an Office 365 group with most of the functionality. A few non critical things might not work. You can choose to migrate distribution lists by using a parameter in the scripts.

  • NotEligible – These distribution lists can't be migrated to an Office 365 group.

Batching

You’ll have an option to specify the batch size as an input. For example, if the batch size is specified as 100, then after processing every 100 * n [Number of connections] distribution lists, the processed and succeeded counts will be shown in the PowerShell console. For the Convert-DistributionGroupToUnifiedGroup.ps1 script, after every batch you’ll be prompted to confirm if you want to continue.

Note: Batch size should be chosen based on the approximate estimated time to run each batch, so you can stop the script if you wish. If you hit Ctrl-C or close when running the Convert-DistributionGroupToUnifiedGroup.ps1 script, you won’t know the status of the current distribution list being migrated. For example, if 10 distribution lists are being migrated in a batch and you hit Ctrl + C while the 7th distribution list was being migrated, status will be available for the first 6 distribution lists. The 7th distribution list status will be missing.

Steps to migrate distribution lists to Office 365 Groups

If you plan to span the migration over several days, make sure you download the latest scripts before you start the migration.

  1. Connect to Exchange PowerShell

  2. Run the Get-DlEligibilityList.ps1 script. The results will be saved to DlEligibilityList.txt file in the working directory.

    Get-DlEligibilityList.ps1 –WorkingDir “C:\Users\Administrator\Desktop\Migration” 
    
  3. You can make a copies of the DlEligibilityList.txt file, remove the rows you don't want to migrate, and use this DlEligibilityList.txt file in the next step. Don't change the format of the .txt file

  4. Run the Convert-DistributionGroupToUnifiedGroup.ps1 script. The results will be saved to MigrationOutput.txt in the working directory.

    Convert-DistributionGroupToUnifiedGroup.ps1 -WorkingDir “C:\Users\Administrator\Desktop\Migration” –DlEligibilityListPath “C:\Users\Administrator\Desktop\Migration\DlEligibilityList.txt”
  5. Check the MigrationOutput.txt file to verify your migrations worked.

  6. Verify that your new Office 365 groups have been created in your organization by checking the Office 365 admin center or the Office 365 admin center preview.

    Get to Office 365 groups See your new Office 365 groups in the admin center preview

    The distribution lists Smtp Address and Alias will be renamed and the distribution list will be hidden from address lists.

Check my migration status

  • MigrationOutput.txt - this file tells you the status of your migrations. These are the statuses you'll see in the file:

    • Success – migration completed successfully.

    • Failure – migration failed and the error message column gives the details.

    • NotEligible – distribution list does not satisfy the eligibility criteria.

    • SuccessActionRequired – distribution list was migrated with all the members and properties but there is some issue in reusing SMTP or deleting the distribution list. The error message will have the appropriate Info needed for taking the action.

    • FailureActionRequired - Migration failed. There is some action needed on the Admin as a cleanup of unused groups.

    • UnknownError – Look at error message column for more details.

Frequently asked questions

What does the status ‘Running’ mean in the MigrationOutput.txt file?

  • It means this distribution list was picked up for migration but we don't have the final status available. This happens when you hit Ctrl+C or try to stop the script in progress, or when the session is disconnected because of network or system issues.

    In this case, if –DeleteDlAfterMigration wasn't set to true, you can check the status of the distribution list by doing a Get-DistributionGroup using the distribution lists ExternalDirectoryObjectId (present in MigrationOutput.txt). If the distribution list was migrated, the SMTP of the distribution list will have the GUID of the Office 365 group. Get-UnifiedGroup <GUID> returns the group details. Check if the SMTP address on the group is as expected.

    If the –DeleteDlAfterMigration parameter was set to true, you can check the status of the distribution list by a doing Get-DistributionGroup using the distribution lists ExternalDirectoryObjectId. If there are no results, it means the distribution list was migrated successfully. If the distribution list still exists and the SMTP address isn't changed, then group creation failed. If distribution list exists with renamed SMTP containing the GUID, run Get-UnifiedGroup <GUID> to look at the group details. Also verify the SMTP address of the distribution list and the Office 365 group.

How can I delete a group created in Azure AD in case of FailureActionRequired?

  • Run Remove-MsolGroup cmdlet in Azure Active Directory by passing the Office group Id present in the error message.

    Remove-MsolGroup –ObjectId GUID

    Check out Azure Active Directory cmdlets.

How do I list all the distribution lists in my organization that are already migrated but not deleted?

  • $migratedDls = Get-DistributionGroup -Filter { Alias -Like 'MigratedDl-*' } | ForEach-Object { $guid = $_.Alias.Replace("MigratedDl-",""); $group = Get-UnifiedGroup $guid; if($group -ne $null) { Echo $_ } }

What should I do in case the SMTP address isn't reused or the SMTP address isn't unique?

  • Identify the recipient which is using the same SMTP address using the Get-Recipient <SMTP> or Get-UnifiedGroup cmdlets. Make a call on which object should have this SMTP either distribution list / Group / Recipient. Update the addresses on these objects using –EmailAddresses parameter on Set-UnifiedGroup or Set-DistributionGroup.

What should I do if the system is shutdown or I closed PowerShell accidentally?

  • If the system shut down while you were running the Get-DlEligibilityList.ps1, rerun the script using -ContinueFromPrevious switch.

    If the system shutdown while you were running the Convert-DistributionGroupToUnifiedGroup.ps1 script, rerun the Convert-DistributionGroupToUnifiedGroup.ps1 script. You don't need to rerun the Get-DlEligibilityList.ps1 script. Take a look at the latest archive of the MigrationOutput.txt file and check the state of distribution lists with "Running" status.

Can I pipe the output from the DlEligibilityList.txt file to the Convert-DistributionGroupToUnifiedGroup.ps1 script?

  • You can pipe the output from DlEligibilityList.txt file to the Convert-DistributionGroupToUnifiedGroup.ps1 script. In this case, all eligible distribution lists and their data will be migrated. Non-eligible distribution lists will not be migrated. If there's non-eligible distribution lists in the DlEligibilityList.txt file, it takes longer to run the script since it'll check eligibility again.

How long does the script run and are there any limits?

  • For a single connection, Get-DlEligibilityList.ps1 takes about 25 minutes to check the eligibility of about 300 distribution lists. The time it takes to run the Convert-DistributionGroupToUnifiedGroup.ps1 depends on the number of members in the distribution lists to be migrated. It takes a about 1 minute for every 250 members. You can set -NoOfConnections parameter to 2 or 3 to make the script faster.

    If the number of distribution lists in your organization is more than 5000, or if the eligibility script seems to be stuck, and there’s no output on the PowerShell console for hours, split the distribution lists covered by the Get-DlEligibilityList.ps1 script by using the -CustomFilterOnAlias parameter, and run the migration steps on each set separately. For example, if the -CustomFilterOnAlias @("a*","b*") is passed as input, then the eligibility script only looks at the distribution lists whose alias starts with a or b.

Why is the contact card still showing a distribution list or what should I do to prevent a migrated distribution list from showing up in my auto suggest list?

  • For Outlook

    • When someone tries to send an email in Outlook by typing the Office 365 group name after migration, the recipient will be resolved as the distribution list instead of the Office 365 group. The contact card of the recipient will be the distribution lists contact card. This is because of the recipient cache or nick name cache in Outlook. The email will be sent successfully to the Office 365 group, but might cause confusion to the sender.

      You can perform the steps in this topic, Information about the Outlook AutoComplete list to reset the cache, which will fix this issue.

  • For Outlook on the web

Do new group members get a welcome email in their inbox?

  • No. The setting to enable welcome messages is set to false by default. This setting affects both existing and new group members who may join after the migration is complete. If the group owner later allows guest users, guest users won't receive a welcome email in their inbox. Guest members can continue working with the group.

Additional information

The following is a list of common parameters used and their definitions.

  • ConvertClosedDlToPrivateGroup - By default a closed distribution list will be converted to a private group. If you don't want to convert the closed distribution list to a private group, set the ConvertClosedDlToPrivateGroup parameter to $false.

  • DeleteDlAfterMigration - If this parameter is set to $true while running the Convert-DistributionGroupToUnifiedGroup.ps1, the distribution list will be deleted if the migration is successful.

  • NoOfConnections - Number of parallel connections that can be used for migration. Range 1-3. Default is 1. If we choose to use 3 then you will not be able to open any new Exchange powershell sessions till the scripts complete.

  • Credential - Admin Login credentials for opening new sessions in case NoOfConnections is specified.

  • WorkingDir - The path where logs and output files of the script will be stored. Default: Current working directory.

  • ContinueFromPrevious - When this parameter is set to true, the script tries to look at the output files of the previous run in the working directory and continue from the point where it was stopped. For this to work, the WorkingDir passed should be same as the run from which the admin wants to continue. Exchange doesn't store any status about the previous run, it's stored in the files in the WorkingDir. This parameter is only available in the Get-DlEligibilityList.ps1 script.

  • Every time the Convert-DistributionGroupToUnifiedGroup.ps1 script is run, any MigrationOutput.txt files from previous migration runs will be archived as MigrationOutput_yyyyMMddHHmmss.txt and a new output file will be created. If you want to use the same input file over multiple runs, remove those rows which were completed and then rerun. The script doesn't remember the previous output so it will attempt to migrate the processed distribution lists again and may lead to an extra time overhead. The output will say distribution list is invalid if the distribution list was already migrated, otherwise, it’ll retry.

Share Facebook Facebook Twitter Twitter Email Email

Was this information helpful?

Great! Any other feedback?

How can we improve it?

Thank you for your feedback!

×