Enhanced Version Controls/Intelligent Versioning Trim with PowerShell

Microsoft has introduced Enhanced Version Controls, previously known as Intelligent Versioning, as part of its public preview in May 2024. This feature, detailed in the Microsoft 365 Roadmap 145802, aims to help administrators manage file versions more effectively, reducing storage costs by removing unnecessary versions.

Extract from the Roadmap

We are introducing new version controls that help tenant and site admins or document library owners reduce the storage footprint driven by low value file versions. Today, document library owners can set count-based version limits at the individual document library level. With the upcoming changes, tenant and site admins or document library owners will have two version history settings: 1) Automatic mode that intelligently expires new and existing version based on their age and restore probability, and 2) Manual mode that will allow admins to set time-based version expiration and count limits on new and existing versions. These controls enable admins to set an appropriate level of recoverability and auditability for their organization balanced with storage usage considerations. Version history limits and management also apply to OneDrive for Business.

This feature is particularly useful for reducing storage costs by eliminating unnecessary file versions. Versioning is automatically enabled in libraries, and combined with auto-save features, the number of versions per file can be substantial.

For more insights on storage usage by versions, refer to the report from the post The Hidden Connection Between SharePoint File Versioning and Storage Management by Nikki Chapple.

Enabling the preview

To enable the preview, use PowerShell with the EnableVersionExpirationSetting parameter.

PnP PowerShell

Set-PnPTenant -EnableVersionExpirationSetting $true

SPO PowerShell

Set-SPOTenant -EnableVersionExpirationSetting $true

Script to set Enhanced Version Controls/Intelligent Versioning

PnP PowerShell at Site Level

set-pnptenantsite -Identity https://reshmeeauckloo.sharepoint.com/sites/Company311 -EnableAutoExpirationVersionTrim  $false  -ExpireVersionsAfterDays 50

If you get the message Set-PnPTenantSite: EnableVersionExpirationSetting is disabled. Please run Set-SPOTenant to enable file version expiration feature, ensure the feature is enabled the using previous step.

If you get the message Set-PnPTenantSite: You must specify a value for "EnableAutoExpirationVersionTrim" if "ExpireVersionsAfterDays", "MajorVersionLimit", "MajorWithMinorVersionsLimit" and "ApplyToNewDocumentLibraries are specified,ensure to specify the parameter EnableAutoExpirationVersionTrim .

SPO PowerShell version

Set-SPOSite -Identity https://reshmeeauckloo.sharepoint.com/sites/Company311 -EnableAutoExpirationVersionTrim  $false  -ExpireVersionsAfterDays 50

For both PnP PowerShell and SPO PowerShell flavours, you will be prompted with the following message

Prompt to confirm enabling setting at site

Script to Get Version Report

Refer to the report from post Getting Storage Metrics for a SharePoint site to get an understanding of how storage space might be used by versions.

Altenatively generate the report using the following cmdlet.

Site Level

New-PnPSiteFileVersionExpirationReportJob  -ReportUrl https://reshmeeauckloo.sharepoint.com/sites/Company311/Shared%20Documents/SiteVersionReport.csv

Library Level

New-PnPLibraryFileVersionExpirationReportJob -Identity "Documents" -ReportUrl https://reshmeeauckloo.sharepoint.com/sites/Company311/Shared%20Documents/VersionReport.csv

Output

Script to run to generate report

Results of the report

Site version report

What-If Analysis

Refer to the following posts to learn more about What-If Analysis

Tutorial: Run ‘What-If’ analysis on version storage report file (Preview)

Tutorial: Generate and analyze version usage report for SharePoint site (Preview)

Script to Trim Version

Setting the enhanced controls does not automatically remove existing versions. The following script can help trim versions. Note that deleted versions are permanently removed and cannot be recovered. The script can be run at the library or site level with options to specify different parameter values.

param (
    [string]$siteURL,
    [string]$library,
    [int]$deleteOlderThanDays,
    [int]$majorVersionsToKeep,
    [int]$majorWithMinorVersionsToKeep,
    [switch]$Automatic
)

if (-not $siteURL) {
    $siteURL = Read-Host "Please enter Site URL"
}

if (-not $library) {
    $library = Read-Host "Please enter the library name, i.e. Documents or leave blank for the whole site"
}

