While working with a partner this weekend on a tenant to tenant migration, we had the need to migrate Office 365 groups. There's not really a lot of information around on recreating groups and memberships, so I decided to put together a tool to help the effort.
The first thing to understand about Office 365 Groups is that they are the marriage of a SharePoint site, A Yammer group (optionally), a distribution list, and a mailbox.
An Office 365 group stores email content (messages and conversations) in the mailbox, while placing files in the SharePoint document library. If you're going to embark on a tenant to tenant migration, you need to capture the email data and the site contents. Group ownership and membership are managed via the Unified Group Links properties.
To back up the groups in a rudimentary fashion, you can simply run Get-UnifiedGroup. However, that misses the ownership and membership information, so you also need to run Get-UnifiedGroupLinks (for each LinkType) and join them to the object.
Once you start looking at the output, you'll notice that the group memberships are stored using the account alias and not the SMTP address. So, if you are moving tenants (and especially if you are merging with an existing tenant), you may not be able to get the same alias again. So, you need to store those values as SMTP.
At some point, this endeavor becomes a tool.
I approached the tool with the mindset of needing to perform Office 365 groups migrations in multiple steps (such as exporting the groups from the source tenant, creating the groups in the new tenant, and then adding the users back once the domains are moved), so you can support data staging.
In a 1-stage migration, you can simply export the groups from the source tenant and import them into the target tenant with the users. This depends on the users (and domains) being in the target tenant.
In a two-stage migration (which I envision will be most scenarios), you export the groups from the source tenant, and then import them into the target tenant. At this point, you can begin staging data using your tool of choice. In most tenant to tenant migrations, you don't move the domain until the end, so your users won't exist with the proper SMTP addresses in the target tenant until cutover time (meaning you might not be able to add them in).
In a divestiture scenario (where the divesting users are getting a new domain name), you may want to remap the user's domain suffix (assuming their alias to the left of the @ stays the same). I've put a feature in for that as well.
Examples of usage:
Example 1 - Export unified groups
.ExportImportUnifiedGroups.ps1 -Mode Export -File MyUnifiedGroups.csv
In this example, you are exporting unified groups from a source tenant.
Example 2 - Import unified groups in a 1-stage migration
.ExportImportUnifiedGroups.ps1 -Mode Import -File MyUnifiedGroups.Csv -IncludeUsers
Import unified groups in a 1-stage migration (imports groups and users together). This option assumes that the domains have been migrated. Since users are resolved via SMTP address on export, the primary SMTP domains for the users must exist in the target environment. If they don't, lots of red on the screen.
Example 3 - Import unified groups in a 2-stage migration (Stage 1)
.ExportImportUnifiedGroups.ps1 -Mode Import -File MyUnifiedGroups.csv
Import unified groups in a 2-stage migration (import groups only, no members or owners). Since the users are resolved via SMTP address on the export, the primary domains for the users must exist in the target environment (is there an echo in here?).
Example 4 - Import unified groups in a 2-stage migration (Stage 2)
.ExportImportUnifiedGroups.ps1 -Mode Set -File MyUnifiedGroups.csv
Import users and set additional properties of previously imported Unified Groups. After the domains have been cut over, you re-process the export file and add the users back in.
Example 5 - Export unified groups with address rewrite
.ExportImportUnifiedGroups -IncludeUsers -Mode Import -File MyUnifiedGroups.csv -RewriteTargetDomain -SourceDomain contoso.com -TargetDomain fabrikam.com
If your organization is involved in a divestiture and the divesting entity is not retaining the primary smtp address, you can rewrite the SMTP suffix with a new address space. In this example, contoso.com is rewritten with fabrikam.com. The resulting export file has rewritten addresses.
Example 6 - Import unified groups in a 1-stage migration with address rewrite
.ExportImportUnifiedGroups -IncludeUsers -Mode Import -File MyUnifiedGroups.csv -RewriteTargetDomain -SourceDomain contoso.com -TargetDomain fabrikam.com
If your organization is involved in a divestiture and the divesting entity is not retaining the primary smtp address, you can rewrite the SMTP suffix with a new address space. In this example, contoso.com is rewritten with fabrikam.com during the import process. The original export file is not modified.
To download the tool, head over to the TechNet Gallery: https://gallery.technet.microsoft.com/Export-and-Import-Unified-e73d82ba.