Table of Contents
Use Graph APIs to Track Progress of File-Level Archiving for SharePoint Online.
In August 2026, Microsoft launched the ability to create an archival step in the settings of Purview retention labels. For example, let’s assume that you have a retention label with a five-year retention period, after which labeled items are deleted. You can now insert archival at any point before the retention period ends. Let’s say after three years. At that point, Purview moves the items into Microsoft 365 Archive and keeps them there until the retention period expires.
I like this capability a lot. It’s an excellent way to keep information that might be needed for the full retention period while potentially reducing cost by moving data into lower-cost storage at some point during the retention cycle. Tenants that use Microsoft 365 Copilot also gain an advantage because archiving old material removes Copilot’s ability to consume that information.
A Graph API is available for file-level archiving. I demonstrate how to use the API to archive old email files for Teams channels captured in SharePoint Online in this article.
The Problem with SharePoint Retention
Everything seems positive until the time comes to validate that retention labels with archive settings are working as they should. Retention processing for SharePoint Online is an impenetrable black box. Administrators configure policies and labels and then rely on SharePoint background jobs to execute the configured settings.
The only practical way to validate retention processing is to examine site content and verify that the expected actions occurred. In this case, did Purview archive items. Disposition reviews might be considered an exception because of the need for reviewers to act when retention periods expire. However, you could wait years for retention periods to expire, and that’s a little long to know if retention happens as expected.
Checking the Effectiveness of Archiving by Retention Labels
Checking individual sites and browsing through folders and items to deduce if Purview is archiving files is easy when just a few files are involved, as in the case of testing. Once an auto-label policy is deployed to apply a retention label with an archive action to large quantities of items, checking becomes more difficult.
In cases like this, I usually open Visual Studio Code and start writing PowerShell. You can download the code from the Microsoft 365 for IT Pros GitHub repository. The script:
- Uses app-only authentication with the Microsoft Graph PowerShell SDK. App-only mode is needed to access items in sites across the tenant.
- Fetches all Microsoft 365 Groups and populates an array. I think the SharePoint sites connected to groups (or teams) are most likely to hold archived files. If you disagree, you can alter the code to use the Get-MgSite or Get-MgAllSite cmdlet to fetch sites and then filter the set to remove archived sites, deleted sites retained by policy, personal sites, and so on. This article explains how to fetch SharePoint sites with the Microsoft Graph PowerShell SDK.
- Finds the drives (document libraries) for each site and removes drives that we don’t want to process, like the preservation hold library.
- For each drive, iterates from the root to find files and check the archive status for each file.
- Reports the results via email.
Because the app is assigned the Mail.Send and Sites.Read.All permissions, it’s got a lot of access to tenant data. You should use RBAC for Applications to restrict the app to specific mailboxes.
Figure 1 shows some of the information provided to administrators. The email lists:
- The sites where file-level archiving is in use and the number of files archived in the site.
- The years when archived files were created.
- The file types of archived files (in my case, most are Word documents).
- The size of the archived files and the total number of archived files found. Files can be archived by a retention label or manually by a user (the SharePoint browser interface is very efficient at applying file-level archiving to large groups of files).
Scheduled Check
This kind of checking is a classic use case for Azure Automation, and I would like to run the code as a monthly scheduled Azure Automation runbook. However, I am blocked because of a Graph SDK issue with site cmdlets. When Microsoft fixes the SDK issue, the only required code change is to replace the app-only parameters for the Connect-MgGraph command with a managed identity. You should also remove the output commands used to signal progress because they make no sense when running on a headless server.
Until a fix is available, I’ll run the code every two weeks or so using app-only authentication. The processing takes about eight minutes of runtime for my (small) tenant. Maybe after file-level archiving settles down (the archive action for retention labels is still in preview), I’ll ease up and check every two months or so, but for now, the data tells me that file-level archiving is happening as expected, even if Purview retention processing is a black box.
Microsoft 365 for IT Pros is a trusted source of technical insight that helps tenant administrators stay informed and productive. We update the content every month to reflect changes across Microsoft 365, and monthly update #135 is available now. Get your copy from Gumroad.com and stay up to date with the information that matters most for keeping your tenant secure, compliant, and running efficiently.