philiphaglund / distributiongroupmigration

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

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 '[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>"

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.EXCH
   New-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.

distributiongroupmigration's Issues

Mail Enabled Security Groups

How do these scripts work against security groups? we have a few mail-enabled security groups we are looking to migrate however I would like to know how these scripts will work against security groups

Cannot bind argument to parameter 'Path' because it is null

Hello,

Have just tried to run Initialize-OnPremDSTGroupToCloud, but got a following error message:

Initialize-OnPremDSTGroupToCloud : Cannot bind argument to parameter 'Path' because it is null.
At line:1 char:1

• Initialize-OnPremDSTGroupToCloud -Group [email protected] -Exchange ...

•   + CategoryInfo          : InvalidData: (:) [Initialize-OnPremDSTGroupToCloud], ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Initialize-OnPremDSTGroupToCloud
  
  

What could it be? How to solve it?

Initialize-OnPremDSTGroupToCloud Could not find a part of the path

After hours of searching how to migrate DST Groups from on-prem Exchange to O365 that can't be upgraded, I found this module for performing this. I've installed in using Powershell 7 and I keep running into the issue that the command "Could not find a part of the path 'C:\Users<user>\AppData\Local\Temp\tmp_j1epa252.kbf\tmp_j1epa252.kbf.format.ps1xml'. This occurs right after entering Exchange On-Premise credentials and it runs through creating a PSSession

Any ideas? that path doesn't even exist on my machine

get a error when trying to use a csv file increase the value for the ResultSize parameter.

We have a large exchange environment and always need to run exchange commands -results unlimited Which I can do with your
DistributionGroupMigration PowerShell module can you modifiy it. I love your tools but can't use it if I can't have multi DL run in the command we have 1700 DL we need to migrate not all at once only by location as that location email is migrated to O365. Still allot of DL. below is
WARNING: There are more results available than are currently displayed. To view them, increase the value for the ResultSize parameter.
WARNING: [10:12:02][Initialize-OnPremDSTGroupToCloud] Manager does not exist in Exchange Online as a valid recipient. Will not continue with current group

Error occurred, will export current configuration of all distribution groups colle cted and its properties to a PSFClixml object to $path

Error occurred, will export current configuration of all distribution groups colle
cted and its properties to a PSFClixml object to C:\Users\mstraathof\AppData\Roaming\WindowsPowerShell\PSFramework\L
ogs\DLlist

Initialize-OnPremDSTGroupToCloud : |Microsoft.Exchange.Configuration.Tasks.ThrowTerminatingErrorException|The
"AcceptMessagesOnlyFromSendersOrMembers" and "AcceptMessagesOnlyFromDLMembers" parameters can't be specified at
the same time.
At line:1 char:28

• ... tpAddress | Initialize-OnPremDSTGroupToCloud -ExchangeServer exchangeserver..

•             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : NotSpecified: (:) [Set-DistributionGroup], ThrowTerminatingErrorException
  • FullyQualifiedErrorId : [Server=DB8P192MB0757,RequestId=7dd170cd-6d8b-4ac1-19b4-e60dbd3f87d6,TimeStamp=Wed,
    28 Jun 2023 13:57:32 GMT],Initialize-OnPremDSTGroupToCloud

Do you have any idea?

Installation fails

Hi Philip
Great stuff you have built but cannot install it following the instruction. Can you help?

When I run the command I got the following error. It looks like it tries to load modules that are already installed on my PC. How can I remediate it?

