Skip to content
Browse

/commands/purview/retention-policy-and-label-cmdlets

Purview retention in PowerShell: New-RetentionCompliancePolicy, New-RetentionComplianceRule, New-ComplianceTag

The commands on this page have not been executed by our verification runner yet.updated
tool
Microsoft Purview (Security & Compliance PowerShell)
versions
Security & Compliance PowerShell, ExchangeOnlineManagement 3.x
os
windows, linux, macos

In Security & Compliance PowerShell a retention policy is two objects: the policy (which locations it covers) and a rule (how long and what to do). Connect with Connect-IPPSSession, then create both:

powershell
New-RetentionCompliancePolicy -Name "Finance 7 years" `
  -ExchangeLocation "kitty@contoso.com","scott@contoso.com" `
  -SharePointLocation "https://contoso.sharepoint.com/sites/finance"

New-RetentionComplianceRule -Name "Finance 7 years rule" -Policy "Finance 7 years" `
  -RetentionDuration 2555 -RetentionComplianceAction KeepAndDelete -ExpirationDateOption ModificationAgeInDays

This keeps content for 2555 days (7 years) after it was last modified, then deletes it. You need a Purview role that covers retention, for example the Compliance Administrator role.

Rule values

ParameterValues
-RetentionDurationNumber of days, or Unlimited
-RetentionComplianceActionKeep, Delete, KeepAndDelete
-ExpirationDateOptionCreationAgeInDays, ModificationAgeInDays (not for Teams rules)
-PublishComplianceTagName of a retention label to publish (label policies only)

Locations

New-RetentionCompliancePolicy takes -ExchangeLocation, -SharePointLocation, -OneDriveLocation, -ModernGroupLocation (Microsoft 365 groups), -PublicFolderLocation, -TeamsChannelLocation, -TeamsChatLocation, -SkypeLocation and -AdaptiveScopeLocation. Use All for every mailbox or site:

powershell
New-RetentionCompliancePolicy -Name "Mail 3 years" -ExchangeLocation All
New-RetentionComplianceRule -Policy "Mail 3 years" -RetentionDuration 1095 -RetentionComplianceAction Keep

Teams chats and channel messages go in a policy of their own, without other locations.

Retention labels

A retention label is a ComplianceTag. Create it, then publish it with a label policy (a retention policy whose rule uses -PublishComplianceTag):

powershell
New-ComplianceTag -Name "HR Content" -RetentionAction Keep -RetentionDuration 1825 -RetentionType ModificationAgeInDays

New-RetentionCompliancePolicy -Name "Publish HR labels" -ExchangeLocation All -SharePointLocation All
New-RetentionComplianceRule -Policy "Publish HR labels" -PublishComplianceTag "HR Content"

Check and change

powershell
Get-RetentionCompliancePolicy -DistributionDetail | Format-List Name,Enabled,DistributionStatus
Get-RetentionComplianceRule -Policy "Finance 7 years" | Format-List Name,RetentionDuration,RetentionComplianceAction
Set-RetentionCompliancePolicy -Identity "Finance 7 years" -AddExchangeLocation "anna@contoso.com"
Get-ComplianceTag | Format-Table Name,RetentionAction,RetentionDuration

Use -DistributionDetail when you read DistributionStatus: without it, Microsoft notes that the status and the location properties are inaccurate. Distribution to all locations takes time after a change.

Sources

Related pages

commands · purviewConnect-IPPSSession: connect to Security & Compliance PowerShell (Purview)Connect-IPPSSession from ExchangeOnlineManagement opens Security & Compliance PowerShell for Purview cmdlets; add -EnableSearchOnlySession for eDiscovery.errors · purviewThe term 'Get-RetentionCompliancePolicy' is not recognized as the name of a cmdletPurview cmdlets such as Get-RetentionCompliancePolicy, Get-DlpCompliancePolicy and Get-Label exist only after Connect-IPPSSession, not Connect-ExchangeOnline.commands · purviewCreate a Purview DLP policy with PowerShell: New-DlpCompliancePolicy and New-DlpComplianceRuleA DLP policy needs New-DlpCompliancePolicy for locations and mode, then New-DlpComplianceRule for sensitive info types and actions. Test in simulation first.