Implementing the ability to migrate directly from on-premises distribution lists to Office 365 Unified Groups

When the Distribution List Migration Version 2.0 module was initially released a feature was included that allowed administrators during the migration process to trigger an upgrade to an Office 365 Unified Group. The code leveraged a special command included in Office 365 that took a cloud only distribution list and performed a migration in the background to an Office 365 Unified Group. I often found that the upgrade command would fail an was not always very specific in the nature or reasons for the failure. This is why the module would do a best effort trigger to allow the upgrade to be performed but continue moving on if a failure code was returned.

For information on the upgrade process please see: Upgrade distribution lists to Microsoft 365 Groups in Exchange Online – Microsoft 365 admin | Microsoft Learn

The features outlined in the above post are being deprecated over time. This necessitated taking a new approach to migrating distribution lists from the on-premises environment to Office 365 Unified Groups if the desire was to convert the group type. Version 2.9.6 of the DLConversionV2 powershell module now introduces the ability to migrate directly from an on-premises distribution group to an Office 365 Unified Group without the need to first perform a standard migration and upgrade.

To migrate to an Office 365 Unified Group from an on-premises distribution list the start-Office365GroupMigration command is utilized. This command follows the same structure as the traditional start-distributionListMigration command and supports the same parameters. In addition to the standard parameter set there is an additional parameter -addManagersAsMembers. This switch automatically takes any user in the managedBy or msExchCoManagedBy attribute and adds them as members of the group. It is a requirement that all owners be members of the group in Office 365.

When migrating from an on-premises distribution list to an Office 365 Unified groups there are some additional restrictions that are not found when performing a standard distribution list migration. These restrictions include:

• The group cannot have any rights on itself or other groups that require a security principle. For example, the group may not have full mailbox access rights, send as rights, mailbox folder permissions, or group manager rights on itself or any other object.
• The group must have at least one manager but no more than 100 managers.
• All managers must be members of the group.
• The group may not contain any mail enabled groups or contacts. Only mailbox and mail user objects are supported for membership.
• The group being migrated may not be a room distribution list type.
• The group being migrated may not have any bypassModerationFromSendersOrMembers properties specified on-premises as this attribute is not supported on Office 365 Unified Groups.

The DLConversionV2 module has been modified to perform these additional checks prior to migration and provide the administrator with a list of exceptions found. When the migration is complete the result will be an Office 365 Unified Group that mirrors all the settings of the on-premises distribution list. This will allow users to take advantage of the new features associated with the modern group experience.

Here is a sample command for migrating an on-premsies distribution list to an Office 365 Unified Group:

Start-Office365GroupMigration -groupSMTPAddress address@domain.com -globalCatalogServer dc.domain.com -activeDirectoryCredential $cred -aadConnectServer aadconnect.domain.com -aadConnectCredential $cred -exchangeServer exchange.domain.com -exchangeCredential $cred -exchangeOnlineCredential $cred -azureADCredential $cred -enableHybridMailFlow:$TRUE -dnNoSyncOU “DN” -logFolderPath c:\temp -overrideSecurityGroupCheck:$TRUE

The command also supports certificate authentication as well as pre-collected permissions evaluations using the additional switches present in the module.

If you encounter any issues with this new feature please open an issue on GitHub or contact me at dlconversionV2@service.microsoft.com.