UPDATE: This script has been moved to the PowerShell Gallery.  All future updates will be posted here: https://www.powershellgallery.com/packages/ExportImport-UnifiedGroups/

Use this script to export / import Unified Groups and their settings as part of a tenant-to-tenant migration.

This script supports multiple modes of operation:

- Export (Backup)

- Import (1 stage or 2 stage)

- Set

As well as a method of transformation (address rewrite for importing/exporting).

In 1-stage migrations, the domain name already has been removed from the source environment or is not being migrated (such as in a divestiture).  In 2-stage migrations, the domain name still exists in the source environment.  Since users are referred to by their Primary SMTP Address, if their primary address is still in another tenant, import would fail.  Using either a 2-stage migration or an address rewrite will allow users to be imported after groups (2-stage) or alongside (rewrite).

For additional examples and more information, see the corresponding blog at https://undocumented-features.com/2017/10/22/backup-and-restore-office-365-groups/.


* Previous Updates

2017-10-27     - Fixed typo for Owners.
2017-10-25     - Fixed parameter typos.
                      - Updated import/set processing to check recipients prior to processing
                        and remove users that aren't valid recipients in the tenant.

Export, Import, and update Unfied Groups 
Use this script to backup, restore, export, import, and update Unified Groups, 
primarily when migrating group settings between tenants. 
In a 1-stage migration, you will export unified groups from a source tenant, 
add the domains to the target tenant, and then import the groups with users into  
the target tenant. To do this, you'll use the -Mode Import -IncludeUsers  
parameters when importing into the target tenant. 
In a 2-stage migration, you will export unified groups from a source tenant, 
import the groups to the target tenant, synchronize the data, and then add the 
domains at a later date.  Once the domains are added, you can re-run the script 
with the -Mode Set parameter to import the users. 
.PARAMETER IncludeUsers 
When running an Import, if the domains have been migrated, use this switch to 
import the users as well. 
Valid options are Export, Import, and Set. 
- Export 
  Use when exporting Unified Groups. Converts objects/aliases to fully-qualified 
  SMTP Addresses. 
- Import 
  Use when importing Unified Groups. If domains haven't been moved between 
  source and target during a migration, do nothing.  If domains have been moved, 
  use the "IncludeUsers" switch. 
- Set 
  If performing a 2-stage migration (pre-create groups so content can be staged 
  and then moving domains), run this param after the domains have been migrated 
  to add the users back to the groups. 
.PARAMETER RewriteTargetDomain 
Use this switch to update the target domain address for users.  You can use this 
with any mode (Export, Import, Set) to update the SMTP suffix of the users that  
will be added back to groups.  Useful if you are performing a tenant to tenant 
migration but not keeping the same address space (such as a divestiture). 
.\ExportImportUnifiedGroups.ps1 -Mode Export -File MyUnifiedGroups.csv 
Export unified groups. 
.\ExportImportUnifiedGroups.ps1 -Mode Import -File MyUnifiedGroups.Csv -IncludeUsers 
Import unified groups in a 1-stage migration (imports groups and users together) 
.\ExportImportUnifiedGroups.ps1 -Mode Import -File MyUnifiedGroups.csv 
Import unified groups in a 2-stage migration (import groups first, import users 
later in a second pass). 
.\ExportImportUnifiedGroups.ps1 -Mode Set -File MyUnifiedGroups.csv 
Import users and set additional properties of previously imported Unified Groups. 
.\ExportImportUnifiedGroups -IncludeUsers -Mode Import -File MyUnifiedGroups.csv -RewriteTargetDomain -SourceDomain contoso.com -TargetDomain fabrikam.com 
Import users while rewriting source domain from contoso.com to fabrikam.com in a 
single-pass (1 stage) migration.  Use this when migrating Office 365 groups but not 
preserving the domain name (such as in a divestiture scenario). 
2017-10-27    - Fixed typo for Owners. 
2017-10-25     - Fixed parameter typos. 
            - Updated import/set processing to check recipients prior to processing 
              and remove users that aren't valid recipients in the tenant.