Migrating Distribution Lists to Office 365 Groups

Office 365 Groups (that’s Groups with a capital “G”) are a newish feature of Office 365 that allow for collaboration across several different cloud applications. Office 365 Groups are the cloud only evolution of Site mailboxes, a technology introduced with Exchange and SharePoint 2013 that gave users a single place to access data stored on both Exchange and SharePoint.

Since those days, Office 365 Groups has grown to include significant functionality. The problem has been that, at least until recently, there was no native migration path to transform your on-premises distribution lists into Office 365 Groups other than manually recreating them. In this post, I’m going to walk you through the process of migrating on-premises distribution lists into Office 365 Groups.

Do I want my distribution lists to be Groups?

This is a reasonable question to start off with because Groups are certainly different than distribution lists, and everyone may not appreciate those changes.

When Microsoft first introduced Groups in late 2014, and talked about them at the first Ignite, Groups were pitched as a way for users to take control of collaboration without those pesky IT departments getting in the way. Microsoft wanted to sell Groups as a feature that belonged to end users, with little or no administrator oversight of Groups being possible.

I was invited to a private session at the first Ignite where Microsoft asked customers about Groups and what functionality changes they wanted to see. The response was overwhelmingly slanted toward requests for better administrator control of Groups. To Microsoft’s credit, they have changed course, and a lot of administrator controls have been added into Office 365 Groups.

Administrative features added recently or coming soon to Groups include: creation policies in Azure AD, data classification policies, usage guidelines to educate end users, ability to update privacy type, multi-domain support and more.

With all these administrative improvements, in addition to an impressive list of user features, Office 365 Groups are a feature that most organizations in Office 365 should be using.

Can I migrate a single distribution list into Office 365?

Yes. The New-UnifiedGroup PowerShell cmdlet can be used to migrate a single distribution list to an Office 365 Group. The distribution group in question must be a universal distribution group.

Of course, the power of the PowerShell pipeline could be put to the task of migrating multiple distribution lists into Office 365 Groups, but that does not work very well most of the time. To solve that problem, Microsoft has released a series of PowerShell scripts to assist with bulk migrations of distribution lists into Office 365 Groups.

Getting started with your distribution list to Group migration

When you’re ready to start migrating your distribution lists into Office 365 Groups, the first thing you’ll need to do is download the scripts Microsoft has created. The distribution list to Group migration scripts are available on the Microsoft Download Center.

That package will download four scripts that run in PowerShell V 3.0 or better. Once those are downloaded, you need to run the following PowerShell command

$env:PSModulePath.Split(";")[0]

That command will show you the path where your workstation is configured to look for PowerShell modules. On my workstation, it’s C:\Users\Nathan\Documents\WindowsPowerShell\Modules, but your mileage may vary. You need to copy DlMigrationModule.psm1 and DlMigration.strings.psd1 to that folder.

The other two scripts are as follows:

• Get-DlEligibilityList.ps1 – This script goes through your on-premises Active Directory and creates a report detailing which distribution lists can and cannot be migrated to Office 365 Groups. The output from running this script is a file called DlEligibilityList.txt that contains the following information about the distribution lists in your environment: ExternalDirectoryObjectId, PrimarySmtpAddress, Alias, Name, Display Name, Eligibility, Reasons, Member Count, MemberSmtpList, OwnersDistinguishedName.
• Convert-DistributionGroupToUnifiedGroup.ps1 – This script does the actual work of converting all eligible distributions lists in your Active Directory to Office 365 Groups in your Office 365 tenant.

On-premises distribution lists with the following properties cannot be migrated to Office 365 Groups

• Managed distribution lists
• Nested distribution lists
• Moderated distribution lists
• Distribution lists with send on behalf settings
• Distribution lists hidden from address lists
• Distribution lists with RecipientTypeDetails other than UserMailbox, SharedMailbox, TeamMailbox, MailUser

On-premises distribution lists with a member join or depart restriction set to Closed will be converted to private Groups with the -ConvertClosedDlToPrivateGroup parameter.

Distribution list to Office 365 Group migration process

Below are the steps you’ll need to follow to perform the migration

1. Connect PowerShell to your Exchange Online tenant
2. Run Get-DlEligibilityList.ps1 script.
3. Modify the DlEligibilityList.txt file in your working directory to remove the rows of any distribution lists you do not want to migrate to Office 365 Groups.
4. Run Convert-DistributionGroupToUnifiedGroup.ps1 script. The results will be saved to a file called MigrationOutput.txt in the working directory.
5. Verify that new Office 365 Groups have been created.

Additional parameters

The following additional parameters can be used with the two scripts.

• ConvertClosedDlToPrivateGroup – this parameter must be set to $true on the Convert script to migrate closed distribution lists to private Office 365 Groups.
• DeleteDlAfterMigration – setting this parameter to $true on the Convert script will delete on-premises distribution lists if the migration is successful.
• NoOfConnections – Default is 1. Can be set to 2 or 3 for the Convert script to open additional connections to Office 365 for parallel migrations.
• Credential – Office 365 admin credentials to open additional sessions in case number of connections is set to 2 or 3.
• WorkingDir – Path where logs and output files are stored.
• ContinueFromPrevious – Setting this parameter to $true will force the Convert script to look for logs and use them to resume the migration from the point where the last attempt stopped.

Wrapping it up

There you have it, everything you need to know to migrate your on-premises distribution lists into Office 365 Groups. Hopefully this will help make your migration into Office 365 a little bit easier.