Practical Purview: Replacing Purview Retention Labels with PowerShell

Programmatically Changing Retention Labels

If Purview retention labels are already applied to files across your tenant’s SharePoint sites, the need might arise to change the label that is applied. Once a label is applied to a file (through any means), it remains in place until either manually or implicitly changed using one of these methods:

1. The default retention label is changed at the container (library or folder) level. All items within the container that have inherited the original default label will automatically update to the new default label.
2. The retention action for the label is configured to apply a different retention label at the end of the retention period.
3. The retention action for the label is configured to run a Power Automate flow at the end of the retention period and the flow applies a different retention label.
4. Programmatically replace the label, which is the topic of this article.

There are several reasons for needing to programmatically replace a retention label that the first three options don’t address:

• You may need to change the retention label before it reaches the end of its retention period and it is not set as a default label on the library or folder
• A retention label has been applied to a file with an auto-apply label policy. The conditions have changed, and you now need a different label to be applied.
• Retention label names don’t always stay the same. Regulations change, organizations change, and business rules change and, as a result, you may need to change a retention label to reflect the new name. Unlike sensitivity labels, you cannot change a retention label name once the label’s been created. Alternatively, you must create a new retention label with the same settings and the updated name and update files with the old retention label.

This article describes how to update a retention label on files across a SharePoint site using the Microsoft Graph PowerShell SDK. I do not explain how to retrieve a SharePoint site and the document libraries within. For an example of how to navigate within a SharePoint site, refer to Create a SharePoint Online Files Report with the Graph PowerShell SDK.

What to Know Before You Start

The script can update both a standard label and record label to another standard label or record label given the required permissions. The permissions depend on whether you are updating from a standard or record label (the ‘Item is a record’ checkbox is selected in the Purview retention label configuration for a record label).

• Permissions for updating from a standard label: Sites.Read.All, Files.ReadWrite.All
• Permissions for updating from a record label: Sites.FullControl.All, File.ReadWrite.All (you also need to be a site collection administrator if using delegated permissions)
• Permissions for listing the Purview retention label settings to determine if the label you are updating from is a record label: RecordsManagement.Read.All

To determine if the label you are updating to needs to be published to the new location, you must know if the retention label you are updating to is an event-based label (the retention label is configured to start retention on a custom event date).

If the new retention label is not event-based, you do not need to publish the new retention label to the SharePoint site to apply the new retention label to files.

If the new retention label is event-based, the label update will work, but you must publish the event-based retention label to the SharePoint site so you can see the Asset Id column in the file’s detail information pane. This column is used for built-in event-based retention. If you are using a custom column instead of the Asset Id column for your event-based label, you do not need to publish the label to the site.

Note: If regulatory record labels are enabled in your tenant and applied to content, they cannot be updated. This is by design.

The Script

Disclaimer: Do not use this script in production until you have determined that the code meets the needs of your organization. This script should first be validated in a non-production environment.

The script targets all files in a document library in a single SharePoint site. In a production scenario, you could read a csv file of SharePoint site URLs and document library names for locations where the retention label update is required. This would provide the flexibility of picking which document libraries you want to change the label on in case you don’t want to necessarily change the label on all files across all document libraries. This may happen if a new label is created due to a re-organization of a company where a department is now split into two and only one of the departments needs their labels updated.

The script accepts the following parameters:

param (
    [string]$siteURL,
    [string]$documentLibraryName,
    [string]$oldRetentionLabelName,
    [string]$newRetentionLabelName
)

Figure 1 shows the script running.

The script must know if the old retention label is a record label so it can lock any unlocked records during the update process. The Get-MgSecurityLabelRetentionLabel cmdlet retrieves all retention labels from Purview and the retainAsRecord property on the retention label’s information identifies the label as a record label. Note: This cmdlet does not support application permissions.

$RetentionLabels = Get-MgSecurityLabelRetentionLabel
$RetentionLabel = $RetentionLabels | Where-Object { $_.DisplayName -eq $oldRetentionLabelName }
$Global:IsRecordLabel = if ($RetentionLabel.BehaviorDuringRetentionPeriod -eq "retainAsRecord") {$true} else {$false}

Only when a record label is locked can it be updated to another label. Passing the isRecordLocked parameter in the retention setting to any file with a record label that is currently unlocked will lock the file.

$params = @{ retentionSettings = @{ isRecordLocked = $true }}
Update-MgDriveItemRetentionLabel -DriveId $Drive -DriveItemId $driveItemId -BodyParameter $params

If you need to remove a label applied to a file rather than updating it to another label, you can use the Remove-MgDriveItemRetentionLabel cmdlet. In this script, I pass the word CLEAR in the new retention label name parameter to signify a retention label removal.

Remove-MgDriveItemRetentionLabel -DriveId $Drive -DriveItemId $File.Id

The script is modeled after the script in the article about generating a report about files in a SharePoint document library to retrieveall files in the library as well as the generation of a csv file which this script uses to capture label updates.

 The retention label is retrieved for each file using the Get-MgDriveItemRetentionlabel cmdlet.

$RetentionlabelInfo = Get-MgDriveItemRetentionLabel -DriveId $Drive -DriveItemId $File.id

If the old retention label is applied to the file, the script updates the label with the new label name taking care to lock any unlocked record labels prior to updating.

if ($null -ne $RetentionLabelName -and $RetentionLabelName -eq $oldRetentionLabelName) {
  if ($global:IsRecordLabel -and $RetentionLabelInfo.RetentionSettings.IsRecordLocked -ne $true) {
              Lock-Record -Drive $Drive -DriveItemId $File.Id
              $lockedByScript = $true
  } else {
              $lockedByScript = $false
  }
  if ($newRetentionLabelName -eq "CLEAR") {
       Remove-MgDriveItemRetentionLabel -DriveId $Drive -DriveItemId $File.Id
  } else {
       $UpdatedLabel = Update-MgDriveItemRetentionLabel -DriveId $Drive -DriveItemId $File.Id -BodyParameter @{name = $newRetentionLabelName}
  }  
}

The Report Output

The output is a PowerShell list (shown in Figure 2). The script also exports the content of the list to a CSV file.

You can download the full script from GitHub.

What This Script Doesn’t do (but Would be Good to Add)

If a retention label is applied to a folder, all unlabeled files within the folder inherit the label. This script could be updated to check if a retention label has been applied to a folder and update the label on the folder as well.

As a script input, read a CSV file of all SharePoint sites, their document libraries, the old retention label, and the new retention label.

This script does not respond to API throttling. Depending on the size of the document library and how many files will be updated in the process, you may have to adjust the script to respond to throttling by retrying the update operation after the Retry-After delay.

This script uses delegated permissions. You may want to switch to app-only permissions in a production scenario. The Get-MgSecurityLabelRetentionLabel cmdlet does not support app-only permissions so switching to app-only permissions would require a different method to retrieve all retention labels from Purview.

Non-Technical Considerations

Consider these potential impacts not addressed in the script:

• If any file being updated is currently under a disposition review, you may not want to update the label due to unknown downstream effects
• If an event has already been triggered for a file that has an event-based retention label applied, you may not want to update the label since the retention event has already started

Closing Thoughts

There is a change in development in the Microsoft 365 Roadmap (Bulk replacement or removal of a retention label – Feature Id 392456) with an estimated Preview available in July 2025. Based on the description, it can perform the action of replacing/removing a retention label across the entire tenant or targeted to specific content using KQL and static or adaptive scopes. This is welcome news for organizations needing this capability.