if (-not $Automatic) {
    if (-not $deleteOlderThanDays) {
        $deleteOlderThanDays = Read-Host "Enter the number of days to keep versions for or leave blank or 0 to keep major minor versions"
        if ($deleteOlderThanDays -eq "") {
            $deleteOlderThanDays = 0
        }
        if ($deleteOlderThanDays -eq 0) {
            $majorVersionsToKeep = Read-Host "Enter the number of major versions to keep"
            $majorWithMinorVersionsToKeep = Read-Host "Enter the number of major versions with minor versions to keep"
        }
    } else {
        Write-Host "DeleteOlderThanDays is specified. Skipping prompts for major versions to keep."
    }
} else {
    Write-Host "Automatic is specified. Skipping other prompts."
}

Connect-PnPOnline -url $siteURL -Interactive

if ($library) {
    if ($Automatic) {
        New-PnPLibraryFileVersionBatchDeleteJob -Identity $library -Automatic -force
    } else {
        if ($deleteOlderThanDays -and $deleteOlderThanDays -gt 0) {
            New-PnPLibraryFileVersionBatchDeleteJob -Identity $library -deletebeforedays $deleteOlderThanDays -force
        } else {
            New-PnPLibraryFileVersionBatchDeleteJob -Identity $library -MajorVersionLimit $majorVersionsToKeep -MajorWithMinorVersionsLimit $majorWithMinorVersionsToKeep -force
        }
    }
    Get-PnPLibraryFileVersionBatchDeleteJobStatus -Identity $library
} else {
    if ($Automatic) {
        New-PnPSiteFileVersionBatchDeleteJob -Automatic -force
    } else {
        if ($deleteOlderThanDays) {
            New-PnPSiteFileVersionBatchDeleteJob -deletebeforedays $deleteOlderThanDays -force
        } else {
            New-PnPSiteFileVersionBatchDeleteJob -MajorVersionLimit $majorVersionsToKeep -MajorWithMinorVersionsLimit $majorWithMinorVersionsToKeep -force
        }
    }
    Get-PnPSiteFileVersionBatchDeleteJobStatus
}

Parameters handling and Prompts

The script checks whether the necessary parameters were provided. If not, it prompts the user to input them:

  • $siteURL and $library:

If $siteURL is not provided, the script prompts the user to enter the site URL. Similarly, if $library is not provided, the script asks the user to enter the library name (e.g., “Documents”). If left blank, the script will target the whole site.

  • $deleteOlderThanDays, $majorVersionsToKeep, $majorWithMinorVersionsToKeep:

    • If the $Automatic switch is not set, and $deleteOlderThanDays is not provided, the script asks the user for the number of days to keep versions.
    • If the user provides 0 or leaves it blank, the script then prompts for the number of major versions to keep and the number of major versions with their minor versions to retain.

  • $Automatic: If the $automatic switch is set, the parameters $deleteOlderThanDays, $majorVersionsToKeep, $majorWithMinorVersionsToKeep are not required , hence does not prompt for those

Script Version Trimming

  • If a specific library is provided:
    • If the $Automatic switch is set, it runs the New-PnPLibraryFileVersionBatchDeleteJob cmdlet with the -Automatic parameter.
    • If $deleteOlderThanDays is specified and greater than 0, it runs the New-PnPLibraryFileVersionBatchDeleteJob cmdlet with the -deletebeforedays parameter.
    • Otherwise, it runs the New-PnPLibraryFileVersionBatchDeleteJob cmdlet with the -MajorVersionLimit and -MajorWithMinorVersionsLimit parameters.
    • It then checks the status of the batch delete job using the Get-PnPLibraryFileVersionBatchDeleteJobStatus cmdlet.
  • If no specific library is provided:
    • If the $Automatic switch is set, it runs the New-PnPSiteFileVersionBatchDeleteJob cmdlet with the -Automatic parameter.
    • If $deleteOlderThanDays is specified, it runs the New-PnPSiteFileVersionBatchDeleteJob cmdlet with the -deletebeforedays parameter.
    • Otherwise, it runs the New-PnPSiteFileVersionBatchDeleteJob cmdlet with the -MajorVersionLimit and -MajorWithMinorVersionsLimit parameters.
    • It then checks the status of the batch delete job using the Get-PnPSiteFileVersionBatchDeleteJobStatus cmdlet.

Script to run trim

Check the job status by running Get-PnPSiteFileVersionBatchDeleteJobStatus or Get-PnPFileFileVersionBatchDeleteJobStatus after a while.

References

New-PnPSiteFileVersionBatchDeleteJob

New-PnPLibraryFileVersionBatchDeleteJob

Tutorial: Run ‘What-If’ analysis on version storage report file (Preview)

Tutorial: Generate and analyze version usage report for SharePoint site (Preview)