en-US

RetentionCompliancePolicy

Applies to : Security & Compliance

This cmdlet is available only in Security & Compliance PowerShell. For more information, see Security & Compliance PowerShell.

Use the Set-RetentionCompliancePolicy cmdlet to modify existing retention policies in the Microsoft Purview compliance portal.

Note: Running this cmdlet causes a full synchronization across your organization, which is a significant operation. If you need to update multiple policies, wait until the policy distribution is successful before running the cmdlet again for the next policy. For information about the distribution status, see Get-RetentionCompliancePolicy.

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.

To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see Permissions in the Microsoft Purview compliance portal.

Note: Don't use a piped Foreach-Object command when adding or removing scope locations: "Value1","Value2",..."ValueN" | Foreach-Object {Set-RetentionCompliancePolicy -Identity "Regulation 123 Compliance" -RemoveExchangeLocation $_}.

Available cmdlets

Parameters

Name Type Default value Accepted values
RetryDistribution SwitchParameter
AddAdaptiveScopeLocation MultiValuedProperty
AddExchangeLocation MultiValuedProperty
AddExchangeLocationException MultiValuedProperty
AddModernGroupLocation MultiValuedProperty
AddModernGroupLocationException MultiValuedProperty
AddOneDriveLocation MultiValuedProperty
AddOneDriveLocationException MultiValuedProperty
AddPublicFolderLocation MultiValuedProperty
AddSharePointLocation MultiValuedProperty
AddSharePointLocationException MultiValuedProperty
AddSkypeLocation MultiValuedProperty
AddSkypeLocationException MultiValuedProperty
AddTeamsChannelLocation MultiValuedProperty
AddTeamsChannelLocationException MultiValuedProperty
AddTeamsChatLocation MultiValuedProperty
AddTeamsChatLocationException MultiValuedProperty
Applications MultiValuedProperty
Comment String
DeletedResources String
Enabled Boolean
EnforceSimulationPolicy Boolean
PolicyRBACScopes MultiValuedProperty
PolicyTemplateInfo PswsHashtable
PriorityCleanup SwitchParameter
RemoveAdaptiveScopeLocation MultiValuedProperty
RemoveExchangeLocation MultiValuedProperty
RemoveExchangeLocationException MultiValuedProperty
RemoveModernGroupLocation MultiValuedProperty
RemoveModernGroupLocationException MultiValuedProperty
RemoveOneDriveLocation MultiValuedProperty
RemoveOneDriveLocationException MultiValuedProperty
RemovePublicFolderLocation MultiValuedProperty
RemoveSharePointLocation MultiValuedProperty
RemoveSharePointLocationException MultiValuedProperty
RemoveSkypeLocation MultiValuedProperty
RemoveSkypeLocationException MultiValuedProperty
RestrictiveRetention Boolean
RemoveTeamsChannelLocation MultiValuedProperty
RemoveTeamsChannelLocationException MultiValuedProperty
RemoveTeamsChatLocation MultiValuedProperty
RemoveTeamsChatLocationException MultiValuedProperty
StartSimulation Boolean

Examples

Example 1

Set-RetentionCompliancePolicy -Identity "Regulation 123 Compliance" -AddExchangeLocation "Kitty Petersen" -AddSharePointLocation "https://contoso.sharepoint.com/sites/teams/finance" -RemovePublicFolderLocation All -Comment "Added new counsel, 9/9/14"

This example makes the following changes to the existing retention policy named "Regulation 123 Compliance":

  • Adds the mailbox for the user named Kitty Petersen.
  • Adds the SharePoint site https://contoso.sharepoint.com/sites/teams/finance.
  • Removes public folders.
  • Updates the comment.

Example 2

$stringJson = @"
[{
     'EmailAddress': '[email protected]',
     'SiteId': '9b2a8116-b9ec-4e2c-bf31-7eaa83697c4b'
}]
"@

Set-RetentionCompliancePolicy -Identity "Sales Policy" -RemoveModernGroupLocation "[email protected]" -DeletedResources $stringJson

The example removes the specified deleted Microsoft 365 Group and site from the specified policy. You identify the deleted resources using the Microsoft 365 Group email address and the related site ID.

IMPORTANT: Before you run this command, make sure you read the Caution information for the DeletedResources parameter about duplicate SMTP addresses.

Example 3

$stringJson = @"
[{
     'EmailAddress': '[email protected]',
     'SiteId': '8b2a8345-b9ec-3b6a-bf31-6eaa83697c4b'
}]
"@

Set-RetentionCompliancePolicy -Identity "Tenant Level Policy" -AddModernGroupLocationException "[email protected]" -DeletedResources $stringJson

The example excludes the specified deleted Microsoft 365 Group and site from the specified tenant level policy. You identify the deleted resources using the Microsoft 365 Group email address and the related site ID.

IMPORTANT: Before you run this command, make sure you read the Caution information for the DeletedResources parameter about duplicate SMTP addresses.

Example 4

$stringJson = @"
[{
     'EmailAddress': '[email protected]',
     'SiteId': '9b2a8116-b9ec-4e2c-bf31-7eaa83697c4b'
 },
{
     'EmailAddress': '[email protected]',
     'SiteId': '4afb7116-b9ec-4b2c-bf31-4abb83697c4b'
}]
"@

Set-RetentionCompliancePolicy -Identity "Sales Policy" -RemoveModernGroupLocation "[email protected]" -DeletedResources $stringJson

This example is similar to Example 2, except multiple deleted resources are specified.

IMPORTANT: Before you run this command, make sure you read the Caution information for the DeletedResources parameter about duplicate SMTP addresses.

Example 5

$stringJson = @"
[{
     'EmailAddress': '[email protected]'
}]
"@

Set-RetentionCompliancePolicy -Identity "Teams Chat Retention Policy" -AddTeamsChatLocationException "[email protected]" -DeletedResources $stringJson

This example excludes the specified soft-deleted mailbox or mail user from the mentioned Teams Retention Policy. You can identify the deleted resources using the mailbox or mail user's email address.

IMPORTANT: Before you run this command, make sure you read the Caution information for the DeletedResources parameter about duplicate SMTP addresses.

Example 6

$stringJson = @"
[{
     'EmailAddress': '[email protected]'
},
{
     'EmailAddress': '[email protected]'
}]
"@

Set-RetentionCompliancePolicy -Identity "Teams Chat Retention Policy" -AddTeamsChatLocationException "[email protected]", "[email protected]" -DeletedResources $stringJson

This example is similar to Example 5, except multiple deleted resources are specified.

IMPORTANT: Before you run this command, make sure you read the Caution information for the DeletedResources parameter about duplicate SMTP addresses.

Policy exclusions must remain within the supported limits for retention policies: Limits for Microsoft 365 retention policies and retention label policies

Microsoft Learn documentation