Using PowerShell to convert Exchange Distribution Groups to Office 365 Groups

At last week’s Microsoft Ignite conference, I had the chance of attending a session called “Evolving distribution lists with Office 365 Groups” (a recording of the session is available online). The session described the integration with Outlook 2016 (no plans exist to back port the technology to Outlook 2013) and then went on to investigate how Microsoft views Office 365 Groups as a better alternative to old-style distribution groups. There’s no denying this fact. Distribution groups have been around since the dawn of email and haven’t evolved too much since. The last time Microsoft did anything to improve matters was the introduction of dynamic distribution lists in Exchange 2003.

Of course, the big issue with Office 365 Groups is that they will only ever live in the cloud. Microsoft is not going to incorporate them into the on-premises version of Exchange. You’ll be able to synchronize Office 365 Groups with on-premises Exchange via AADConnect if you operate a hybrid environment, but you won’t be able to create these groups on-premises.

One reason why this is so is the position that Office 365 Groups are moving to occupy within the Office 365 ecosystem as a single entity that permits access to many different forms of data available within the service. Today, membership of an Office 365 Group allows a user to access a shared mailbox, shared calendar, shared OneNote notebook, and a document library. The signs are that more resources will be accessible in the future, all granted through group membership.

Anyway, if you want more information about Office 365 Groups, you can read it in chapter 7 of “Office 365 for Exchange Professionals”. (also available on Kindle).

Speaking of which, keeping the content of an eBook about Office 365 requires you to pay a lot of attention to what Microsoft is saying to customers at conferences such as Ignite. You never know when a speaker provides some information that should be included in the book or requires a change to the book’s content. In this case, I was interested in how Alfons Staerk approached the topic of migration from old-style distribution groups to Office 365 Groups.

It looks very much as if customers will be left to their own devices to migrate distribution groups as they wish. Of course, distribution groups bring their own complexities to the table. How should you deal with nested groups, for instance. What do you do with groups that include mail-enabled public folders, mail contacts, and shared mailboxes in their membership as none of these objects are supported in Office 365 Groups. And, of course, Office 365 Groups use their own mechanism to access resources across different parts of the service, so what do you do with mail-enabled universal security groups?

Microsoft demonstrated a program called “Hummingbird” that can migrate a distribution group to an Office 365 group, subject to the caveats expressed above. Apparently the source code of the program will also be available to allow you to do your own thing.

But the approach taken to migrate a distribution group with a PowerShell script was more interesting. Up to recently, the PowerShell support for Office 365 Groups was just plain bad. You couldn’t create a new group or update group membership, both of which seem like fundamental operations. Microsoft is currently rolling out a new set of cmdlets to Office 365 tenants that address the problem. These are the *-UnifiedGroup cmdlet set to maintain group objects and the *–UnifiedGroupLinks cmdlet set to maintain group membership.

The script shown by Alfons was rudimentary but effective, but only for very simple distribution groups whose membership is solely composed of mailboxes. Everyone loves a challenge, and I decided that it would be a good thing to learn more about how to use the new cmdlets to work with Office 365 Groups, so I set about working on the ConvertDLtoO365Group.ps1 PowerShell script. After all, we need to bring out a second edition of “Office 365 for Exchange Professionals” (probably in September) that should cover this topic.

I’m no programmer. At least, I haven’t been for many years. My COBOL and VAX BASIC skills are rusty now but, as Jeffrey Snover keeps on reminding me, the joy of PowerShell is its ability to put things together bit by bit until something really good is done. PowerShell is like Lego bricks in that respect.

I hacked my way through several versions of the script. The current version is available in the TechNet gallery for anyone to download (and hopefully improve). The script runs in the context of a PowerShell session that is already connected to Exchange Online and does the following:

  • Takes the alias or name of a distribution group as the input parameter.
  • Performs some initial checks to see whether the distribution group exists or an Office 365 Group with the same alias exists. And that it’s an object of type MailUniversalDistributionGroup, which is the only type we can convert.
  • Checks the members of the input group to strip out those that can’t be added to the target Office 365 Group.
  • Checks whether the input group has member join restrictions. If it has (the group is “Closed” or “ApprovalRequired”), the admin is prompted to decide whether they want to create a private Office 365 Group. You can’t currently change the group type, so this is an important decision.
  • Tells the admin what’s happening and asks to proceed.
  • The new Office 365 Group is created with the New-UnifiedGroup It uses the same alias as the input distribution group because a new alias is given to that group.
  • As many of the properties of the input distribution group as possible are moved to the new Office 365 Group (not all can be because there isn’t a direct 1-to-1 mapping between the two object types). The Set-UnifiedGroup cmdlet is used for this purpose.
  • In particular, the Office 365 Group is set to auto-subscribe new members so that it mimics the distribution of new content via email as members expect from a distribution group.
  • The membership is added to the new Office 365 Group using the Add-UnifiedGroupLinks
  • Group members can be in three sets of links (owners, members, and subscribers). Because the new Office 365 Group is intended to behave like an email distribution group, the members are added to the members and subscribers sets.
  • The owners/managers of the input distribution group are added as owners of the Office 365 Group.
  • The email address of the input distribution group is switched to the new Office 365 Group so that new traffic goes there.
Converting an Exchange Distribution Group with ConvertDLtoO365Group.ps1

Converting an Exchange Distribution Group with ConvertDLtoO365Group.ps1

Phew! That’s a lot of processing. There are some known issues. For example, the –AccessType parameter for the New-UnifiedGroup cmdlet doesn’t work at present, so only public groups can be created. This is a known bug and is being fixed by Microsoft. Another issue is that running Add-UnifiedGroupLinks to add mailboxes as subscribers doesn’t work. This bug is also known and a fix will be available shortly.

However, the point is that it’s a PowerShell script and because it’s a script the code is there and available for all to see – and hopefully improve.

Thanks to Alfons Staerk and Sam Koppes of Microsoft for their encouragement. I think they quite liked seeing the demo script shown by Alfons take on a life of its own…


Follow Tony @12Knocksinna


About Tony Redmond

Lead author for the Office 365 for IT Pros eBook and writer about all aspects of the Office 365 ecosystem.
This entry was posted in Cloud, Exchange, Office 365 and tagged , , , , , , , . Bookmark the permalink.

4 Responses to Using PowerShell to convert Exchange Distribution Groups to Office 365 Groups

  1. Pingback: Office 365 Groups : Tips to Understand them better

  2. Jamie says:

    Hi Tony~
    Not sure if you are still monitoring this but in the link to your script under the Q/A section I had a question. You said this on the last question “You could extract the Set-Distribution group commands from the script and execute them in a PowerShell session that is connected to an on-prem Exchange server “. I am very new to power shell can you tell me what you mean by that and or what that would look like? Thanks!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.