diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantApplyFileVersionPolicyJobImpact.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantApplyFileVersionPolicyJobImpact.md new file mode 100644 index 000000000..4792ca4ed --- /dev/null +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantApplyFileVersionPolicyJobImpact.md @@ -0,0 +1,89 @@ +--- +external help file: Microsoft.Online.SharePoint.PowerShell.dll-Help.xml +Module Name: microsoft.online.sharepoint.powershell +online version: https://learn.microsoft.com/powershell/module/microsoft.online.sharepoint.powershell/get-spotenantapplyfileversionpolicyjobimpact +applicable: SharePoint Online +title: Get-SPOTenantApplyFileVersionPolicyJobImpact +schema: 2.0.0 +author: blarrywangmsft +ms.author: blarrywang +ms.reviewer: +--- + +# Get-SPOTenantApplyFileVersionPolicyJobImpact + +## SYNOPSIS + +Estimates how many versions would be trimmed and how much storage would be freed if a trimming job were run with the given version policy. SharePoint Advanced Management license or Copilot license is required to run this cmdlet. + +> [!NOTE] +> This feature is currently in preview and may not be available in your tenant. + +## SYNTAX + +``` +Get-SPOTenantApplyFileVersionPolicyJobImpact -VersionPolicy [] +``` + +## DESCRIPTION + +Queries the version dataset collected by a previously completed `New-SPOTenantApplyFileVersionPolicyJob -CollectVersionData` job and returns an estimated impact object showing how many versions would be trimmed and how much storage would be freed if a trimming job were run with the given version policy. + +> [!NOTE] +> - A completed job that was started with `-CollectVersionData` is required before running this cmdlet. Use `Get-SPOTenantApplyFileVersionPolicyJobProgress` to confirm the job has completed. +> - The estimate is based on a snapshot collected during the job and may not reflect changes made to the tenant after the job ran. +> - The estimate does not account for versions protected by retention policies, retention labels, or eDiscovery holds. Actual versions deleted may be fewer than estimated. + +## EXAMPLES + +### Example 1 +```powershell +$policy = Get-SPOTenantVersionPolicy | Get-SPOVersionPolicyWithChanges -MajorVersionLimit 50 +Get-SPOTenantApplyFileVersionPolicyJobImpact -VersionPolicy $policy +``` + +Estimates the impact of a trimming job run with a modified policy that limits to 50 major versions. + +## PARAMETERS + +### -VersionPolicy +The version policy to evaluate. Use `Get-SPOTenantVersionPolicy` and `Get-SPOVersionPolicyWithChanges` to build this value. + +```yaml +Type: SPOFileVersionPolicySettings +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-ProgressAction`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.Online.SharePoint.TenantAdministration.SPOTenantVersionPolicyImpact + +## NOTES + +## RELATED LINKS + +[New-SPOTenantApplyFileVersionPolicyJob](New-SPOTenantApplyFileVersionPolicyJob.md) + +[Get-SPOTenantApplyFileVersionPolicyJobProgress](Get-SPOTenantApplyFileVersionPolicyJobProgress.md) + +[Get-SPOTenantVersionPolicy](Get-SPOTenantVersionPolicy.md) + +[Get-SPOVersionPolicyWithChanges](Get-SPOVersionPolicyWithChanges.md) + +[SharePoint Advanced Management](/sharepoint/sharepoint-advanced-management-licensing) + +[Microsoft 365 Copilot](/microsoft-365/copilot/microsoft-365-copilot-licensing) diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantVersionPolicy.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantVersionPolicy.md new file mode 100644 index 000000000..96bd25f25 --- /dev/null +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOTenantVersionPolicy.md @@ -0,0 +1,61 @@ +--- +external help file: Microsoft.Online.SharePoint.PowerShell.dll-Help.xml +Module Name: microsoft.online.sharepoint.powershell +online version: https://learn.microsoft.com/powershell/module/microsoft.online.sharepoint.powershell/get-spotenantversionpolicy +applicable: SharePoint Online +title: Get-SPOTenantVersionPolicy +schema: 2.0.0 +author: blarrywangmsft +ms.author: blarrywang +ms.reviewer: +--- + +# Get-SPOTenantVersionPolicy + +## SYNOPSIS + +Returns the current tenant-level file version policy as an `SPOFileVersionPolicySettings` object. + +## SYNTAX + +``` +Get-SPOTenantVersionPolicy [] +``` + +## DESCRIPTION + +Returns the current tenant-level file version policy, including the default policy settings and any per-file-type overrides, as an `SPOFileVersionPolicySettings` object. + +The returned object is a local copy and can be modified using `Get-SPOVersionPolicyWithChanges`. Pass the modified policy to `New-SPOTenantApplyFileVersionPolicyJob` to apply it to the tenant, or to `Get-SPOTenantApplyFileVersionPolicyJobImpact` to estimate trimming impact without making changes. + +## EXAMPLES + +### Example 1 +```powershell +Get-SPOTenantVersionPolicy +``` + +Returns the current tenant-level file version policy. + +## PARAMETERS + +### CommonParameters +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-ProgressAction`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.Online.SharePoint.TenantAdministration.SPOFileVersionPolicySettings + +## NOTES + +## RELATED LINKS + +[Get-SPOVersionPolicyWithChanges](Get-SPOVersionPolicyWithChanges.md) + +[New-SPOTenantApplyFileVersionPolicyJob](New-SPOTenantApplyFileVersionPolicyJob.md) + +[Get-SPOTenantApplyFileVersionPolicyJobImpact](Get-SPOTenantApplyFileVersionPolicyJobImpact.md) diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOVersionPolicyWithChanges.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOVersionPolicyWithChanges.md new file mode 100644 index 000000000..3713a5901 --- /dev/null +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Get-SPOVersionPolicyWithChanges.md @@ -0,0 +1,196 @@ +--- +external help file: Microsoft.Online.SharePoint.PowerShell.dll-Help.xml +Module Name: microsoft.online.sharepoint.powershell +online version: https://learn.microsoft.com/powershell/module/microsoft.online.sharepoint.powershell/get-spoversionpolicywithchanges +applicable: SharePoint Online +title: Get-SPOVersionPolicyWithChanges +schema: 2.0.0 +author: blarrywangmsft +ms.author: blarrywang +ms.reviewer: +--- + +# Get-SPOVersionPolicyWithChanges + +## SYNOPSIS + +Returns a locally modified copy of a version policy. + +## SYNTAX + +### Default (Default) +``` +Get-SPOVersionPolicyWithChanges -VersionPolicy [-MajorVersionLimit ] + [-ExpireVersionsAfterDays ] [-EnableAutoExpirationVersionTrim ] [] +``` + +### FileType +``` +Get-SPOVersionPolicyWithChanges -VersionPolicy -FileType + [-MajorVersionLimit ] [-ExpireVersionsAfterDays ] + [-EnableAutoExpirationVersionTrim ] [] +``` + +### FileTypeRemove +``` +Get-SPOVersionPolicyWithChanges -VersionPolicy -FileType [-Remove] + [] +``` + +## DESCRIPTION + +Returns a modified copy of the given version policy. This cmdlet is intended to be used in a pipeline with `Get-SPOTenantVersionPolicy` to build a modified policy that can then be passed to `New-SPOTenantApplyFileVersionPolicyJob` or `Get-SPOTenantApplyFileVersionPolicyJobImpact`. + +When `-FileType` is omitted, the default policy settings are modified. When `-FileType` is specified, the per-file-type override for that type is created or updated. For supported file type names, see [File type version limits in SharePoint](/sharepoint/file-type-version-limits). + +Use `-Remove` with `-FileType` to delete a per-file-type override. + +## EXAMPLES + +### Example 1 +```powershell +Get-SPOTenantVersionPolicy | Get-SPOVersionPolicyWithChanges -MajorVersionLimit 100 +``` + +Retrieves the current tenant version policy and returns a copy with the default major version limit changed to 100. + +### Example 2 +```powershell +Get-SPOTenantVersionPolicy | Get-SPOVersionPolicyWithChanges -FileType "video" -MajorVersionLimit 50 -ExpireVersionsAfterDays 180 +``` + +Retrieves the current tenant version policy and returns a copy with a per-file-type override for `video` files that limits to 50 major versions and expires versions after 180 days. + +### Example 3 +```powershell +Get-SPOTenantVersionPolicy | Get-SPOVersionPolicyWithChanges -FileType "video" -Remove +``` + +Retrieves the current tenant version policy and returns a copy with the `video` file type override removed, so `video` files will fall back to the default policy. + +## PARAMETERS + +### -EnableAutoExpirationVersionTrim +When `$true`, uses automatic expiration, where Microsoft manages the expiration schedule. When `$false`, uses the manual expiration schedule defined by `-MajorVersionLimit` and `-ExpireVersionsAfterDays`. + +When `EnableAutoExpirationVersionTrim` is `$true`, `MajorVersionLimit` is always 500 and `ExpireVersionsAfterDays` is always 30. As a result, switching `-EnableAutoExpirationVersionTrim` from `$false` to `$true` sets `MajorVersionLimit` to 500 and `ExpireVersionsAfterDays` to 30. + +Applies to the default policy or the file type specified by `-FileType`. + +```yaml +Type: Boolean +Parameter Sets: Default, FileType +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExpireVersionsAfterDays +The number of days after which versions expire. Set to `0` to disable time-based expiration. + +Specifying `-ExpireVersionsAfterDays` when the policy has `EnableAutoExpirationVersionTrim` set to `$true` throws an error. + +Applies to the default policy or the file type specified by `-FileType`. + +```yaml +Type: Int32 +Parameter Sets: Default, FileType +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FileType +The file type name whose per-file-type override should be created, updated, or removed. Supported values are `"audio"`, `"video"`, and `"outlookspst"`. Omit this parameter to modify the default policy. For more information, see [File type version limits in SharePoint](/sharepoint/file-type-version-limits). + +```yaml +Type: String +Parameter Sets: FileType, FileTypeRemove +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MajorVersionLimit +The maximum number of major versions to retain. + +Specifying `-ExpireVersionsAfterDays` when the policy has `EnableAutoExpirationVersionTrim` set to `$true` throws an error. + +Applies to the default policy or the file type specified by `-FileType`. + +```yaml +Type: Int32 +Parameter Sets: Default, FileType +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Remove +Removes the per-file-type override identified by `-FileType`. `-FileType` is required when this switch is specified. + +```yaml +Type: SwitchParameter +Parameter Sets: FileTypeRemove +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VersionPolicy +The version policy object to modify, typically piped from `Get-SPOTenantVersionPolicy`. The original object is not modified; a new object with the requested changes is returned. + +```yaml +Type: SPOFileVersionPolicySettings +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-ProgressAction`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.Online.SharePoint.TenantAdministration.SPOFileVersionPolicySettings + +## OUTPUTS + +### Microsoft.Online.SharePoint.TenantAdministration.SPOFileVersionPolicySettings + +## NOTES + +Always review the returned policy object before passing it to `New-SPOTenantApplyFileVersionPolicyJob` or `Get-SPOTenantApplyFileVersionPolicyJobImpact` to confirm it reflects the intended configuration. + +## RELATED LINKS + +[Get-SPOTenantVersionPolicy](Get-SPOTenantVersionPolicy.md) + +[New-SPOTenantApplyFileVersionPolicyJob](New-SPOTenantApplyFileVersionPolicyJob.md) + +[Get-SPOTenantApplyFileVersionPolicyJobImpact](Get-SPOTenantApplyFileVersionPolicyJobImpact.md) diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Microsoft.Online.SharePoint.PowerShell.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Microsoft.Online.SharePoint.PowerShell.md index 0a54ee0f6..c1e5830ee 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Microsoft.Online.SharePoint.PowerShell.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Microsoft.Online.SharePoint.PowerShell.md @@ -371,6 +371,9 @@ Get the structural navigation caching state for a web. ### [Get-SPOTenant](Get-SPOTenant.md) Returns SharePoint Online organization properties. +### [Get-SPOTenantApplyFileVersionPolicyJobImpact](Get-SPOTenantApplyFileVersionPolicyJobImpact.md) +Estimates how many versions would be trimmed and how much storage would be freed if a trimming job were run with the given version policy. SharePoint Advanced Management license or Copilot license is required to run this cmdlet. + ### [Get-SPOTenantApplyFileVersionPolicyJobProgress](Get-SPOTenantApplyFileVersionPolicyJobProgress.md) Gets the status for a tenant apply file version policy job. SharePoint Advanced Management license or Copilot license is required to run this cmdlet. @@ -413,6 +416,9 @@ Returns the current configuration status. ### [Get-SPOTenantTaxonomyReplicationParameters](Get-SPOTenantTaxonomyReplicationParameters.md) Get the replication parameters to manage Multi-Geo taxonomy replication. +### [Get-SPOTenantVersionPolicy](Get-SPOTenantVersionPolicy.md) +Returns the current tenant-level file version policy. + ### [Get-SPOTheme](Get-SPOTheme.md) Returns one or all theme settings from the tenant. @@ -431,6 +437,9 @@ This cmdlet allows SharePoint administrators to check the status of a user or si ### [Get-SPOUserOneDriveLocation](Get-SPOUserOneDriveLocation.md) This cmdlet will return the user principal name, current location, and corresponding OneDrive for Business url, and the site ID. This cmdlet only supports Multi-Geo OneDrive sites. +### [Get-SPOVersionPolicyWithChanges](Get-SPOVersionPolicyWithChanges.md) +Returns a locally modified copy of a version policy. + ### [Get-SPOWebTemplate](Get-SPOWebTemplate.md) Displays all site templates that match the given identity. diff --git a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOTenantApplyFileVersionPolicyJob.md b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOTenantApplyFileVersionPolicyJob.md index 181e44c7a..73c8b30d9 100644 --- a/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOTenantApplyFileVersionPolicyJob.md +++ b/sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/New-SPOTenantApplyFileVersionPolicyJob.md @@ -22,8 +22,21 @@ Queues a job to apply the tenant-level file version policy across all sites. Sha ## SYNTAX +### WithExistingVersionPolicy (Default) ``` -New-SPOTenantApplyFileVersionPolicyJob [-TrimVersions] [-SetVersionPolicy] [-WhatIf] [-Confirm] [] +New-SPOTenantApplyFileVersionPolicyJob [-TrimVersions] [-SetVersionPolicy] [-WhatIf] [-Confirm] + [] +``` + +### WithVersionPolicy +``` +New-SPOTenantApplyFileVersionPolicyJob [-TrimVersions] -VersionPolicy + [-WhatIf] [-Confirm] [] +``` + +### CollectData +``` +New-SPOTenantApplyFileVersionPolicyJob [-CollectVersionData] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -39,9 +52,11 @@ The following site types are excluded from processing: > [!NOTE] > - Versions deleted using this cmdlet will be permanently deleted and cannot be recovered from the recycle bin. -> - Use `Get-SPOTenant` cmdlet and the `EnableAutoExpirationVersionTrim`, `MajorVersionLimit`, `ExpireVersionsAfterDays` and `VersionPolicyFileTypeOverride` properties to confirm the tenant-level file version policy before running the cmdlet to make sure it matches your intended configuration. +> - Use `Get-SPOTenantVersionPolicy` to confirm the tenant-level file version policy before running the cmdlet to make sure it matches your intended configuration. You can also use the `Get-SPOTenant` cmdlet and check the `EnableAutoExpirationVersionTrim`, `MajorVersionLimit`, `ExpireVersionsAfterDays`, and `VersionPolicyFileTypeOverride` properties. > - If the tenant-level version policy changes while the job is in progress, the job will apply the updated policy to the remaining sites that have not yet been processed. Sites that were already processed will not be re-evaluated or updated. -> - Allow only one job per tenant. +> - Only one job is allowed per tenant. +> - Use `-CollectVersionData` first and wait for the job to complete before running `Get-SPOTenantApplyFileVersionPolicyJobImpact` to estimate the impact of a policy without deleting any versions. +> - When `-VersionPolicy` is specified, the tenant-level version policy is always updated and `-SetVersionPolicy` is not needed. Optionally add `-TrimVersions` to also trim existing versions. ## EXAMPLES @@ -66,6 +81,21 @@ New-SPOTenantApplyFileVersionPolicyJob -SetVersionPolicy Example 3 starts a tenant apply file version policy job to set version policy for existing document libraries across all sites. +### Example 4 +```powershell +New-SPOTenantApplyFileVersionPolicyJob -CollectVersionData +``` + +Example 4 starts a job to collect version data across all sites. Once the job completes, use `Get-SPOTenantApplyFileVersionPolicyJobImpact` to estimate the impact of a version policy without deleting any versions. + +### Example 5 +```powershell +$policy = Get-SPOTenantVersionPolicy | Get-SPOVersionPolicyWithChanges -MajorVersionLimit 100 +New-SPOTenantApplyFileVersionPolicyJob -TrimVersions -VersionPolicy $policy +``` + +Example 5 retrieves the current tenant version policy, modifies the major version limit to 100 locally, then starts a trim job using that modified policy. The tenant-level policy is updated before the job begins. + ## PARAMETERS ### -Confirm @@ -88,7 +118,7 @@ Sets version policy for existing document libraries across all sites based on th ```yaml Type: SwitchParameter -Parameter Sets: (All) +Parameter Sets: WithExistingVersionPolicy Aliases: Required: False @@ -98,12 +128,27 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -CollectVersionData +Collects version data across all sites for use with `Get-SPOTenantApplyFileVersionPolicyJobImpact`. Use this switch to run a data-collection pass before deciding whether and how to trim versions. The job does not delete any versions. Cannot be combined with `-VersionPolicy` or `-SetVersionPolicy`. + +```yaml +Type: SwitchParameter +Parameter Sets: CollectData +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -TrimVersions Trims existing versions for files in document libraries across all sites based on the tenant-level file version policy. ```yaml Type: SwitchParameter -Parameter Sets: (All) +Parameter Sets: WithExistingVersionPolicy, WithVersionPolicy Aliases: Required: False @@ -113,6 +158,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -VersionPolicy +The new version policy to apply to the tenant before starting the job. When specified, the tenant-level policy is always updated and the version policy is propagated to all sites. Optionally combine with `-TrimVersions` to also trim existing versions. + +Use `Get-SPOTenantVersionPolicy` and `Get-SPOVersionPolicyWithChanges` to build this value. + +```yaml +Type: SPOFileVersionPolicySettings +Parameter Sets: WithVersionPolicy +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -145,8 +207,14 @@ This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVar [Get-SPOTenantApplyFileVersionPolicyJobProgress](Get-SPOTenantApplyFileVersionPolicyJobProgress.md) +[Get-SPOTenantApplyFileVersionPolicyJobImpact](Get-SPOTenantApplyFileVersionPolicyJobImpact.md) + [Remove-SPOTenantApplyFileVersionPolicyJob](Remove-SPOTenantApplyFileVersionPolicyJob.md) +[Get-SPOTenantVersionPolicy](Get-SPOTenantVersionPolicy.md) + +[Get-SPOVersionPolicyWithChanges](Get-SPOVersionPolicyWithChanges.md) + [Get-SPOTenant](Get-SPOTenant.md) [SharePoint Advanced Management](/sharepoint/sharepoint-advanced-management-licensing)