Automating SharePoint Online File Retention Policies using PnP PowerShell

Automating file retention policies in SharePoint Online ensures compliance, security, and data lifecycle management. Using PnP PowerShell, we can:
Create and assign retention policies to document libraries
Move, archive, or delete files based on retention rules
Monitor and enforce policy compliance
Automate cleanup of old documents

Step 1: Connect to SharePoint Online

Before managing retention policies, authenticate using PnP PowerShell:

$siteUrl = "https://yourtenant.sharepoint.com/sites/YourSite"
Connect-PnPOnline -Url $siteUrl -Interactive
Write-Host " Connected to SharePoint Online"

✔ Ensures secure authentication for policy management.

Step 2: Create a Retention Label in SharePoint Online

Retention labels define how long documents are kept and what happens afterward.

$labelName = "Retention_7Years"
New-PnPRetentionCompliancePolicy -Name $labelName -RetentionDuration 7 -RetentionAction "Delete"

Write-Host " Created Retention Label: $labelName"

✔ This label deletes files automatically after 7 years.

Step 3: Apply Retention Label to a SharePoint Document Library

To enforce the retention policy, assign it to a specific library:

$libraryName = "Documents"
$labelName = "Retention_7Years"

Set-PnPList -Identity $libraryName -Label $labelName

Write-Host " Applied retention label to $libraryName"

✔ Ensures all files in the library comply with retention rules.

Step 4: Automate File Cleanup Based on Retention Policies

To delete expired files, schedule a PnP PowerShell script:

$library = Get-PnPList -Identity "Documents"
$expiredFiles = Get-PnPListItem -List $library -Query "<View><Query><Where><Lt><FieldRef Name='Created' /><Value Type='DateTime'>$(Get-Date).AddYears(-7)</Value></Lt></Where></Query></View>"

foreach ($file in $expiredFiles) {
    Remove-PnPListItem -List "Documents" -Identity $file.Id -Recycle
    Write-Host "🗑 Deleted expired file: $($file.FieldValues['FileLeafRef'])"
}

Write-Host " Expired files removed"

✔ Automatically removes files older than 7 years.

Step 5: Archive Old Files Instead of Deleting

If files should be moved to an archive library instead of deleted:

$archiveLibrary = "Archived Documents"
$sourceLibrary = "Documents"

$oldFiles = Get-PnPListItem -List $sourceLibrary -Query "<View><Query><Where><Lt><FieldRef Name='Created' /><Value Type='DateTime'>$(Get-Date).AddYears(-5)</Value></Lt></Where></Query></View>"

foreach ($file in $oldFiles) {
    $fileUrl = $file.FieldValues["FileRef"]
    Move-PnPFile -ServerRelativeUrl $fileUrl -TargetLibrary $archiveLibrary -Force
    Write-Host " Archived file: $($file.FieldValues['FileLeafRef'])"
}

Write-Host " Old files moved to archive"

✔ Moves files older than 5 years to an archived library.

Step 6: Automate Retention Policy Enforcement

To run the script weekly, schedule it using Task Scheduler:

$taskName = "SharePoint Retention Policy Automation"
$scriptPath = "C:\Scripts\RetentionPolicy.ps1"

$action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File $scriptPath"
$trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Sunday -At 3AM
Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -User "SYSTEM" -RunLevel Highest

Write-Host " Scheduled retention policy enforcement."

✔ Fully automates SharePoint retention management.

Step 7: Audit Retention Policy Compliance

Generate a compliance report for SharePoint document libraries:

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

$library = "Documents"
$files = Get-PnPListItem -List $library | Select Id, FileLeafRef, Created

Write-Output "Retention Policy Compliance Report - $library" > Retention_Report.csv
$files | Export-Csv -Path "Retention_Report.csv" -NoTypeInformation

Write-Host " Compliance report generated: Retention_Report.csv"

✔ Tracks which files comply with retention rules.