From 832c31dd6291a59da1813094ceaaa76c1eb556ad Mon Sep 17 00:00:00 2001 From: Hector Mota Date: Thu, 3 Sep 2026 16:42:02 -0700 Subject: [PATCH 1/2] Update File Archive Policy cmdlets for OneDrive support Documents the AllODBSites policy type and the site exclusion model, and corrects guidance for the file type criteria parameters. Add-SPOSiteToFileArchivePolicy: - Document the new -Exclude switch. - Explain that inclusions are only valid for SelectedSites policies and exclusions only for AllSites/AllODBSites policies. - Add an exclusion example and note the 1,000 site limit per policy. New-SPOFileArchivePolicy / Set-SPOFileArchivePolicy: - Add AllODBSites to the accepted values for -PolicyType. - Document the new -FileTypeExclusionCriteria parameter. - Note that file type filtering is not implemented in the current preview: supplying -FileTypeCriteria or -FileTypeExclusionCriteria returns an error. The previous New-SPOFileArchivePolicy example passed -FileTypeCriteria and would have failed, so it has been replaced. - Set-SPOFileArchivePolicy: correct the activation rule to include AllODBSites. Get-SPOFileArchivePolicySites: - Clarify that the cmdlet returns included sites for a SelectedSites policy and excluded sites for an AllSites/AllODBSites policy. Remove-SPOSiteToFileArchivePolicy: - Clarify that it removes either an inclusion or an exclusion, and document the guard against removing the last site from an active SelectedSites policy. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../Add-SPOSiteToFileArchivePolicy.md | 38 ++++++++++++-- .../Get-SPOFileArchivePolicySites.md | 4 +- .../New-SPOFileArchivePolicy.md | 51 ++++++++++++++++--- .../Remove-SPOSiteToFileArchivePolicy.md | 6 ++- .../Set-SPOFileArchivePolicy.md | 38 +++++++++++--- 5 files changed, 120 insertions(+), 17 deletions(-) diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Add-SPOSiteToFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Add-SPOSiteToFileArchivePolicy.md index 9c6dac7ea..d617fdae1 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Add-SPOSiteToFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Add-SPOSiteToFileArchivePolicy.md @@ -19,12 +19,18 @@ Adds a site to a file archive policy. ## SYNTAX ``` -Add-SPOSiteToFileArchivePolicy -PolicyId -Site [] +Add-SPOSiteToFileArchivePolicy -PolicyId -Site [-Exclude] [] ``` ## DESCRIPTION -This cmdlet adds a site to an existing file archive policy that has a PolicyType of `SelectedSites`. The site must exist and be eligible for archiving. At least one site must be added before a `SelectedSites` policy can be activated. +This cmdlet adds a site to an existing file archive policy, either as an inclusion or as an exclusion. + +By default, the site is added as an inclusion. Inclusions are only valid for a policy whose PolicyType is `SelectedSites`, and at least one site must be added before such a policy can be activated. Adding an inclusion to an `AllSites` or `AllODBSites` policy returns an error. + +When you use the `-Exclude` parameter, the site is added as an exclusion and is exempted from the policy when it runs. Exclusions are only valid for a policy whose PolicyType is `AllSites` or `AllODBSites`. Adding an exclusion to a `SelectedSites` policy returns an error. + +The site must exist and be eligible for archiving. A single policy can contain a maximum of 1,000 sites, counting inclusions and exclusions together. > [!NOTE] > This cmdlet is part of the file archive policies feature which is currently in preview. @@ -37,10 +43,36 @@ This cmdlet adds a site to an existing file archive policy that has a PolicyType Add-SPOSiteToFileArchivePolicy -PolicyId "a1b2c3d4-e5f6-7890-abcd-ef1234567890" -Site "https://contoso.sharepoint.com/sites/marketing" ``` -Adds the marketing site to the specified file archive policy. +Adds the marketing site to the specified `SelectedSites` file archive policy, so that the policy applies to it. + +### Example 2 + +```powershell +Add-SPOSiteToFileArchivePolicy -PolicyId "a1b2c3d4-e5f6-7890-abcd-ef1234567890" -Site "https://contoso-my.sharepoint.com/personal/user_contoso_com" -Exclude +``` + +Adds a OneDrive for Business site to the specified `AllODBSites` policy as an exclusion, exempting it from archiving while the policy continues to apply to every other OneDrive site in the tenant. ## PARAMETERS +### -Exclude + +Adds the site as an exclusion instead of an inclusion, exempting it from the policy when the policy runs. + +Use this parameter only with a policy whose PolicyType is `AllSites` or `AllODBSites`. Omit it when adding sites to a `SelectedSites` policy. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -PolicyId Specifies the unique identifier (GUID) of the policy to add the site to. diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOFileArchivePolicySites.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOFileArchivePolicySites.md index f10a0fa2e..ea2256de8 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOFileArchivePolicySites.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOFileArchivePolicySites.md @@ -24,7 +24,9 @@ Get-SPOFileArchivePolicySites -PolicyId [] ## DESCRIPTION -This cmdlet retrieves the list of sites that have been added to a file archive policy. This is applicable to policies with a PolicyType of `SelectedSites`. +This cmdlet retrieves the list of sites that have been added to a file archive policy. + +For a policy with a PolicyType of `SelectedSites`, this returns the included sites that the policy applies to. For a policy with a PolicyType of `AllSites` or `AllODBSites`, this returns the excluded sites that are exempt from the policy. > [!NOTE] > This cmdlet is part of the file archive policies feature which is currently in preview. diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md index daa34c51d..f50db8c4e 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md @@ -20,13 +20,16 @@ Creates a new file archive policy for the tenant. ``` New-SPOFileArchivePolicy [-Name ] -PolicyType [-LastAccessDateCriteria ] - [-FileTypeCriteria ] [-IsWhatIfMode ] [] + [-FileTypeCriteria ] [-FileTypeExclusionCriteria ] [-IsWhatIfMode ] + [] ``` ## DESCRIPTION This cmdlet creates a new file archive policy for the connected SharePoint Online tenant. A file archive policy defines the criteria under which files are automatically archived based on their last access date. The policy is created in an Inactive state and must be activated using `Set-SPOFileArchivePolicy` with `-State Active` before it takes effect. +Use `-PolicyType` to choose the scope of the policy: all SharePoint sites in the tenant (`AllSites`), all OneDrive for Business sites in the tenant (`AllODBSites`), or only the sites you explicitly add (`SelectedSites`). + > [!NOTE] > This cmdlet is part of the file archive policies feature which is currently in preview. @@ -43,13 +46,21 @@ Creates a new file archive policy named "ArchiveAll" that targets all sites in t ### Example 2 ```powershell -New-SPOFileArchivePolicy -PolicyType "SelectedSites" -Name "ArchiveMarketing" -LastAccessDateCriteria 12 -FileTypeCriteria ".docx", ".pptx", ".xlsx" +New-SPOFileArchivePolicy -PolicyType "SelectedSites" -Name "ArchiveMarketing" -LastAccessDateCriteria 12 ``` -Creates a new file archive policy named "ArchiveMarketing" that targets selected sites, archives files not accessed in the last 12 months, and only applies to .docx, .pptx, and .xlsx file types. +Creates a new file archive policy named "ArchiveMarketing" that targets only the sites you add with `Add-SPOSiteToFileArchivePolicy`, and archives files not accessed in the last 12 months. ### Example 3 +```powershell +New-SPOFileArchivePolicy -PolicyType "AllODBSites" -Name "ArchiveOneDrive" +``` + +Creates a new file archive policy named "ArchiveOneDrive" that targets all OneDrive for Business sites in the tenant. To exempt individual OneDrive sites, add them as exclusions with `Add-SPOSiteToFileArchivePolicy` and the `-Exclude` parameter. + +### Example 4 + ```powershell New-SPOFileArchivePolicy -PolicyType "AllSites" -IsWhatIfMode $true ``` @@ -60,7 +71,29 @@ Creates a new file archive policy in `WhatIf` mode. When the policy runs, it wil ### -FileTypeCriteria -Specifies an array of file extensions to include in the policy. Only files matching the specified extensions will be considered for archiving. Use the dot-prefixed format. If not specified, all file types are included. +Specifies an array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). When omitted, all file types are included. + +> [!NOTE] +> File type filtering isn't implemented in the current preview. Supplying this parameter returns the error "Updating file type criteria is not supported. Please remove and recreate the policy." Omit the parameter to create the policy with all file types included. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FileTypeExclusionCriteria + +Specifies an array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). When omitted, no file types are excluded. + +> [!NOTE] +> File type filtering isn't implemented in the current preview. Supplying this parameter returns the error "Updating file type exclusion criteria is not supported. Please remove and recreate the policy." Omit the parameter to create the policy with no file type exclusions. ```yaml Type: String[] @@ -127,13 +160,19 @@ Accept wildcard characters: False ### -PolicyType -Specifies whether the policy targets all sites in the tenant or only selected sites. Accepted values are `AllSites` and `SelectedSites`. If `SelectedSites` is chosen, you must add at least one site using `Add-SPOSiteToFileArchivePolicy` before the policy can be activated. +Specifies the scope of the policy. Accepted values are: + +- `AllSites`: The policy applies to all SharePoint sites in the tenant. +- `AllODBSites`: The policy applies to all OneDrive for Business sites in the tenant. +- `SelectedSites`: The policy applies only to the sites you explicitly add to it. + +If you choose `SelectedSites`, you must add at least one site using `Add-SPOSiteToFileArchivePolicy` before the policy can be activated. If you choose `AllSites` or `AllODBSites`, you can optionally exempt individual sites by adding them with `Add-SPOSiteToFileArchivePolicy` and the `-Exclude` parameter. ```yaml Type: SPOFileArchivePolicyType Parameter Sets: (All) Aliases: -Accepted values: AllSites, SelectedSites +Accepted values: AllSites, SelectedSites, AllODBSites Required: True Position: Named diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Remove-SPOSiteToFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Remove-SPOSiteToFileArchivePolicy.md index 39f4a82e9..cfecb5973 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Remove-SPOSiteToFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Remove-SPOSiteToFileArchivePolicy.md @@ -24,7 +24,11 @@ Remove-SPOSiteToFileArchivePolicy -PolicyId -Site [ [!NOTE] > This cmdlet is part of the file archive policies feature which is currently in preview. diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md index e02a53161..4d1cb9d5f 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md @@ -20,13 +20,13 @@ Updates an existing file archive policy. ``` Set-SPOFileArchivePolicy -PolicyId [-Name ] [-PolicyType ] - [-LastAccessDateCriteria ] [-FileTypeCriteria ] [-IsWhatIfMode ] [-State ] - [] + [-LastAccessDateCriteria ] [-FileTypeCriteria ] [-FileTypeExclusionCriteria ] + [-IsWhatIfMode ] [-State ] [] ``` ## DESCRIPTION -This cmdlet updates the properties of an existing file archive policy. Only the parameters that are specified will be updated; all other properties remain unchanged. You cannot set the State to `Active` unless the PolicyType is `AllSites` or at least one site has been added to the policy using `Add-SPOSiteToFileArchivePolicy`. +This cmdlet updates the properties of an existing file archive policy. Only the parameters that are specified will be updated; all other properties remain unchanged. You cannot set the State to `Active` unless the PolicyType is `AllSites` or `AllODBSites`, or at least one site has been added to the policy using `Add-SPOSiteToFileArchivePolicy`. > [!NOTE] > This cmdlet is part of the file archive policies feature which is currently in preview. @@ -61,7 +61,29 @@ Enables `WhatIf` mode on the specified policy. Future policy runs will report el ### -FileTypeCriteria -Specifies an updated array of file extensions to include in the policy. Only files matching the specified extensions will be considered for archiving. Use the dot-prefixed format. Set to `$null` to include all file types. +Specifies an updated array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). + +> [!NOTE] +> File type filtering isn't implemented in the current preview, and the inclusion list can't be changed after a policy is created. Supplying this parameter returns the error "Updating file type criteria is not supported. Please remove and recreate the policy to change this setting." + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FileTypeExclusionCriteria + +Specifies an updated array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). + +> [!NOTE] +> File type filtering isn't implemented in the current preview, and the exclusion list can't be changed after a policy is created. Supplying this parameter returns the error "Updating file type exclusion criteria is not supported. Please remove and recreate the policy to change this setting." ```yaml Type: String[] @@ -141,13 +163,17 @@ Accept wildcard characters: False ### -PolicyType -Specifies the updated policy type. Accepted values are `AllSites` (targets all sites in the tenant) and `SelectedSites` (targets only sites explicitly added to the policy). +Specifies the updated policy type. Accepted values are: + +- `AllSites`: The policy applies to all SharePoint sites in the tenant. +- `AllODBSites`: The policy applies to all OneDrive for Business sites in the tenant. +- `SelectedSites`: The policy applies only to the sites you explicitly add to it. ```yaml Type: SPOFileArchivePolicyType Parameter Sets: (All) Aliases: -Accepted values: AllSites, SelectedSites +Accepted values: AllSites, SelectedSites, AllODBSites Required: False Position: Named From ff37af9091ba210251b1a9002016751a55c4c776 Mon Sep 17 00:00:00 2001 From: Hector Mota Date: Fri, 4 Sep 2026 11:26:12 -0700 Subject: [PATCH 2/2] Remove backend implementation notes from file type criteria parameters Implementation status of the service backend doesn't belong in the public cmdlet reference. The -FileTypeCriteria and -FileTypeExclusionCriteria parameters are now described in terms of their intended behavior only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../New-SPOFileArchivePolicy.md | 10 ++-------- .../Set-SPOFileArchivePolicy.md | 10 ++-------- 2 files changed, 4 insertions(+), 16 deletions(-) diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md index f50db8c4e..6d28fca2d 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOFileArchivePolicy.md @@ -71,10 +71,7 @@ Creates a new file archive policy in `WhatIf` mode. When the policy runs, it wil ### -FileTypeCriteria -Specifies an array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). When omitted, all file types are included. - -> [!NOTE] -> File type filtering isn't implemented in the current preview. Supplying this parameter returns the error "Updating file type criteria is not supported. Please remove and recreate the policy." Omit the parameter to create the policy with all file types included. +Specifies an array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). Only files matching the specified extensions are considered for archiving. When omitted, all file types are included. ```yaml Type: String[] @@ -90,10 +87,7 @@ Accept wildcard characters: False ### -FileTypeExclusionCriteria -Specifies an array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). When omitted, no file types are excluded. - -> [!NOTE] -> File type filtering isn't implemented in the current preview. Supplying this parameter returns the error "Updating file type exclusion criteria is not supported. Please remove and recreate the policy." Omit the parameter to create the policy with no file type exclusions. +Specifies an array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). Files matching the specified extensions aren't archived. When omitted, no file types are excluded. ```yaml Type: String[] diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md index 4d1cb9d5f..6764086a4 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Set-SPOFileArchivePolicy.md @@ -61,10 +61,7 @@ Enables `WhatIf` mode on the specified policy. Future policy runs will report el ### -FileTypeCriteria -Specifies an updated array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). - -> [!NOTE] -> File type filtering isn't implemented in the current preview, and the inclusion list can't be changed after a policy is created. Supplying this parameter returns the error "Updating file type criteria is not supported. Please remove and recreate the policy to change this setting." +Specifies an updated array of file extensions to include in the policy, in dot-prefixed format (for example, `.docx`). Only files matching the specified extensions are considered for archiving. ```yaml Type: String[] @@ -80,10 +77,7 @@ Accept wildcard characters: False ### -FileTypeExclusionCriteria -Specifies an updated array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). - -> [!NOTE] -> File type filtering isn't implemented in the current preview, and the exclusion list can't be changed after a policy is created. Supplying this parameter returns the error "Updating file type exclusion criteria is not supported. Please remove and recreate the policy to change this setting." +Specifies an updated array of file extensions to exclude from the policy, in dot-prefixed format (for example, `.docx`). Files matching the specified extensions aren't archived. ```yaml Type: String[]