Complete Tool Manual

Full reference for every screen and feature in the SPO Version Management Windows GUI application (v2.4.0).

New here? Start with the Quick Start Guide first.

Navigation Structure

The application sidebar contains these main sections:

Home

The Home screen is your at-a-glance operational view of the tenant. It shows:

Session Summary

Quick Actions

Shortcut buttons to the most common screens:

• Execute → Execution > Clean Versions
• Config → Configuration
• Sites → Site Catalog
• History → Execution History

Tenant Storage

Storage Trend (Monthly)

A chart showing monthly storage evolution over time. Updated by Data Sync.

Worldwide Impact

Shows aggregated anonymous statistics from the community telemetry backend (total storage freed by all participants globally).

Recent Executions

Quick view of the last 2-3 execution runs with timestamp, status, and site count.

Actions:

• Open Dashboard (top-right button) — Opens the HTML dashboard in your browser (http://localhost:8080)
• Backup Data — Creates a backup of all configuration and log files

PowerShell equivalent:

# Open the web dashboard
.\Start-Dashboard.ps1
# Opens http://localhost:8080

Pre reqs

The Prerequisites screen validates your entire environment before you can run the tool. Click Run Checks to validate all dependencies.

Validation Grid

Each row shows: Status (OK / FAIL), Version, Required For, and Action (Install button if missing).

The summary bar shows: ✓ N passed | ✗ N failed

JWT Debug

Click JWT Debug to decode and inspect the access token claims from your certificate authentication. Useful for troubleshooting permission issues.

Debug Output

Bottom panel shows verbose output from prerequisite checks for troubleshooting.

PowerShell equivalent:

# Check PS7
pwsh --version

# Check SPO module
Get-Module -ListAvailable Microsoft.Online.SharePoint.PowerShell

# Check Graph module
Get-Module -ListAvailable Microsoft.Graph.Reports

# Check PnP module (PS7 only)
pwsh -Command "Get-Module -ListAvailable PnP.PowerShell"

Config

The Configuration screen is split into multiple sections. Scroll down to see all options.

Part 1 — Connection & Authentication

Tenant Connection

Entra ID App Registration

Important: Without Entra ID app registration, you’ll need to log in interactively every time. See the Entra ID App Setup Guide for step-by-step instructions.

Purview App (Optional)

Required only if you want to manage retention policies:

Dashboard Settings

Part 2 — Directories, Auto-Update & Telemetry

Execution Directories

The Calculated Full Paths panel below shows the resolved absolute paths for each directory.

Auto-Update

Anonymous Telemetry

Telemetry is opt-in and collects only aggregate, non-identifying metrics to help improve the tool.

• ☑️ Enable anonymous usage statistics (opt-in) — Toggle to participate
• Preview payload — Click to see exactly what data will be sent before enabling
• Telemetry Endpoint — The backend URL: https://spo-telemetry-6406.azurewebsites.net

Example payload sent to backend:

{
  "tenantHash": "a1b2c3d4e5f6...",
  "appVersion": "2.4.0.0",
  "sessionId": "20260504_191530_2f180393",
  "sitesProcessed": 1517,
  "versionsDeleted": 42850,
  "storageFreedBytes": 8589934592,
  "duration": "00:45:12",
  "status": "Completed",
  "mode": "DeleteOnly",
  "majorVersionLimit": 5
}

What IS sent (anonymous, aggregate only):

• One-way hash of TenantId + local secret salt (impossible to reverse-engineer your tenant)
• App version and session ID
• Aggregate counts: sites processed, versions deleted, storage freed
• Job duration, status, and mode
• No IP addresses are logged server-side

What is NEVER sent:

• ❌ Site URLs, names, or any content
• ❌ Tenant name, domain, or admin URL
• ❌ User identity, email, or credentials
• ❌ File names, document content, or metadata
• ❌ Certificate thumbprints or client IDs

Why your participation matters: Telemetry powers the community statistics on the project website showing global impact (total TB freed, sessions run, tenants participating). This anonymous data helps:

• Prioritize features based on real usage patterns
• Demonstrate community impact to justify investment
• Identify common failure scenarios to fix
• Show the worldwide community how much storage is being saved collectively

Your participation is completely anonymous and directly helps improve the tool for everyone.

Actions (top toolbar)

PowerShell equivalent:

# All config is stored in config\AppPaths.json
# View current config:
Get-Content .\config\AppPaths.json | ConvertFrom-Json

# Edit directly or use the GUI

HTTP Server

Starts a local web server to host the interactive HTML Dashboard.

Server Status

Shows current state: ● Stopped (red) or ● Running (green) with the active URL.

Settings

Server Controls

Server Logs

Real-time log output from the HTTP server. Toggle Auto-scroll logs to follow new entries.

After starting, open http://localhost:8080 in your browser to view the full interactive dashboard with charts, site lists, and analytics.

PowerShell equivalent:

.\Start-Dashboard.ps1
# Starts server and opens http://localhost:8080

Retention

Manage Microsoft Purview retention policies that may block version deletion. When a site is under a retention hold, SharePoint prevents version deletion — this screen lets you handle that.

Summary Cards

Tabs

Actions

• Refresh — Reload policies from Purview
• Search bar — Filter policies by name
• Clear — Clear the search

Requires: Purview app registration (configured in Config → Purview App section). See Entra ID App Setup — Purview App.

PowerShell equivalent:

.\Start-SPOVersionManagement.ps1 -AdminUrl "https://contoso-admin.sharepoint.com" `
    -MajorVersionLimit 5 -ManageRetentionPolicy

Sites

Site Catalog

The full inventory of all SharePoint sites in your tenant. This data comes from the Data Sync operation.

Stats Banner (top)

• Version Size — Total storage consumed by versions across all sites
• Versions % — Percentage of total storage that is file versions
• Updated — Timestamp of last data sync

Summary Cards

Filters

• Text search — Filter by site name or URL
• Status filter(s) — Filter by: Active, Inactive, Locked, etc.
• Archive states — Filter by: All, Archived, NotArchived

Grid Columns

Actions (top-right)

Site Detail Popup

Click the magnifier icon (🔍) on any row in the Site Catalog to open the detail popup. This shows comprehensive information about a single site:

Storage Overview

Execution Summary

• Total Executions — How many times the tool has processed this site
• First Execution — Date of first processing
• Last Execution — Date of most recent processing
• Total Versions Deleted — Cumulative versions removed
• Total Space Released — Cumulative storage freed

Version Retention Impact

Execution History Table

Full log of all operations on this site:

PowerShell equivalent:

# Get site details
Get-SPOSite -Identity "https://contoso.sharepoint.com/sites/teamsite1" -Detailed

# Check version deletion job progress
Get-SPOSiteFileVersionBatchDeleteJobProgress -Identity "https://contoso.sharepoint.com/sites/teamsite1"

Execution Scope

Define exactly which sites to process during execution.

Warning Banner

⚠️ If Target Sites is empty, all sites in the tenant will be processed (minus Skip Sites).

Two Panels

Each panel shows: Site URL and Reason / Notes columns.

Actions (toolbar)

PowerShell equivalent:

# Use CSV files for scope control
.\Start-SPOVersionManagement.ps1 -AdminUrl "https://contoso-admin.sharepoint.com" `
    -MajorVersionLimit 5 `
    -IncludeSitesCSV "C:\path\to\IncludeSites.csv" `
    -ExcludeSitesCSV "C:\path\to\ExcludeSites.csv"

Archive Candidates

Sites identified as candidates for archiving. These come from the SharePoint Advanced Management (SAM) inactive site report that you import.

The grid shows the same columns as Site Catalog (Title, URL, Storage, Versions, Ver. Size, Status, Archive, Lock).

How to Export the SAM Report

You have two options to get the inactive sites report from SharePoint Admin Center:

Option A — From Advanced Management Overview:

1. Go to SharePoint Admin Center → scroll down in left nav
2. Click Advanced management (PRO badge)
3. Under “Content management assessment”, find Site lifecycle → “Site Inactivity”
4. Click View recommendations
5. In the “Site inactivity” panel that opens on the right, click Download a report
6. Save the CSV file

Option B — From Site Lifecycle Management:

1. Go to Policies → Site lifecycle management
2. You’ll see your inactive site policies listed

1. Click on Inactive site policies → Open
2. Find your policy in the list and click ⬇ Download on the Report column
3. Save the CSV file

Using the SAM report in the tool:

• Go to Execution → Clean Versions → Input Files → set SAM Report (CSV) to the downloaded file path
• OR go to Sites → Archive Candidates to view them in the grid and decide which to archive

Actions

Archived Sites

Sites that have already been archived. Shows the same grid as Site Catalog with archive state confirmed. Use this view to verify archival operations completed successfully.

Actions

PowerShell equivalent:

# Check archive status
Get-SPOSite -Identity "https://contoso.sharepoint.com/sites/oldsite" | Select-Object Url, LockState, Status

# List all archived sites
Get-SPOSite -Limit All | Where-Object { $_.ArchiveStatus -eq 'Archived' }

Archive Queue

Sites queued for archiving. You add sites here from the Site Catalog or Archive Candidates screens using the “Add to Archive” button.

The grid shows: Title, URL, Storage, Versions, Ver. Size, Status, Archive, Lock.

The bottom status bar shows: Queue source: ArchiveQueue.json | Rows in file: N | Valid rows (SiteUrl): N | Visible rows: N | Last updated: <timestamp>

Actions

When you click Run Archive, the tool opens a PowerShell window and executes the SharePoint archive command for each site in the queue.

PowerShell equivalent:

# Archive a site (lock access)
Set-SPOSite -Identity "https://contoso.sharepoint.com/sites/oldsite" -LockState NoAccess

# Full archive with SAM license (Microsoft official):
Set-SPOSiteArchiveState -Identity "https://contoso.sharepoint.com/sites/oldsite" -ArchiveState Archived

# Reactivate an archived site:
Set-SPOSiteArchiveState -Identity "https://contoso.sharepoint.com/sites/oldsite" -ArchiveState Active

Execution

Clean Versions

The main execution screen for version cleanup operations. This is where you configure and launch the version deletion process.

Session Control (top bar)

Tip: Sessions auto-save on interruption. You can always resume exactly where you left off.

Version Policy (left panel)

Delete Mode

Operation Mode (right panel)

Input Files (bottom panel)

Execution Controls (top-right)

Output Panels (bottom)

• Left panel — Real-time execution log (verbose output)
• Right panel (SITE PROGRESS) — Per-site progress tracker showing current site being processed

PowerShell equivalent:

# Full execution with all options
.\Start-SPOVersionManagement.ps1 `
    -AdminUrl "https://contoso-admin.sharepoint.com" `
    -MajorVersionLimit 5 `
    -MinorVersionLimit 0 `
    -MaxConcurrentJobs 100 `
    -ReexecutionDays 60 `
    -IncludeSitesCSV "IncludeSites.csv" `
    -ExcludeSitesCSV "ExcludeSites.csv" `
    -SkipGraph `
    -GraphReportCSV "SharePointSiteUsageStorage.csv" `
    -ManageRetentionPolicy `
    -Unattended

Data Sync

Synchronize tenant data for the dashboard, analytics, and execution history.

Sync Options

Input Files (optional)

Load data from local CSV files instead of calling APIs. Useful when you already have reports downloaded or when running offline.

Leave empty to use the default API-based data retrieval.

Click ▶ Run Sync to execute all checked options. Click ■ Abort to stop.

Telemetry Sync

If you upgraded from a previous version and have execution history that was never synced to the community backend, click ↑ Sync History to Telemetry to upload anonymized past results. This is a one-time manual sync for pre-existing data.

External Job Sync

Checks SharePoint for version management jobs completed outside this tool — by other admins, scripts, or scheduled tasks.

This ensures your Dashboard and re-execution rules (Re-execution Days) reflect the real state, even if other people ran cleanup jobs on the same tenant.

PowerShell equivalent:

# Sync only (no version deletion)
.\Start-SPOVersionManagement.ps1 -AdminUrl "https://contoso-admin.sharepoint.com" -SyncOnly

# Then open the dashboard to see updated data
.\Start-Dashboard.ps1

Archive Sites

Execute the archive operation for sites in the Archive Queue. This screen shows the same Archive Queue grid and lets you trigger the archival.

When you click Run Archive, the tool opens a new PowerShell window and processes each site sequentially using the Microsoft SharePoint archive command.

The bottom status bar shows queue source and row counts.

PowerShell equivalent:

.\Start-ArchiveWebsites.ps1

# Or archive individual sites:
Set-SPOSiteArchiveState -Identity "https://contoso.sharepoint.com/sites/oldsite" -ArchiveState Archived

File Archive Explorer

Search for files by extension across a specific SharePoint site using the Graph Search API. This lets you find large or unnecessary files to archive at the file level (not site level).

Management is per site — select one site at a time to scan.

Target Site

Authentication

Extension Groups

Create and manage groups of file extensions to search for. The tool uses the SharePoint search index to find matching files.

Extension Group Actions:

• + New Group — Create a custom group
• Reset Defaults — Restore default groups
• Save Config — Save current extension configuration
• ✗ — Delete a group
• ↕ — Reorder groups

Results Grid

After scanning, results show:

Actions:

• ▶ Run — Execute the search
• ■ Abort — Stop the search
• Export Config — Export extension group configuration

Select files from results and add them to the File Archive Queue for archival.

Requires: PnP.PowerShell module (PS 7+).

File Archive Queue

Track and execute file-level archive operations for files found via the File Archive Explorer.

Actions:

• Refresh — Update status of all items
• Remove Selected — Remove from queue
• Clear Queue — Remove all items
• Select All / Archive Selected — Archive specific files
• Start — Begin archiving all queued files

Session Manager

Browse, inspect, and resume past execution sessions. State is auto-saved on interruption so you never lose progress.

Session Grid

Actions (toolbar)

Session Detail Panel (bottom)

When you select a session, the detail panel shows the full configuration used:

• Session ID, Status, Admin URL, Started/Last Updated timestamps
• Configuration: Mode, Major/Minor Version Limit, Max Concurrent Jobs, Check Batch Size, Batch Delay, Delete Before Days, Zero Version Action, Manage Retention, Use File Cache

This is useful for auditing and understanding what parameters were used in each execution.

Task Scheduler

Schedule unattended executions via Windows Task Scheduler.

⚠️ Administrator privileges required. Click Run as Admin to elevate the application.

The grid shows: enabled state, task name, schedule (cron), last run, result, and next run.

Important: Scheduled tasks run unattended and require Entra ID app registration with certificate authentication. Interactive login cannot work without a user present. See the Entra ID App Setup Guide.

PowerShell equivalent:

# The task scheduler creates a Windows scheduled task that runs:
.\Start-SPOVersionManagement.ps1 `
    -AdminUrl "https://contoso-admin.sharepoint.com" `
    -MajorVersionLimit 5 `
    -Unattended

History

Full execution audit trail. Browse and filter every job ever executed by the tool.

Filters:

• Search — Free text search (site name, session ID, etc.)
• Status — Filter by: All, CompleteSuccess, Failed, InProgress
• Type — Filter by: All, BatchDelete, SyncListPolicy
• Date range — From/To date pickers

Grid Columns:

Actions:

• Export CSV — Download the full history as CSV for Power BI or Excel analysis
• Refresh — Reload from the local database

PowerShell equivalent:

# History is stored in config\SiteExecutionHistory.json
# Export to CSV for analysis:
$history = Get-Content .\config\SiteExecutionHistory.json | ConvertFrom-Json
$history.Sites | Export-Csv -Path "ExecutionHistory.csv" -NoTypeInformation

Updates

Check for new versions, download, and install updates automatically.

Features:

• Current version — Shows installed version (e.g., v2.4.0.0)
• Available version — Latest version on GitHub
• Download & Install — Downloads the ZIP, extracts over the existing installation (preserving all JSON config/data files)
• View local JSON databases — Check the state and size of your config files
• View release notes — See what changed in the latest release

The update process:

1. Downloads the latest release ZIP from GitHub
2. Extracts files, overwriting only application files
3. Preserves: config/ folder, Logs/ folder, all JSON databases
4. Shows release notes after completion

Status Bar

The bottom status bar (always visible) shows real-time system state: