Skip to content

Latest commit

 

History

History
108 lines (87 loc) · 6.33 KB

README.md

File metadata and controls

108 lines (87 loc) · 6.33 KB
Raw

DistributionGroupMigration

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

Azure Pipelines (master) PS Gallery License
Build Status PowerShell Gallery License: MIT

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:

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
  1. Run Initialize-OnPremDSTGroupToCloud with the parameters of your choice.
  2. Choose whether to run the Remove-OnPremDSTGroup or Set-NoAADSyncOnPremDSTGroup function depending on your needs.
  3. Initialize a AAD Connect synchronization using Start-ADSyncSyncCycle or wait for the automatic synchronization to take place.
  4. Run Complete-OnPremDSTGroupToCloud to complete the migration.
  5. 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 '[email protected]' -ExchangeServer exchprod01.contoso.com
Set-NoAADSyncOnPremDSTGroup -Group '[email protected]' -ExchangeServer exchprod01.contoso.com
# Remove-OnPremDSTGroup -Group '[email protected]' -ExchangeServer exchprod01.contoso.com
Invoke-Command -ComputerName "<AADConnectServerName>" -ScriptBlock {Start-ADSyncSyncCycle}
Complete-OnPremDSTGroupToCloud -Group '[email protected]'
# Optional, remove the group after completion. Force must be used when Complete-OnPremDSTGroupToCloud was ran before Remove-OnPremDSTGroup.
Remove-OnPremDSTGroup -Group '[email protected]' -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>"
  1. Remove the Exchange Online distribution group created from Initialize-OnPremDSTGroupToCloud and renamed with Complete-OnPremDSTGroupToCloud.
Remove-DistributionGroup -Identity $DistributionGroupObject.CompletedGroup.PrimarySmtpAddress -Confirm

  1. 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.EXCH
New-EXCHDistributionGroup @Recreate
    • Remove NoSync attribute:
    Set-ADGroup -Identity $DistributionGroupObject.EXCH.DistinguishedName -Clear 'adminDescription'

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

Maintainers

License

This project is licensed under the MIT.