How to migrate Microsoft 365 Groups and Planner plans to another tenant

Install the module if needed (how-to), sign in to the source tenant in the browser window that opens and accept the scopes, then export each group with its mail nickname and visibility.

Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes "Group.Read.All","Tasks.Read"
Get-MgGroup -Filter "groupTypes/any(c:c eq 'Unified')" -All |
  Select-Object Id,DisplayName,MailNickname,Mail,Visibility |
  Export-Csv C:\migration\groups.csv -NoTypeInformation

Record owners and members by user principal name so you can map them to target accounts.

$groups = Import-Csv C:\migration\groups.csv
foreach ($g in $groups) {
  Get-MgGroupOwner -GroupId $g.Id -All |
    ForEach-Object { [pscustomobject]@{Group=$g.MailNickname; Role="Owner"; UPN=$_.AdditionalProperties.userPrincipalName} }
  Get-MgGroupMember -GroupId $g.Id -All |
    ForEach-Object { [pscustomobject]@{Group=$g.MailNickname; Role="Member"; UPN=$_.AdditionalProperties.userPrincipalName} }
} | Export-Csv C:\migration\group-membership.csv -NoTypeInformation

Graph does not show every mail setting. Use Exchange Online PowerShell for addresses, privacy and delivery settings. To install and connect, see Connect to Exchange Online PowerShell.

Connect-ExchangeOnline
Get-UnifiedGroup -ResultSize Unlimited -IncludeAllProperties |
  Select-Object DisplayName,PrimarySmtpAddress,@{n="EmailAddresses";e={$_.EmailAddresses -join ";"}},AccessType,HiddenFromAddressListsEnabled,HiddenFromExchangeClientsEnabled,RequireSenderAuthenticationEnabled,AutoSubscribeNewMembers |
  Export-Csv C:\migration\group-settings.csv -NoTypeInformation

Plans live inside groups. Record each plan with its bucket and task count so you can check the rebuild later.

foreach ($g in $groups) {
  Get-MgGroupPlannerPlan -GroupId $g.Id | ForEach-Object {
    [pscustomobject]@{
      Group   = $g.MailNickname
      Plan    = $_.Title
      PlanId  = $_.Id
      Buckets = (Get-MgPlannerPlanBucket -PlannerPlanId $_.Id).Count
      Tasks   = (Get-MgPlannerPlanTask -PlannerPlanId $_.Id -All).Count
    }
  }
} | Export-Csv C:\migration\plans.csv -NoTypeInformation

Send each owner their rows from groups.csv and plans.csv and ask which groups and plans are still used. Archive completed plans as Excel exports (Step 6) instead of rebuilding them.

Owners, members and task assignees must exist in the target. Create them with Bulk create users in Microsoft 365 or the Entra ID cross-tenant guide. Then add target UPN and target object ID columns to your mapping sheet and save it as C:\migration\group-membership-mapped.csv with columns Group, Role and TargetUPN.

# Target tenant: object IDs for the mapping sheet
Connect-MgGraph -Scopes "User.Read.All"
Get-MgUser -All | Select-Object Id,UserPrincipalName | Export-Csv C:\migration\target-users.csv -NoTypeInformation

A group cannot use an address on a domain that is still verified in the source tenant. Until the domain moves, create groups with an address on the target's initial or another verified domain, then add the final address at cutover. See moving a domain between tenants.

Open Naming policy and note any prefix, suffix or blocked words. Microsoft says the naming policy does not apply to Global Administrator or User Administrator, so run the scripts as one of those if you want names unchanged. Check whether group creation is restricted with the Group.Unified directory setting (EnableGroupCreation and GroupCreationAllowedGroupId) and make sure the migration account is allowed.

Connect-MgGraph -Scopes "Directory.Read.All"
(Get-MgBetaDirectorySetting | Where-Object { $_.DisplayName -eq "Group.Unified" }).Values

