Thumbnail Extending Microsoft 365 with custom retention controls

Extending Microsoft 365 with custom retention controls

Recently, Joanne C Klein published a post on side effects of only using auto-applying retention labels. Whether those side effects are actually showstoppers or not, an organisation would need to know those challenges upfront when implementing retention controls. This blog post is about a small Microsoft 365 extension I’ve built to allow people to work around those challenges.

When using retention labels, many organisations do not want to (only) trust end users to apply the right labels. It may be that it’s not straightforward what retention label a document would need. Applying the right retention label may require a user to have an in depth understanding of how certain business processes relate to legal and regulatory frameworks. Making that choice is not always easy. And frankly, editing document metadata is also often not the first thing an end user is concerned about.

To work around that, those organisations often want to implement some automation to apply retention labels, be it through Microsoft’s own options (Auto-apply retention labels) or through custom automation using Power Automate, Azure Functions or scripts. Automated application of retention labels is a hot topic.

To do this, an organisation has to publish retention labels as auto-apply labels, or (in the case of custom automation) not publish the retention labels at all. I’ve written a small blog post on this some time ago. In both cases, users would not be able to apply a retention label manually.

But that does come with some side effects: the “Apply a label” dropdown will not be visible on documents at all. Even if a document is already labelled. The consequence is that it’s now impossible to clear a retention label manually as well. And secondly it’s now also impossible to toggle the record lock status when using record type retention labels and record versioning.

All this may or may not be what you want. In any case it’s now become quite hard to clear or relabel a document if it’s already labelled.

So what if you want to have it both ways? To have the power of auto-apply labels, but still be able to toggle the lock status manually… or clear the label manually…

I’ve developed a small open source Microsoft 365 extension to view and manage some retention controls. You can download the .sppkg file here or find the repository here. So how does it work and what does it do?

If a document is labelled using a retention label, an extra button will show in the document context menu / list command bar:

screenshot 1

That button opens a popup that shows some information on the retention label and information on when it was applied by whom and what settings are enforced on the document. It will also show links with which you can clear the label or toggle the lock status. If a document has been labelled using event-based retention, the label event date will also show. But only as soon as Purview has processed the event and the label event date has therefore become available on the document.

screenshot 2

Note: If a document has been labelled using event-based retention, the label event date will also show as soon as Purview has processed the event.

You can even select multiple items and clear the label on all items at once.

screenshot 3

To install and deploy this extension you’ll need to have the SharePoint Administrator role (or contact someone who has). The extension is a small SharePoint Framework solution that be installed and deployed on your entire SharePoint tenant or just on a selection of sites.

Just upload the SPPKG file to your app catalog and enable it on all sites to deploy it tenant wide:

app catalog

👷‍♂️ And that’s basically it! It’s a work in progress, so I may add new features, like the possibility to limit this to users with certain permissions. Or maybe by being able to relabel the document. If you have questions or feature requests, do let me know!

Of course I did use a couple of magic tricks in this solution. Among other things, I’m leveraging the following Microsoft Graph endpoint to get at the retention label information: /drives/{drive-id}/items/{item-id}/retentionLabel, which yields the following JSON-object with all kinds of interesting properties:

  "name": "Retention label for Contracts",
  "retentionSettings": {
    "behaviorDuringRetentionPeriod": "retain",
    "isDeleteAllowed": false,
    "isRecordLocked": false,
    "isMetadataUpdateAllowed": false,
    "isContentUpdateAllowed": false,
    "isLabelUpdateAllowed": false
  "isLabelAppliedExplicitly": false,
  "labelAppliedDateTime": "2022-12-22T10:18:23.6580555+00:00",
  "labelAppliedBy": {
    "user": {
      "id": "56d171c8-a92e-4359-9c4a-38b88ac7eabd",
      "displayName": "Contoso Admin"

The only thing that I’m missing here, is the label event date. So I retrieved that through the SharePoint REST API v1.

To query this Graph endpoint, you would need a delegated Sites.Read.All permission on the Graph. However, I generally want to avoid assigning permissions unless absolutely necessary. Specifically because these permissions (once approved) would be able to be used by any SharePoint Framework solution installed on the tenant. I wanted to circumvent having to approve any permissions, so I used the SharePoint v2 REST API to query the same endpoint. In my case this is as simple as querying https://{tenant-name}{drive-id}/items/{item-id}/retentionLabel. This will just use the existing auth cookies that you’re using when communicating with SharePoint. No additional permissions necessary ✅.

Locking and unlocking a record can also be done using the Microsoft Graph. However, that would also require approved permissions on the Graph. In this case Sites.ReadWrite.All. To work around this I’m using the same API endpoints that the SharePoint UI is using on the v1 REST API: /_api/SP.CompliancePolicy.SPPolicyStoreProxy.LockRecordItem() and /_api/SP.CompliancePolicy.SPPolicyStoreProxy.UnlockRecordItem()

For clearing labels I used the /_api/SP_CompliancePolicy_SPPolicyStoreProxy_SetComplianceTagOnBulkItems endpoint.

Checkout my blog post on programmatically working with retention if you want to know more.

Viewing and managing retention controls can be challenging, when trusting only on automated retention labels. With a simple extension of Microsoft 365, this can shift back in focus!

Happy retention!

purview sharepoint spfx compliance
Support me by sharing this


More blogs

Debugging production code in SPFx
Debugging production code in SPFx

A way to debug minified SPFx code in production against your original typescript code.

Read more
4 benefits of starting your DLM journey today
4 benefits of starting your DLM journey today

This post highlights 4 key benefits of implementing data lifecycle management.

Read more
Applying inactive retention labels
Applying inactive retention labels

In this blog post I'm highlighting the difference between active and inactive retention labels, and why you may want to keep your retention labels as inactive.

Read more


Thanks for reading

Thanks for reading my blog, I hope you got what you came for. Blogs of others have been super important during my work. This site is me returning the favor. If you read anything you do not understand because I failed to clarify it enough, please drop me a post using my socials or the contact form.

Warm regards,

Microsoft MVP | Microsoft 365 Architect

Microsoft MVP horizontal