Priority cleanup for SharePoint Online and OneDrive for Business

Earlier this year, Microsoft released the Priority cleanup feature in preview, which we covered in a series of articles. The gist of it is that Priority cleanup allows you to override existing retention controls and dispose of items subject to them, but only after multiple levels of approval. The initial version of the feature only supported Exchange Online mailboxes. Now, Priority cleanup is getting support for SharePoint Online and OneDrive for Business sites, so let’s take a look.

Scenarios covered by Priority cleanup for SPO/ODFB

While Microsoft positioned Priority cleanup for Exchange Online as a security/data spillage prevention scenario, in the case of SPO and ODFB sites their vision is a bit different. The expectations are that far greater volume of items will be processed, thus there are some changes to the review process. One scenario Microsoft expects customers to leverage Priority cleanup for is to delete Teams meeting recordings and transcripts. Another one is to remove items stored within the Preservation Hold Library, which is what we will be testing later on.

The above examples are simply scenarios that Microsoft has considered and envisions customers will make use of. As we are free to use any KQL property supported for auto-labeling items, there are many additional scenarios where Priority cleanup for SPO/ODFB can be employed. The aforementioned expectations however have shaped some of the design aspects of the feature, and you might be surprised to discover it behaves differently compared to Exchange Online scenarios.

Configure Priority cleanup for files

Before creating Priority cleanup policy for SPO and ODFB sites, we need to ensure the required permission assignments are in place. Nothing new here, so I will just refer you to the official documentation on this. Another prerequisite that you might need to address is creating an adaptive scope, if you plan to use such with your priority cleanup policy. Once prerequisite are met, open the Purview compliance portal, select the Data Lifecycle Management solution, then Priority cleanup. Click the Create a priority cleanup button to start the process.

Name your policy and make sure to enter a proper (and detailed) Description. On the next page, select whether you’d like to use an Adaptive or Static Scope for the policy. To keep things simple, we will use a static one. Proceed to the next page in order to configure the Locations to include. As we will be configuring a priority cleanup for items stored in SPO and ODFB sites, select Policy for SharePoint/OneDrive here. The selection is split between SharePoint classic and communication sites, covering files in all non-group connected sites (including those corresponding to shared and private channels) and files stored in sites corresponding to OneDrive accounts. Do note that if you want to cover Microsoft 365 Group-connected sites, this is only possible via Adaptive scopes.

Adjust the selection of included and excluded sites as needed, then hit the Next button to proceed to the Conditions page. Herein you configure the KQL query that will be used for the underlying auto-label policy. You can use any of the keywords and conditions supported for auto-labeling policies. And if you need a refresher/explanation on how this auto-labeling magic comes into play, refer to our previous article on the subject.

Next, under the Settings page, decide what to do with any items matched by the priority cleanup policy. You can choose to either Delete items as soon as possible or override the current retention period via the Prevent permanent deletion until a set time option. After that, you need to configure the set of Approvers. Unlike the Exchange Online scenario, for a SPO/ODFB priority cleanup policy we only need to define approvers in a single scenario, namely when items matched by the policy are subject to an eDiscovery hold. Retention policies do not count in this regard, but more on that later.

Lastly, you need decide whether to create the priority cleanup policy in disabled state, or turn it on immediately. This is the other big difference compared to the Exchange Online scenario, as a policy can only be turned on in Simulation mode. This mandatory mode allows you to review the accuracy of your KQL query by surfacing (subset of the) matches and serves as the replacement of the additional approvals needed in non-eDiscovery hold related scenarios. We will cover this in more detail in the next section.

The last page of the policy creation wizard allows you to review its configuration and requires you to acknowledge the impact before allowing you to hit the Submit button. At this point some additional checks are made, such as ensuring the approver permissions are correctly assigned or no invalid characters are present in the policy name. If everything checks out the policy and its underlying rule, compliance tag and associated policy/rule are provisioned on the backend. You’ll be presented with the compliance tag ID, which can be used to fetch additional information on the policy and its processing.

Simulation mode

As mentioned above, Simulation mode is now mandatory before any newly created priority cleanup policy can be turned on. To access the results of the simulated run, select the priority cleanup policy entry to open its Details pane, then click on the View simulation details button. The Simulation Overview page will give you a quick summary of the effectiveness of the KQL query you configured for the policy. Up to 200 sample items will be available for detailed examination under the Items to review page.

The experience matches that of “regular” auto-apply policies, so please review the official documentation in case you need a more detailed guide, or want to understand the limits it is subject to. For our purposes, the most important thing to be aware of is that the user who created the policy cannot enable it even if everything checks out with the simulation run. Instead, one of the designated approvers will have to do that, by accessing the Simulation page and hitting the Turn on policy button on top. This ensures the four-eyes principle is adhered to.

Should any of the sample items raise a question as to the policy’s effectiveness, you have the ability to Edit the policy settings right from the review experience, as well as to Restart the simulation. Otherwise, proceed to enable the policy, or ask one of the other approvers to do so. Once enabled, it can take up to a week for the policy, its associated rule and compliance tag to be distributed, and start taking effect on any matched items. We discuss the various method available to monitor the policy’s progress later on.

(Lack of) Disposition review

Back when we covered Exchange Online priority cleanup, we spent quite few words on detailing the reviewer experience. The process remains largely the same, sans the Exchange specific bits such as the limit in the number of items that can be tagged by a single run of the MFA. There is one huge difference though, as alluded to above – approval is only required for items that are subject to eDiscovery holds. This does NOT include items affected by retention policies/holds. For example, a site subject to a retention policy to keep all items forever will happily allow priority cleanup to remove any matching items without even a hint of approval process.

