Applying Retention Labels to SharePoint Files using PnP PowerShell

Retention labels in SharePoint Online help organizations manage content lifecycle by enforcing rules such as retention, deletion, or records management. Microsoft Purview provides tools for defining Retention Labels, which can be applied to SharePoint document libraries, folders, or files.

PnP PowerShell simplifies the process of applying Retention Labels programmatically. This guide provides a step-by-step approach to applying and managing Retention Labels using PnP PowerShell.

Step 1: Prerequisites

1.1 Install and Update PnP PowerShell

Ensure PnP PowerShell is installed on your system. If not, install it using the following command:

Install-Module PnP.PowerShell -Scope CurrentUser

To update PnP PowerShell to the latest version:

Update-Module PnP.PowerShell

1.2 Required Permissions

Global Administrator or SharePoint Administrator role in Microsoft 365
Microsoft Purview Compliance Center access to define retention labels
Ensure PnP Management Shell is registered in Azure AD

1.3 Connect to SharePoint Online

Run the following command to connect to your SharePoint Online environment:

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/YourSite" -Interactive

Replace "yourtenant" with your actual tenant name and "YourSite" with the target SharePoint site.

Step 2: Retrieve Available Retention Labels

Before applying labels, retrieve the list of existing Retention Labels from Microsoft Purview.

Get-PnPRetentionLabel

This command will return all Retention Labels configured in your Microsoft 365 Compliance Center.

Step 3: Apply Retention Labels to Files in a SharePoint Library

3.1 Apply a Retention Label to a Single File

To apply a Retention Label to a specific document, use the Set-PnPListItem command.

$libraryName = "Documents"
$filePath = "Shared Documents/TestFile.pdf"
$retentionLabel = "Confidential Retention"

# Get the file's list item
$item = Get-PnPListItem -List $libraryName -Fields "FileRef" | Where-Object { $_["FileRef"] -eq $filePath }

# Apply the retention label
Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = $retentionLabel}

Replace “Documents” with the actual document library name.
Replace “Shared Documents/TestFile.pdf” with the file’s path inside the library.
Replace “Confidential Retention” with the exact retention label name retrieved from Step 2.

3.2 Apply a Retention Label to All Files in a Library

To apply a Retention Label to all files in a document library:

$libraryName = "Documents"
$retentionLabel = "Confidential Retention"

# Get all items in the library
$items = Get-PnPListItem -List $libraryName -Fields "ID"

foreach ($item in $items) {
    Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = $retentionLabel}
    Write-Host "Applied label '$retentionLabel' to item ID: $($item.Id)"
}

This script:
Fetches all files in the Documents library.
Applies the Retention Label to each file.
Displays a success message for each file.

Step 4: Apply Retention Labels to Files in Specific Folders

To apply retention labels only to files inside a specific folder, modify the script as follows:

$libraryName = "Documents"
$folderPath = "Shared Documents/Confidential"
$retentionLabel = "Confidential Retention"

# Get all items within the specified folder
$items = Get-PnPListItem -List $libraryName -Fields "FileRef" | Where-Object { $_["FileRef"] -like "$folderPath/*" }

foreach ($item in $items) {
    Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = $retentionLabel}
    Write-Host "Applied label '$retentionLabel' to file: $($item.FileRef)"
}

Replace “Confidential” with the actual folder name inside the document library.
This script filters files within the Confidential folder and applies the retention label.

Step 5: Remove a Retention Label from Files

To remove a Retention Label, set the ComplianceTag property to "" (empty string):

$libraryName = "Documents"
$filePath = "Shared Documents/TestFile.pdf"

# Get the file's list item
$item = Get-PnPListItem -List $libraryName -Fields "FileRef" | Where-Object { $_["FileRef"] -eq $filePath }

# Remove the retention label
Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = ""}
Write-Host "Removed retention label from file: $filePath"

For bulk removal, loop through all files:

$libraryName = "Documents"

# Get all items in the library
$items = Get-PnPListItem -List $libraryName -Fields "ID"

foreach ($item in $items) {
    Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = ""}
    Write-Host "Removed retention label from item ID: $($item.Id)"
}

Step 6: Automate Retention Label Assignment from a CSV File

If you need to apply retention labels to multiple files from a CSV file, follow these steps:

6.1 Create a CSV File

Create a CSV file (RetentionLabels.csv) with the following format:

FilePath,RetentionLabel
Shared Documents/Confidential/Report1.pdf,Confidential Retention
Shared Documents/Public/Policy.docx,Public Retention
Shared Documents/Internal/Budget.xlsx,Internal Retention

6.2 Apply Labels in Bulk Using PowerShell

Run the following script to apply labels from the CSV file:

$libraryName = "Documents"
$csvFile = "C:\Path\To\RetentionLabels.csv"
$files = Import-Csv -Path $csvFile

foreach ($file in $files) {
    $item = Get-PnPListItem -List $libraryName -Fields "FileRef" | Where-Object { $_["FileRef"] -eq $file.FilePath }
    
    if ($item) {
        Set-PnPListItem -List $libraryName -Identity $item.Id -Values @{"ComplianceTag" = $file.RetentionLabel}
        Write-Host "Applied label '$($file.RetentionLabel)' to file: $($file.FilePath)"
    } else {
        Write-Host "File not found: $($file.FilePath)"
    }
}