Migrate parent sensitivity labels to label groups

Microsoft 365 licensing guidance for security & compliance.

Previously, parent labels were used to organize sensitivity labels in a two-tier hierarchy. To reduce complexity, their replacement, label groups, don't support settings other than name, description, color, and priority.

For more information about parent labels and label groups, see Sublabels that use parent labels or label groups.

To migrate your parent sensitivity labels to sensitivity label groups, use the Microsoft Purview portal if you see the information banner displayed in the following instructions.

Before you begin

First, make sure you have permissions to create and manage sensitivity labels. For more information, see Permissions required to create and manage sensitivity labels.

Then, understand the impact of parent labels that if applicable, will be migrated to a sublabel with the same name, in addition to a label group. If this scenario applies to you, you must decide whether you want to leave these new sublabels published after the migration, or you want to unpublish them:

• If you decide to unpublish these new sublabels, you can do this manually, or use PowerShell scripts to automatically unpublish them.
• If you leave these new sublabels published, decide whether you will need to edit them post migration and before users can select them.

This new sublabel creation ensures that all users and services that might have accessed the parent label as a standalone label will continue to be able to access it after the migration. A parent label is considered applicable if any of the following conditions apply:

• It's configured for label actions, such as encryption or content marking.
• It has a different label scope from its sublabels. The parent label and all its sublabels must have an identical label scope for the parent label to not be considered applicable.
• It's included in a different publishing policy from its sublabels.

The resulting sublabel that's created has the same name and settings as the original parent label. Without reconfiguration, this new sublabel will be available to select in a policy where previously it couldn't be selected as a parent label.

You can confirm whether you have applicable parent labels before the labels are migrated when you review the proposed new label scheme as part of the migration process. In the following example, the parent label Confidential is identified as an applicable parent label, with the result that a new sublabel of the same name will be created:

PowerShell scripts for unpublishing sublabels from applicable parent labels

These PowerShell commands use Security & Compliance PowerShell.

Script One: Before the migration, run the following command to fetch all policies that publish parent labels.

$parents = (Get-Label | ? { $_.ParentId -ne $null } | %{ echo $_.ParentId } | Sort-Object -Unique)
$parentLabels = ($parents | % { Get-Label -Identity $_.Guid })
$policyPublishingParent = @{}
$policies = Get-LabelPolicy; $parentLabels | % { $parent = $_.Name; $policies | ? { $_.Labels -contains $parent } | 
% { echo "$($_.Name) policy has published $parent"; $(If ($policyPublishingParent.Keys -notcontains $_.Name) { 
$policyPublishingParent[$_.Name] = @() }); $policyPublishingParent[$_.Name] += $parent } }

Don't close your PowerShell session but keep it open during the label migration.

Script Two: As soon as migration is complete, run the following script to unpublish the newly created sublabels from applicable parent labels:

$policyPublishingParent.Keys | % { $policyToRemove = $_; $policyPublishingParent.Item($policyToRemove) | % { 
Set-LabelPolicy -Identity $policyToRemove -RemoveLabels $_ } 

Migrate to the modern label scheme

Migration is gradually rolling out, so migrating your parent labels to label groups might not yet be available for your tenant.

1. Sign in to the Microsoft Purview portal > Solutions > Information Protection > Sensitivity labels

2. On the Sensitivity labels page, if you see an information banner Migrate to the modern label scheme, label migration is available to your tenant. From this banner, select Get started to start the migration:

   

3. On the Migrate to the modern label scheme flyout pane, you see a summary of your sensitivity labels before and after the migration. For more details, select the Review new scheme button at the bottom of the pane. For example:

   

4. The New label scheme page shows you how your migrated labels will look in the Microsoft Purview portal, with a folder icon next to what used to be parent labels. This page will also alert you to any naming conflicts that need to be resolved before the migration. For example, the General parent label has a sublabel that's also named General. All sublabels must have a unique name from their parent label.

   You can use the Download button to save a copy to a CSV file. The default name is NewLabelSchemecsv.csv.

   Important

   Even if you don't have alerts to resolve, use this opportunity to carefully review the labels and consider making changes to them before you migrate so you can remove or minimize the applicable parent labels that will create a new sublabel if they're not needed. After making changes, restart the migration and check the post-migration information again from this page.

   For example, you might have parent labels that you've never used as standalone labels, but are configured for encryption or content markings. Label actions are one of the reasons why migration creates a new sublabel that you might not need.

5. When you're ready to migrate your labels, select the Migrate button.

   Note

   If you have applicable parent labels that will create new sublabels and you decided to use a script to automatically unpublish them, run Script One before you select Migrate.

   The migration process doesn't take long, typically just a few minutes to an hour. However, as a precaution, allow up to 24 hours. While the migration is in progress, we don't recommend making any changes to the label configuration because those changes will likely be lost.

   When the migration is complete, the browser refreshes, and the new label scheme is displayed with a message to confirm that the migration is complete.

   Note

   If you have applicable parent labels that will create new sublabels and you decided to use a script to automatically unpublish them, now run Script Two.

Next steps

For instructions to manage your migrated labels, see Create and configure sensitivity labels. Review your new label groups and migrated labels, and make any changes that you need. For example, reconfigure or unpublish any new labels that were created from parent labels.

For parent labels that were migrated to label groups, and for existing sublabels, users won't see or experience any changes in their apps. For example, priority ordering behaves the same and a default sublabel continues to be honored.