Set groupTypes to Unified with mailEnabled true and securityEnabled false. Microsoft allows up to 20 relationships, such as owners and members combined, in the create call. Add owners at creation and members afterwards. If the group's SharePoint site will move with Microsoft's cross-tenant SharePoint migration, create it the way the SharePoint guide describes instead.

Connect-MgGraph -Scopes "Group.ReadWrite.All","User.Read.All"
$params = @{
  displayName     = "Marketing"
  description     = "Marketing team"
  groupTypes      = @("Unified")
  mailEnabled     = $true
  mailNickname    = "marketing"
  securityEnabled = $false
  visibility      = "Private"
  "owners@odata.bind" = @(
    "https://graph.microsoft.com/v1.0/users/<targetOwnerObjectId>"
  )
}
$group = New-MgGroup -BodyParameter $params

Bulk-adding members to a new group can send each one a welcome email. Switch it off before adding members.

Connect-ExchangeOnline
Set-UnifiedGroup -Identity "Marketing" -UnifiedGroupWelcomeMessageEnabled:$false

Use the mapping sheet to resolve each target user, then add them by reference.

$map = Import-Csv C:\migration\group-membership-mapped.csv   # Group,Role,TargetUPN
foreach ($row in $map | Where-Object Group -eq "marketing") {
  $user = Get-MgUser -UserId $row.TargetUPN
  $ref  = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/$($user.Id)" }
  if ($row.Role -eq "Owner") {
    New-MgGroupOwnerByRef -GroupId $group.Id -BodyParameter $ref
  } else {
    New-MgGroupMemberByRef -GroupId $group.Id -BodyParameter $ref
  }
}

Creating a group with Graph does not add you as a member, and Microsoft requires the account creating a Planner plan to be a member of the group. Add the migration account now and remove it after the Planner rebuild.

$me = Get-MgUser -UserId "migration@fabrikam.onmicrosoft.com"
New-MgGroupMemberByRef -GroupId $group.Id -BodyParameter @{ "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/$($me.Id)" }

Reapply the settings you exported to group-settings.csv. Lower-case smtp: adds a secondary address; upper-case SMTP: sets the primary. You cannot use -EmailAddresses and -PrimarySmtpAddress in the same command.

Set-UnifiedGroup -Identity "Marketing" -AccessType Private
Set-UnifiedGroup -Identity "Marketing" -RequireSenderAuthenticationEnabled $false
Set-UnifiedGroup -Identity "Marketing" -HiddenFromAddressListsEnabled $true
Set-UnifiedGroup -Identity "Marketing" -EmailAddresses @{Add="smtp:mktg@fabrikam.com"}

Microsoft's FastTrack cross-tenant documentation lists Microsoft 365 group-connected sites among the SharePoint content that migrates, and asks you to pre-create the Microsoft 365 groups connected to those sites in the target. Follow the SharePoint cross-tenant migration guide after Step 4. To install the shell, see Install SharePoint Online Management Shell.

Microsoft does not document a native way to move group conversations or the group calendar between tenants. Choose a third-party tool that lists Microsoft 365 group mailboxes as a supported source, or keep the source group read-only for reference and start fresh in the target. Record the decision per group.

If the group has a team, plan the team, channels and chat history together. See Teams chat migration.

Microsoft says distribution lists and mail contacts are not part of mailbox data migration and must be pre-created in the target. Handle them in the same batch as your groups.

New-DistributionGroup -Name "All Sales" -Alias allsales -PrimarySmtpAddress allsales@fabrikam.onmicrosoft.com
New-MailContact -Name "Supplier Accounts" -ExternalEmailAddress accounts@supplier.example

Whatever method you choose, open each plan, select the ... menu in the plan header and choose Export as Excel. Microsoft lists plan name and ID, task ID, title, description, bucket, status, start and due dates, assignments, priority and labels. Microsoft notes these steps are being updated for the new Planner experience. Store each file with your migration records.

