New-SPOTenantApplyFileVersionPolicyJob
Queues a job to apply the tenant-level file version policy across all sites. 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
WithExistingVersionPolicy (Default)
New-SPOTenantApplyFileVersionPolicyJob
[-TrimVersions]
[-SetVersionPolicy]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
WithVersionPolicy
New-SPOTenantApplyFileVersionPolicyJob
-VersionPolicy <SPOFileVersionPolicySettings>
[-TrimVersions]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
CollectData
New-SPOTenantApplyFileVersionPolicyJob
[-CollectVersionData]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Queues a job to apply the tenant-level file version policy across all sites. The job trims existing file versions and/or sets version policy for existing document libraries based on the version policy configured at the tenant level.
The following site types are excluded from processing:
- Read-only sites
- Locked sites
- Archived sites
- Sites with version policy broken inheritance
Note
- Versions deleted using this cmdlet will be permanently deleted and cannot be recovered from the recycle bin.
- Use
Get-SPOTenantVersionPolicyto confirm the tenant-level file version policy before running the cmdlet to make sure it matches your intended configuration. You can also use theGet-SPOTenantcmdlet and check theEnableAutoExpirationVersionTrim,MajorVersionLimit,ExpireVersionsAfterDays, andVersionPolicyFileTypeOverrideproperties. - 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.
- Only one job is allowed per tenant.
- Use
-CollectVersionDatafirst and wait for the job to complete before runningGet-SPOTenantApplyFileVersionPolicyJobImpactto estimate the impact of a policy without deleting any versions. - When
-VersionPolicyis specified, the tenant-level version policy is always updated and-SetVersionPolicyis not needed. Optionally add-TrimVersionsto also trim existing versions.
Examples
Example 1
New-SPOTenantApplyFileVersionPolicyJob -TrimVersions -SetVersionPolicy
Example 1 starts a tenant apply file version policy job to trim existing versions and set version policy for existing document libraries across all sites.
Example 2
New-SPOTenantApplyFileVersionPolicyJob -TrimVersions
Example 2 starts a tenant apply file version policy job to trim existing versions for files in document libraries across all sites.
Example 3
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
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
$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
-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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
CollectData
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SetVersionPolicy
Sets version policy for existing document libraries across all sites based on the tenant-level file version policy. The version policy applies to new versions created in these existing document libraries.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
WithExistingVersionPolicy
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TrimVersions
Trims existing versions for files in document libraries across all sites based on the tenant-level file version policy.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
WithExistingVersionPolicy
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
WithVersionPolicy
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SPOFileVersionPolicySettings |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
WithVersionPolicy
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.