The Problem: “Invisible” Retention Policies
Retention Policies are essential for data compliance, but they’re often invisible. When working in a SharePoint site or managing content in OneDrive, users and administrators can’t see which retention policies were applied.
Unlike published retention labels, these policies don’t provide any visible indication on the sites or items they govern, leading to confusion and a lack of transparency.
The Additional Challenge: Difficult Access to Policy Details in Microsoft Purview
Adding to this issue is the difficulty in accessing retention policy details within Microsoft Purview. Administrators must click through multiple screens to view most properties of a policy.
Want to see which sites or groups a policy applies to? You’ll have to dig into the “Edit” mode, then click through each location individually. This process is time-consuming, especially in environments with a large number of policies and locations.
A Questionable Rationale: "User-Friendly" Design?
Some experts suggest that this invisibility is part of a "user-friendly" design, intended to keep users from being overwhelmed by complex compliance rules. However, this rationale can be counterproductive.
Users encountering unexpected behaviours—like documents reappearing in the Preservation Hold Library after deletion (for users with appropriate permissions) —may find the system confusing rather than reassuring. Instead of enhancing the user experience, this invisibility can create frustration when users can't easily understand the rules that govern their content.
A more transparent approach, where retention policies are visible but not modifiable by end-users, could strike a better balance between user-friendliness and transparency.
A Limited Tool: Policy Lookup in Microsoft Purview
Microsoft Purview does offer a "Policy Lookup" feature within the Records Management portal. This tool allows you to search for retention policies applied to a specific User, SharePoint Site, or M365 Group by entering the exact matching string (e.g., site URL or group name).
However, even this tool has its limitations. The information it provides is restricted to Scope Types, Applications, Last Modified, and Date Created—far from the detailed, actionable insights administrators need. And you have to enter the URL of each site that you want to check. You can only search for one item at a time.
The Solution: A PowerShell Script for Visibility and Ease of Access
To address these issues, I developed a PowerShell script that automates the process of retrieving and reporting on retention policies across your Microsoft 365 environment. This script provides a clear and detailed view of where policies are applied, what specific properties they have — without the need for excessive clicking and manual checks.
What the Script Covers (and What It Doesn’t)
The script retrieves retention policies across your Microsoft 365 environment and generates a detailed report saved in a CSV file. This report provides insights into which policies are applied to specific locations and outlines their key properties.
Once the script generates the CSV file, you can easily load it into Excel for further analysis. This is particularly useful if you’re dealing with a large-scale implementation where the sheer number of retention policies could be overwhelming.
Excel’s powerful data filtering, sorting, and pivot table features make it easy to break down the data, identify patterns, and gain insights that might be difficult to see in a simple list format.
The screenshots of the excel file are below. I generated the report in my demo Tenant, which is nearly empty. But it is still sufficient to show the attributes that are captured:
What It Reports On:
Retention Policies (Remember that Retention Policies are applied to the containers).
Auto-Apply Label Policies: It also reports on policies that automatically apply retention labels to content based on specific criteria.
What It Doesn’t Report On:
Label Publishing Policies: The script doesn’t report on label publishing policies that push labels to sites, as these labels become self-evident once applied. Administrators and users can easily see the labels in use without needing additional reporting.
Here’s a quick overview of how the script works:
Shows Where Policies Are Applied: The script lists all locations as well as the location exceptions, such as the URLs of SharePoint sites or the names of Modern Groups affected by the policies, making it clear which locations are under governance.
Provides Policy Details: It outputs key details about each policy, including the retention duration, actions, and any exceptions.
Customizable: You can easily modify the script to add more properties or adjust the output to meet your specific needs.
Connecting to MS Purview
In order to run any script from this article, you need to connect to Compliance Center: Make sure that ExchangeOnlineManagement Module is installed or install it:
Install-Module -Name ExchangeOnlineManagement Import the Module:
Import-Module ExchangeOnlineManagementConnect to Compliance Center:
Connect-IPPSSession -UserPrincipalName Name@Tenant.onmicrosoft.com
Exploring Retention Policy Properties
To explore additional available properties of a retention policy, you can use the following PowerShell script:
# Lists available properties of the Retention Policy
$PolicyName = "M365 Groups"
# Retrieve the policy by name
$Policy = Get-RetentionCompliancePolicy -Identity $PolicyName -DistributionDetail
# Output all properties of the policy
$Policy | Format-List -Property *
# Retrieve all associated rules for this policy
$Rules = Get-RetentionComplianceRule -Policy $PolicyName
# Output all properties of the rules associated with the policy
ForEach ($Rule in $Rules) {
$Rule | Format-List -Property *
}This script allows you to inspect all the available properties of a specific retention policy, making it easier to identify additional attributes you may want to include in your custom reports. By understanding these properties, you can enhance your reporting scripts to capture more detailed information, tailoring the output to your specific needs.
How to Get It
You can find the script on GitHub here.
While this script has been tested on most locations and attributes, it has not been fully tested with Teams policies and a few specific properties. I’ve run it successfully in my Demo Tenant, but I can’t guarantee how scalable it will be when applied to a very large Tenant.
Therefore, please use it at your discretion and always test it first in a controlled environment.
Nevertheless, this script serves as a strong starting point for gaining better visibility into your retention policies.
Understanding RetentionRuleTypes and Customizing Your Script
RetentionRuleTypes property plays a crucial role in identifying the type of each policy. Understanding these values is key to customizing your script and focusing on the policies that matter most to your scenario.
Here are the possible values for RetentionRuleTypes:
Publish: Represents Label Publishing Policies. These policies are designed to make labels available for manual application by users within the Microsoft 365 environment.
Apply: Refers to Auto-Apply Label Retention Policies. These policies automatically apply specific labels to content based on predefined criteria.
Default: Indicates a "standard" Retention Policy. These are the general retention policies applied across various locations in your Microsoft 365 environment, often setting the baseline for data retention and deletion.
Customizing the Script to Filter Policies by Type
The script excludes Publish RetentionRuleTypes of the policies, since they are already visible in the UI. This is achieved with the following line:
$Policies = Get-RetentionCompliancePolicy -DistributionDetail -RetentionRuleTypes | Where-Object { $_.RetentionRuleTypes -ne "Publish" }However, if you wish to target specific types of policies, you can easily modify this line using the -eq operator for exact matches. For example:
To retrieve only "standard" Retention Policies (Default):
$Policies = Get-RetentionCompliancePolicy -DistributionDetail -RetentionRuleTypes | Where-Object { $_.RetentionRuleTypes -eq "Default" }To retrieve only Auto-Apply Label Retention Policies (Apply):
$Policies = Get-RetentionCompliancePolicy -DistributionDetail -RetentionRuleTypes | Where-Object { $_.RetentionRuleTypes -eq "Apply" }But if you need to retrieve Policies that publish labels to the workloads (Publish):
$Policies = Get-RetentionCompliancePolicy -DistributionDetail -RetentionRuleTypes | Where-Object { $_.RetentionRuleTypes -eq "Publish" }Whether you’re focusing on standard retention policies, auto-apply label policies, or something else, this approach gives you full control over the data you extract and analyze.
If you just want to view all Policies along with RetentionRuleTypes, use the following script:
# Retrieve all retention policies from the tenant with RetentionRuleTypes
$Policies = Get-RetentionCompliancePolicy -DistributionDetail -RetentionRuleTypes
# Process each policy and create a custom object
$PolicyOutput = $Policies | ForEach-Object {[PSCustomObject]@{
Name = $_.Name
RetentionRuleTypes = $_.RetentionRuleTypes -join ", "
}
}
# Output the results in a table and order by RetentionRuleTypes
$PolicyOutput | Sort-Object RetentionRuleTypes | Format-Table Name, RetentionRuleTypes -AutoSizeHere is an output when I run the script in my demo Tenant:
Commenti