DistributionGroupMigration

Migrate Exchange On-premise distribution groups to Exchange Online (Office 365).

Azure Pipelines (master)	PS Gallery	License

Have you seen the following message:

The action 'Set-DistributionGroup','<property>', can't be performed on the object '<name>' because the object is being synchronized from your on-premises organization. This action should be performed on the object in your on-premises organization.

This is because owners of an on-premises distribution group that's synced to Office 365 can't manage the distribution group in Exchange Online. The module DistributionGroupMigration is designed to help with this by migrating Exchange On-premise distribution groups to Exchange Online (Office 365).

Requirements

• Exchange Hybrid deployment

Installation

If you have the PowerShellGet module installed you can enter the following command:

Install to your personal PowerShell modules folder:

Install-Module-Name DistributionGroupMigration -Scope CurrentUser
Import-Module-Name DistributionGroupMigration

Install for everyone:

Install-Module-Name DistributionGroupMigration
Import-Module-Name DistributionGroupMigration

Documentation

You can learn how to use the functions by reading the documentation:

• Cmdlet Overview

Usage

Recommended to verify in a non-production environment. If that isn't possible, use a non-production distribution group.

The functions Complete-OnPremDSTGroupToCloud, Remove-OnPremDSTGroup and Set-NoAADSyncOnPremDSTGroup will fail if the Initialize-OnPremDSTGroupToCloud haven't been initiated. This is because the Initialize-OnPremDSTGroupToCloud creates PSFClixml files which is used on those three functions.

This is a basic overview on how to migrate a distribution group.

1. View the examples.

Get-Help-Name Initialize-OnPremDSTGroupToCloud-Examples
Get-Help-Name Complete-OnPremDSTGroupToCloud-Examples
Get-Help-Name Remove-OnPremDSTGroup-Examples
Get-Help-Name Set-NoAADSyncOnPremDSTGroup-Examples

2. Run Initialize-OnPremDSTGroupToCloud with the parameters of your choice.
3. Choose whether to run the Remove-OnPremDSTGroup or Set-NoAADSyncOnPremDSTGroup function depending on your needs.
4. Initialize a AAD Connect synchronization using Start-ADSyncSyncCycle or wait for the automatic synchronization to take place.
5. Run Complete-OnPremDSTGroupToCloud to complete the migration.
6. Verify that the distribution group has the correct properties and working, i.e. send a mail message to the distribution group.

If you put it all together:

Initialize-OnPremDSTGroupToCloud-Group 'dstgroup001@contoso.com'-ExchangeServer exchprod01.contoso.comSet-NoAADSyncOnPremDSTGroup-Group 'dstgroup001@contoso.com'-ExchangeServer exchprod01.contoso.com# Remove-OnPremDSTGroup -Group 'dstgroup001@contoso.com' -ExchangeServer exchprod01.contoso.comInvoke-Command-ComputerName "<AADConnectServerName>"-ScriptBlock {Start-ADSyncSyncCycle}
Complete-OnPremDSTGroupToCloud-Group 'dstgroup001@contoso.com'# Optional, remove the group after completion. Force must be used when Complete-OnPremDSTGroupToCloud was ran before Remove-OnPremDSTGroup.Remove-OnPremDSTGroup-Group 'dstgroup001@contoso.com'-ExchangeServer exchprod01.contoso.com-Force

Initialize all synchronized distribution groups:

$DSTs=Get-DistributionGroup-Filter {IsDirSynced -eq$true}
$DSTs.PrimarySmtpAddress|Initialize-OnPremDSTGroupToCloud-ExchangeServer exchprod01.contoso.com-Force

Rollback

If for some reason a rollback is needed all distribution group objects is saved in PSFClixml.

1. The LogPath location provided in Initialize-OnPremDSTGroupToCloud contains all PSFClixml as well as all logs.
2. Retrieve a distribution group that will be used in the rollback.

$DistributionGroupObject=Import-PSFClixml-Path "<Path>"

3. Remove the Exchange Online distribution group created from Initialize-OnPremDSTGroupToCloud and renamed with Complete-OnPremDSTGroupToCloud.

Remove-DistributionGroup-Identity $DistributionGroupObject.CompletedGroup.PrimarySmtpAddress-Confirm

4. Depending on if the Exchange On-premise distribution group was removed using Remove-OnPremDSTGroup or just set not to synchronize Set-NoAADSyncOnPremDSTGroup, reverse that step.

   • Recreate the distribution group:

   $Recreate=$DistributionGroupObject.EXCHNew-EXCHDistributionGroup@Recreate

   • Remove NoSync attribute:

   Set-ADGroup-Identity $DistributionGroupObject.EXCH.DistinguishedName-Clear 'adminDescription'

5. Initialize a AAD Connect synchronization using Start-ADSyncSyncCycle or wait for the automatic synchronization to take place.

Maintainers

• Philip Haglund - @KPHaglund

License

This project is licensed under the MIT.