Create Retention Policies using PowerShell

I am a big advocate of using PowerShell where possible for managing Microsoft 365. However, many organizations I work with don’t realize how much PowerShell does and use the Admin Centers instead. One area where organizations don’t usually use PowerShell is with Retention policies. It is often due to each company thinking that their policies are very different from anther’s. In reality, however, most organizations use the same Retention policies and schedules.

We will create three retention policies for this post, one for Exchange Online only, a second for SharePoint Online, and one for Microsoft Teams. These policies will retain the content for a specific amount of time and then delete it.

There are two commands we can use to create the policies and rules. They are:

The steps required for deploying a Compliance policy with rules are:

Connect to Microsoft 365 Security and Compliance
Define usable variables
Create the Compliance Policy
Create the Compliance Rule

Step 1: Connect to Microsoft 365 Security and Compliance

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-IPPSSession -UserPrincipalName user@domain.onmicrosoft.com

Step 2: Define usable variables

$exchname = "Exchange Policy"
$exchnamerule = "Exchange Policy Rule"
$exchdescription = "Exchange Policy"

$teamsname = "Teams Policy"
$teamsnamerule = "Teams Policy Rule"
$teamsdescription = "Teams Policy"

$sponame = "SharePoint Policy"
$sponamerule = "SharePoint Policy Rule"
$spodescription = "SharePoint Policy"

Step 3: Create the Compliance Policies

NOTE: You cannot create a single policy with all locations including Teams and Yammer. If you require a Teams or Yammer policy, they need creating separately.

# Create the Exchange Only Policy
$exchpolicy = New-RetentionCompliancePolicy `
	-Name $exchname `
	-Comment $exchdescription `
	-ExchangeLocation All `
	-PublicFolderLocation All `
	-Enabled $false

# Create the Teams Only Policy
$teamspolicy = New-RetentionCompliancePolicy `
	-Name $teamsname `
	-Comment $teamsdescription `
	-TeamsChannelLocation All `
	-TeamsChatLocation All `
	-Enabled $true

# Create the SharePoint Only Policy
$spopolicy = New-RetentionCompliancePolicy `
	-Name $sponame `
	-Comment $spodescription `
	-SharePointLocation All `
	-ModernGroupLocation All `
	-OneDriveLocation All `
	-Enabled $true

Once the polices save, they become visible within the Compliance admin center.

Step 4: Create the Compliance Rules

NOTE: The supported properties for Microsoft Teams are different to other rules.

# Create Exchange Only Policy Rule
New-RetentionComplianceRule `
	-Name $exchnamerule `
	-Policy $exchpolicy.Id `
	-RetentionDuration 2555 `
	-RetentionComplianceAction KeepAndDelete `
	-ExpirationDateOption ModificationAgeInDays

# Create Teams Only Policy Rule
New-RetentionComplianceRule `
	-Name $teamsnamerule `
	-Policy $teamspolicy.Id `
	-RetentionDuration 2555 `
	-RetentionComplianceAction KeepAndDelete

# Create SharePoint Only Policy Rule
New-RetentionComplianceRule `
	-Name $sponamerule `
	-Policy $spopolicy.Id `
	-RetentionDuration 2555 `
	-RetentionComplianceAction KeepAndDelete `
	-ExpirationDateOption ModificationAgeInDays

Accessing the Compliance admin center displays the policies, and if we click into a policy, our settings show.

These policies are just basic retention policies. If we needed an approach that combined sources, included and excluded specific locations or users, plus performed more complex retention, we could create it with PowerShell.

# Create Combined Variables
$combinedname = "Combined Retention Policy"
$combinednamerule = "Combined Retention Policy Rule"
$combineddescription = "Combined Retention Policy"

# Create Combined Retention Policy
$combinedpolicy = New-RetentionCompliancePolicy `
	-Name $combinedname `
	-Comment $combineddescription `
	-ExchangeLocation All `
	-ExchangeLocationException "adelev@m365x.onmicrosoft.com","pradeepg@m365x.onmicrosoft.com" `
	-SharePointLocation All `
	-SharePointLocationException "https://m365x.sharepoint.com/sites/ContosoBrand","https://m365x.sharepoint.com/sites/RetailOperations" `
	-ModernGroupLocation All `
	-OneDriveLocation All `
	-OneDriveLocationException "https://m365x-my.sharepoint.com/personal/diegos_m365x_onmicrosoft_com", "https://m365x-my.sharepoint.com/personal/gradya_m365x_onmicrosoft_com" `
	-SkypeLocation "leeg@m365x.onmicrosoft.com" `
	-PublicFolderLocation All `
	-Enabled $false

NOTE: Once the policy creates, you are not able to edit the policy, until it is enabled. To resolve this at creation, change the “Enabled” property to “True”

# Create Combined Retention Policy Rule
New-RetentionComplianceRule `
	-Name $combinednamerule `
	-Policy $combinedpolicy.Id `
	-ContentMatchQuery "filetype:docx" `
	-RetentionDuration 2555 `
	-RetentionComplianceAction KeepAndDelete `
	-ExpirationDateOption ModificationAgeInDays

Creating Retention policies using PowerShell provides you a repeatable and scripted process for deployment. I highly recommend using PowerShell as the approach for creating Retention policies to ensure consistency and better management.