To make it clear, this is not a bug, but intentional design decision. Microsoft’s reasoning behind this approach is that an non-direct approval was already received by the person that enabled the policy after its simulation run. Another argument is the larger volume of items expected to be processed for SPO/ODFB scenarios. I do not agree with those statements, and not only because of the obvious differences in behavior compared to the Exchange scenario. We will have to wait and see whether this behavior will get tweaked based on customer feedback, but until such time comes, be aware that item-level approval will only be required for items subject to eDiscovery holds.

In turn, you will not receive any notification emails in this scenario, either. This makes it that more important to ensure that the initial policy configuration process and the simulation run properly reflect the expected outcome. While deletions are not final, as we will discuss in the next section, recovering items is not that simple. Further complications arise from the fact that the second stage Recycle bin is not indexed and content searches will not return any items stored therein. Effectively, we are left with the audit log trail as the only way to gauge the policy’s effectiveness and monitor its progress.

It’s not all bad news though. As the audit log data powers tools such as the Activity explorer, we can get a quick overview and even item-level details with ease. The screenshot below illustrates how our priority cleanup policy performed over the course of few days, giving us the total number of items processed, items processed per days and details on each individual item.

How items are processed

One of the points I made when discussing priority cleanup for Exchange Online was that it is hard to monitor the progress of the policy processing. Luckily, this is a bit easier when it comes to items stored in SPO/ODFB as the corresponding metadata is easier to access. Once the priority cleanup policy takes effect, any matching items will get tagged with the Compliance tag associated with the policy, and bearing its name. In our test scenario above, this would be “PHL cleanup 2”. The screenshot below shows one such example:

This allows you to adjust the view settings to surface said metadata and sort or filter items by it, in contrast to the Exchange Online scenario where we had to work with MFCMAPI or similar tools. Unfortunately, as items get processed, they end up in the second stage Recycle bin, where we have much limited options to curate the view.

Items processed by the priority cleanup policy remain in the second stage Recycle bin for up to 93 days, so removals are not immediate. And since the second stage Recycle bin is not indexed, Content searches and eDiscovery queries will happily tell you that no matching items remain, which unfortunately is not always true. In effect, reporting on the contents of the second stage Recycle bin is something you might want to consider as part of the cleanup process, and given the lackluster UI, using the Get-PnPRecycleBinItem cmdlet is probably the way to go.

Removing the item(s) from the the second stage Recycle bin will result in their permanent deletion. Recovering items on the other hand is not as simple as hitting the Restore button. The item will keep its compliance tag after the restore and will end up moved to the second stage Recycle bin after the next processing cycle. In order to exclude a given item, you must instead adjust the KQL query for the corresponding priority cleanup policy.

Lastly, keep in mind that the process can take some time. The initial policy distribution and label auto-assignment can take up to a week, while still being a subject to the daily processing limits. For this test scenario, a rate of about ~2300 items per day was reached, which can have some implications if your policy is expected to process thousands upon thousands of items. The processing limits also affect the “recovered” file experience – it can take some time to reprocess a given item, depending on the total number of items covered by the policy. Rest assured, a file you tried to recover by hitting the Restore button will inevitably get deleted anew.

Some additional notes and summary

Before closing the article, some additional details are worth mentioning. Much like the Exchange Online scenario, disabling a priority cleanup policy requires you to go over the full wizard, which is a bit annoying. But as active policies continue to run indefinitely until disabled and will process any items that match the corresponding KQL query, you might not always want to keep them enabled.

In terms of audit trail, using the compliance tag ID remains the quickest way to fetch (most) relevant events. The screenshot below showcases the results of an Audit log query, filtered to show events corresponding to the processing of a single item. A PriorityCleanupTagApplied event, attributed to SHAREPOINT\system, signals the initial auto-labeling event. The item was then moved to the second stage Recycle bin (PriorityCleanupFileRecycled). A second deletion event follows, as the item was manually recovered from the second stage Recycle bin, only to be recycled anew, as it remains under the scope of the priority cleanup policy.

Another thing to keep in mind is that OneNote files stored in SPO/ODFB are processed differently. Priority cleanup works at the section or page level, as do retention policies. Lastly, it’s worth reiterating that we can use some “special” KQL keywords for scenarios such as cleaning items stored in the PHL (use the ParentLink:PreservationHoldLibrary keyword) or to target Teams meeting recordings and transcripts (ProgID:Media AND ProgID:Meeting).

In summary, we covered how Priority cleanup supports items stored in SharePoint Online and OneDrive for Business. When comparing it to the Exchange Online scenario we examined previously, quite few differences, both in the initial configuration and the way items are processed, are apparent. Some of these are direct consequence of the building blocks the feature uses, but might be a surprise to people that aren’t used to working with auto-apply labels. For others, a deliberate design decision has been made. Examples in this category include the lack of disposition review for items subject to retention policies as well as the use of the second stage Recycle bin instead of permanent deletion.

Personally, I do find it a bit annoying that even in 2025, we lack a uniform approach across all Microsoft 365 workloads. This was supposedly one of the big selling points of the unified compliance architecture, but we’re yet to see it realized. On top of the inherent workload-specific oddities, Microsoft decided to further deviate from the experience we’ve detailed for the ExO workload, in few areas we listed above. We can extend various arguments for or against such design decisions, and Microsoft might even change the behavior before the feature reaches GA. My point is simply that is pays to have a predictable, uniform experience across all workloads.