Microsoft says premium plans and tasks are not available in the Planner API, so they are missing from plans.csv. Ask owners for any plans they use that are not in the list, and mark them for a vendor tool or a manual rebuild.

Save buckets and tasks to JSON so the write step can run in a separate session. Take the PlanId from plans.csv.

Connect-MgGraph -Scopes "Tasks.Read","Group.Read.All"   # source tenant
$planId = "<sourcePlanId>"
Get-MgPlannerPlanBucket -PlannerPlanId $planId | ConvertTo-Json -Depth 5 | Out-File C:\migration\buckets.json
Get-MgPlannerPlanTask -PlannerPlanId $planId -All | ConvertTo-Json -Depth 10 | Out-File C:\migration\tasks.json

Disconnect, sign in to the target as the migration account (a member of the group), and create the plan. The plan's container is the target group and cannot be changed after it is set.

Disconnect-MgGraph
Connect-MgGraph -Scopes "Tasks.ReadWrite","Group.ReadWrite.All"   # target tenant
$params = @{
  container = @{ url = "https://graph.microsoft.com/v1.0/groups/<targetGroupId>" }
  title     = "Marketing campaigns"
}
$plan = New-MgPlannerPlan -BodyParameter $params

Use " !" as the order hint for new items. Microsoft warns that an order hint copied directly from a response causes a 400 error.

$bucketMap = @{}
foreach ($b in (Get-Content C:\migration\buckets.json | ConvertFrom-Json)) {
  $new = New-MgPlannerBucket -BodyParameter @{ name = $b.Name; planId = $plan.Id; orderHint = " !" }
  $bucketMap[$b.Id] = $new.Id
}

Assignments are keyed by the target user's object ID. Each entry needs @odata.type and an orderHint. Fill $userMap from your mapping sheet (source object ID to target object ID).

$userMap = @{}   # sourceUserId -> targetUserId, loaded from your mapping sheet
foreach ($t in (Get-Content C:\migration\tasks.json | ConvertFrom-Json)) {
  $assign = @{}
  foreach ($uid in $t.Assignments.PSObject.Properties.Name) {
    if ($userMap[$uid]) {
      $assign[$userMap[$uid]] = @{ "@odata.type" = "#microsoft.graph.plannerAssignment"; orderHint = " !" }
    }
  }
  $params = @{
    planId      = $plan.Id
    bucketId    = $bucketMap[$t.BucketId]
    title       = $t.Title
    assignments = $assign
  }
  if ($t.DueDateTime)   { $params.dueDateTime   = $t.DueDateTime }
  if ($t.StartDateTime) { $params.startDateTime = $t.StartDateTime }
  New-MgPlannerTask -BodyParameter $params | Out-Null
}

Descriptions, checklists and references live on the task details object. Planner versions every object with an etag: updates must send the last known etag in an If-Match header (the -IfMatch parameter), or Planner returns 412. Read the details first, then update with the etag you received.

Compare bucket and task counts in the target with plans.csv, and spot-check assignments and dates against the Excel export. Record the result per plan.

Tell owners when source plans become read-only. Changes made after your export will not reach the target. Send the date at least a week ahead and again on the day.

Once the domain is verified in the target, set the primary address on each group and add any remaining aliases.

Set-UnifiedGroup -Identity "Marketing" -PrimarySmtpAddress marketing@contoso.com

Remove the account you added as a member in Step 4 from every target group.

Remove-MgGroupMemberDirectoryObjectByRef -GroupId $group.Id -DirectoryObjectId $me.Id

Each group owner confirms membership, site access, plans and task assignments. Log gaps in the hypercare issue log.

Agree a retention period with owners and your compliance team before deleting anything, and record it in the checklist.

Microsoft says deleting a group automatically deletes all plans it contains, and restoring the group restores them. Delete source groups only after the Excel exports are filed and owners have signed off.

Remove-MgGroup -GroupId <sourceGroupId>