Install-Module -Name DistributionGroupMigration -Scope CurrentUser
PackageManagement\Install-Package : The following commands are already available on this system:'Add-AzureADApplicationOwner,Add-AzureADDeviceRegisteredOwner,Add-AzureADDeviceRegisteredUser,
Add-AzureADDirectoryRoleMember,Add-AzureADGroupMember,Add-AzureADGroupOwner,Add-AzureADMSLifecyclePolicyGroup,Add-AzureADServicePrincipalOwner,Confirm-AzureADDomain,Connect-AzureAD,Disconnec
t-AzureAD,Enable-AzureADDirectoryRole,Get-AzureADApplication,Get-AzureADApplicationExtensionProperty,Get-AzureADApplicationKeyCredential,Get-AzureADApplicationLogo,Get-AzureADApplicationOwne
r,Get-AzureADApplicationPasswordCredential,Get-AzureADApplicationProxyApplication,Get-AzureADApplicationProxyApplicationConnectorGroup,Get-AzureADApplicationProxyConnector,Get-AzureADApplica
tionProxyConnectorGroup,Get-AzureADApplicationProxyConnectorGroupMembers,Get-AzureADApplicationProxyConnectorMemberOf,Get-AzureADApplicationServiceEndpoint,Get-AzureADContact,Get-AzureADCont
actDirectReport,Get-AzureADContactManager,Get-AzureADContactMembership,Get-AzureADContactThumbnailPhoto,Get-AzureADContract,Get-AzureADCurrentSessionInfo,Get-AzureADDeletedApplication,Get-Az
ureADDevice,Get-AzureADDeviceConfiguration,Get-AzureADDeviceRegisteredOwner,Get-AzureADDeviceRegisteredUser,Get-AzureADDirectoryRole,Get-AzureADDirectoryRoleMember,Get-AzureADDirectoryRoleTe
mplate,Get-AzureADDomain,Get-AzureADDomainNameReference,Get-AzureADDomainServiceConfigurationRecord,Get-AzureADDomainVerificationDnsRecord,Get-AzureADExtensionProperty,Get-AzureADGroup,Get-A
zureADGroupAppRoleAssignment,Get-AzureADGroupMember,Get-AzureADGroupOwner,Get-AzureADMSDeletedDirectoryObject,Get-AzureADMSDeletedGroup,Get-AzureADMSGroup,Get-AzureADMSGroupLifecyclePolicy,G
et-AzureADMSIdentityProvider,Get-AzureADMSLifecyclePolicyGroup,Get-AzureADOAuth2PermissionGrant,Get-AzureADObjectByObjectId,Get-AzureADServiceAppRoleAssignedTo,Get-AzureADServiceAppRoleAssig
nment,Get-AzureADServicePrincipal,Get-AzureADServicePrincipalCreatedObject,Get-AzureADServicePrincipalKeyCredential,Get-AzureADServicePrincipalMembership,Get-AzureADServicePrincipalOAuth2Per
missionGrant,Get-AzureADServicePrincipalOwnedObject,Get-AzureADServicePrincipalOwner,Get-AzureADServicePrincipalPasswordCredential,Get-AzureADSubscribedSku,Get-AzureADTenantDetail,Get-AzureA
DTrustedCertificateAuthority,Get-AzureADUser,Get-AzureADUserAppRoleAssignment,Get-AzureADUserCreatedObject,Get-AzureADUserDirectReport,Get-AzureADUserExtension,Get-AzureADUserLicenseDetail,G
et-AzureADUserManager,Get-AzureADUserMembership,Get-AzureADUserOAuth2PermissionGrant,Get-AzureADUserOwnedDevice,Get-AzureADUserOwnedObject,Get-AzureADUserRegisteredDevice,Get-AzureADUserThum
bnailPhoto,Get-CrossCloudVerificationCode,New-AzureADApplication,New-AzureADApplicationExtensionProperty,New-AzureADApplicationKeyCredential,New-AzureADApplicationPasswordCredential,New-Azur
eADApplicationProxyApplication,New-AzureADApplicationProxyConnectorGroup,New-AzureADDevice,New-AzureADDomain,New-AzureADGroup,New-AzureADGroupAppRoleAssignment,New-AzureADMSGroup,New-AzureAD
MSGroupLifecyclePolicy,New-AzureADMSIdentityProvider,New-AzureADMSInvitation,New-AzureADServiceAppRoleAssignment,New-AzureADServicePrincipal,New-AzureADServicePrincipalKeyCredential,New-Azur
eADServicePrincipalPasswordCredential,New-AzureADTrustedCertificateAuthority,New-AzureADUser,New-AzureADUserAppRoleAssignment,Remove-AzureADApplication,Remove-AzureADApplicationExtensionProp
erty,Remove-AzureADApplicationKeyCredential,Remove-AzureADApplicationOwner,Remove-AzureADApplicationPasswordCredential,Remove-AzureADApplicationProxyApplication,Remove-AzureADApplicationProx
yApplicationConnectorGroup,Remove-AzureADApplicationProxyConnectorGroup,Remove-AzureADContact,Remove-AzureADContactManager,Remove-AzureADDeletedApplication,Remove-AzureADDevice,Remove-AzureA
DDeviceRegisteredOwner,Remove-AzureADDeviceRegisteredUser,Remove-AzureADDirectoryRoleMember,Remove-AzureADDomain,Remove-AzureADGroup,Remove-AzureADGroupAppRoleAssignment,Remove-AzureADGroupM
ember,Remove-AzureADGroupOwner,Remove-AzureADMSDeletedDirectoryObject,Remove-AzureADMSGroup,Remove-AzureADMSGroupLifecyclePolicy,Remove-AzureADMSIdentityProvider,Remove-AzureADMSLifecyclePol
icyGroup,Remove-AzureADOAuth2PermissionGrant,Remove-AzureADServiceAppRoleAssignment,Remove-AzureADServicePrincipal,Remove-AzureADServicePrincipalKeyCredential,Remove-AzureADServicePrincipalO
wner,Remove-AzureADServicePrincipalPasswordCredential,Remove-AzureADTrustedCertificateAuthority,Remove-AzureADUser,Remove-AzureADUserAppRoleAssignment,Remove-AzureADUserExtension,Remove-Azur
eADUserManager,Reset-AzureADMSLifeCycleGroup,Restore-AzureADDeletedApplication,Restore-AzureADMSDeletedDirectoryObject,Revoke-AzureADSignedInUserAllRefreshToken,Revoke-AzureADUserAllRefreshT
oken,Select-AzureADGroupIdsContactIsMemberOf,Select-AzureADGroupIdsGroupIsMemberOf,Select-AzureADGroupIdsServicePrincipalIsMemberOf,Select-AzureADGroupIdsUserIsMemberOf,Set-AzureADApplicatio
n,Set-AzureADApplicationLogo,Set-AzureADApplicationProxyApplication,Set-AzureADApplicationProxyApplicationConnectorGroup,Set-AzureADApplicationProxyApplicationCustomDomainCertificate,Set-Azu
reADApplicationProxyApplicationSingleSignOn,Set-AzureADApplicationProxyConnector,Set-AzureADApplicationProxyConnectorGroup,Set-AzureADDevice,Set-AzureADDomain,Set-AzureADGroup,Set-AzureADMSG
roup,Set-AzureADMSGroupLifecyclePolicy,Set-AzureADMSIdentityProvider,Set-AzureADServicePrincipal,Set-AzureADTenantDetail,Set-AzureADTrustedCertificateAuthority,Set-AzureADUser,Set-AzureADUse
rExtension,Set-AzureADUserLicense,Set-AzureADUserManager,Set-AzureADUserPassword,Set-AzureADUserThumbnailPhoto,Update-AzureADSignedInUserPassword'. This module 'AzureAD' may override the exi
sting commands. If you still want to install this module 'AzureAD', use -AllowClobber parameter.
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:1809 char:21
+ ...          $null = PackageManagement\Install-Package @PSBoundParameters
+                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (Microsoft.Power....InstallPackage:InstallPackage) [Install-Package], Exception
    + FullyQualifiedErrorId : CommandAlreadyAvailable,Validate-ModuleCommandAlreadyAvailable,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage

wrong output information when validating members of groups in Initialize-OnPremDSTGroupToCloud.ps1 script

Found out that the log output from member validation in Initialize-OnPremDSTGroupToCloud.ps1 script (lines 521-532) gives wrong information.
I have 4 members in my test distribution group. The last one doesn't have a valid e-mail address and cannot be found in Exchange Online.

[DBG]: PS >> $Members

Name        RecipientType
----        -------------
d099        MailUser     
mizi        MailUser     
testdk      MailUser     
D099_1 test User     

[DBG]: PS >> $Members.primarysmtpaddress
[email protected]
[email protected]
[email protected]

The current member is:

[DBG]: PS >> $member
D099_1 test User  

But the warning returns the previous user mail address :-)
[12:03:30][Initialize-OnPremDSTGroupToCloud] Member [email protected] does not exist in Exchange Online as a valid recipient. Will not continue with current group [email protected].

Can it be fixed quickly?

/Michal