SCAppRetentionCompliancePolicy

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
Name	Key	String	The name of the app retention policy.
Applications	Write	String[]	The apps the policy applies to, in the format <LocationType>:<App>, for example User:MicrosoftTeamsChannelMessages or Group:Yammer. Separate several apps of the same location type with a comma inside a single entry.
AdaptiveScopeLocation	Write	String[]	The names of the adaptive scopes the policy applies to. An adaptive policy cannot use any other location, and a policy cannot switch between adaptive and static locations.
ExchangeLocation	Write	String[]	The mailboxes to include in a static policy, or All.
ExchangeLocationException	Write	String[]	The mailboxes to exclude when ExchangeLocation is All.
ModernGroupLocation	Write	String[]	The Microsoft 365 groups to include in a static policy, or All.
ModernGroupLocationException	Write	String[]	The Microsoft 365 groups to exclude when ModernGroupLocation is All.
Comment	Write	String	The comment of the app retention policy.
Enabled	Write	Boolean	Specifies whether the policy is enabled.
RestrictiveRetention	Write	Boolean	Specifies whether Preservation Lock is enabled for the policy. Once enabled, it cannot be turned off.
Ensure	Write	String	Specify if the app retention policy should exist.	Present, Absent
Credential	Write	PSCredential	Credentials of the Global Admin
ApplicationId	Write	String	Id of the Entra ID application to authenticate with.
TenantId	Write	String	Id of the Entra ID tenant used for authentication.
CertificateThumbprint	Write	String	Thumbprint of the Entra ID application's authentication certificate to use for authentication.
CertificatePassword	Write	PSCredential	Username can be made up to anything but password will be used for CertificatePassword
CertificatePath	Write	String	Path to certificate used in service principal usually a PFX file.
AccessTokens	Write	String[]	Access token used for authentication.

Description

This resource configures a Purview retention policy for apps, such as Teams channel messages, Viva Engage or Copilot interactions.

Please note: A policy targets either static locations (ExchangeLocation, ModernGroupLocation and their exceptions) or adaptive scopes (AdaptiveScopeLocation), but never both. Once created, it cannot be switched from one to the other location type.

Permissions

Office 365 Exchange Online

To authenticate with the Office 365 Exchange Online API, this resource requires the following permissions:

Delegated permissions

• Read

• None

• Update

• None

Application permissions

• Read

• Exchange.ManageAsApp

• Update

• Exchange.ManageAsApp

Examples

Example 1

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        SCAppRetentionCompliancePolicy 'SCAppRetentionCompliancePolicy-Example'
        {
            Name                      = "Teams Channel Messages Retention";
            Applications              = @("User:MicrosoftTeamsChannelMessages");
            Comment                   = "Retains the Teams channel messages of every user for seven years";
            Enabled                   = $true;
            ExchangeLocation          = @("All");
            ExchangeLocationException = @("meetingroom.oslo@contoso.com");
            RestrictiveRetention      = $false;
            Ensure                    = "Present";
            ApplicationId             = $ApplicationId;
            TenantId                  = $TenantId;
            CertificateThumbprint     = $CertificateThumbprint;
        }
    }
}

Example 2

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        SCAppRetentionCompliancePolicy 'SCAppRetentionCompliancePolicy-Example'
        {
            Name                      = "Teams Channel Messages Retention";
            Applications              = @("User:MicrosoftTeamsChannelMessages");
            Comment                   = "Retains the Teams channel messages of every user for ten years"; # Updated Property
            Enabled                   = $true;
            ExchangeLocation          = @("All");
            ExchangeLocationException = @("meetingroom.oslo@contoso.com");
            RestrictiveRetention      = $false;
            Ensure                    = "Present";
            ApplicationId             = $ApplicationId;
            TenantId                  = $TenantId;
            CertificateThumbprint     = $CertificateThumbprint;
        }
    }
}

Example 3

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        SCAppRetentionCompliancePolicy 'SCAppRetentionCompliancePolicy-Example'
        {
            Name                  = "Teams Channel Messages Retention";
            Ensure                = "Absent";
            ApplicationId         = $ApplicationId;
            TenantId              = $TenantId;
            CertificateThumbprint = $CertificateThumbprint;
        }
    }
}

Example 4

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        SCAppRetentionCompliancePolicy 'SCAppRetentionCompliancePolicy-Example'
        {
            Name                  = "Finance Teams Channel Messages Retention";
            Applications          = @("User:MicrosoftTeamsChannelMessages");
            AdaptiveScopeLocation = @("Finance Zurich Users");
            Comment               = "Retains the Teams channel messages of the finance department";
            Enabled               = $true;
            Ensure                = "Present";
            ApplicationId         = $ApplicationId;
            TenantId              = $TenantId;
            CertificateThumbprint = $CertificateThumbprint;
        }
    }
}