Modern Retention using SharePoint Metadata

Reading Time: 5 minutes


Important: I am confirming with Microsoft if this workaround is a supported method for applying retention. I will update this post with those details when known.

[Updated August 3, 2018] I received the response quoted below from Microsoft. In summary, the steps to create the Retention Policy in this post IS NOT SUPPORTED so please do not use them. In full transparency, I’m leaving this post active rather than deleting it to hopefully prevent someone else from trying this method:

“Thanks as always for your diligent support of our content services solutions for Office 365. As you might guess, what you’ve found isn’t a supported solution – something that requires you to save a blank and then edit it – that’s below the quality level we strive to maintain. However, support for direct auto-labeling and retention of content based on content types and/or library metadata is something we will be announcing and releasing soon, if you can wait a bit longer. We promise it will be even smoother than the solution you’ve outlined here.  

But make no mistake about it – soon this scenario will be fully supported.”


Retention labels in Office 365 are configured in the Security and Compliance Center. You can manually set a label or use the auto-apply feature to automatically set it based on a condition. The condition can be based on one of two things:

  • sensitive information type
  • keyword query

If you’re coming from the Information Management Policy world where you can set retention based on a piece of metadata or a content type on a document, you are likely looking for similar capability in the new world of Retention labels. Up until this point in time, I didn’t think this was possible, however I’m pleased to say I’ve now found a way to do this using the keyword query capability.

The keyword query uses KQL syntax. In this syntax, you can search for any managed property in SharePoint that is queryable. This requires an understanding of how SharePoint metadata translates into a managed property in the search schema. Once you understand this, it opens up a world of possibilities for automatically setting retention based on a SharePoint metadata value. Examples of where this might be useful:

  • apply a Budget retention label against all budgets when their status is ‘approved’
  • apply a Contract retention label when the contract status is ‘Expired’

There is a UI bug that was stopping me from using KQL syntax to search against a managed property, however I’ve found a way around it! Follow below for the steps to implement the second example above to apply a Contract retention label based on a SharePoint column.

Create Site and IA to hold Contracts

For this example, I’ll create a new modern SharePoint Communication site called Contract Central. Within this site, I’ll define the Information Architecture (IA) to store all contracts. This will include a Content type called Contract with the following site columns:

  • Contract status – choice values: Pending, Active, Expired
  • Contract effective date – date
  • Contract expiry date – date

Create a new document library called Contracts. In this library, include the custom Contract content type from above.

Add some contract documents to the Contracts library and fill in the metadata. Ensure some of them are set to each of the contract statuses to demonstrate the auto-apply feature. In the image below, I’ve added 6 contract documents, all of the Contract content type, 3 of which are set to Expired.


Let Search do its Magic!

Wait for search to index the content added above. During this process, crawled and managed properties are generated in the search schema and, when complete, I’ll leverage 2 of them in this solution.

To build a query using managed properties, they must be queryable. (have the Query property set)

The first property to query is the content type. I only want to apply the Contracts label to documents that are a Contract content type. To do this, I’ll query the ContentType managed property (queryable property is circled):


The second property is the contract status. There is a UI bug I’ve noticed on some automatically generated managed properties where the settings appear blank on the managed property page, however this does not reflect the true settings of the property. In the 2 images below, the managed property generated for the Contract Status column, ContractStatusOWSCHCS, doesn’t appear to have the queryable property set, yet when you edit the property, it is.

This slideshow requires JavaScript.

Once I confirmed the two queryable managed properties were defined in the search schema, I’m ready to define the retention label.

Tip: to quickly test your query before proceeding to the next step, enter it in a search box in SharePoint. You should get back the correct search results:

ContentType:Contract AND ContractStatusOWSCHCS:Expired

Create Retention Label

Retention labels are added in the Security & Compliance Center under the Classifications section. I created a new retention label called Contract with these settings in accordance with the retention requirements for my organization. Retention will commence when the document is labeled since we want to only label it when a contract is expired and will be automatically deleted 3 years after that:


Create Retention Policy (Tricky part)

Warning: this step is not supported. Please refer to Microsoft’s response at the beginning of this post.

To auto-apply the Contract label from above, select the Auto-apply a label button  from the label definition pane.


This will prompt you to fill out some settings to auto-apply the label. For the Contract label, we want to set it based on specific words or phrases, so select the second option:


Here’s what I’ve discovered… in the Keyword query editor box that appears, you can either leave it blank  or enter a temporary value just to allow the policy to be saved. If you try and enter your KQL query on this first save, the save will fail. I’ll adjust it on the second pass to include the correct query.

First pass when defining the auto-apply retention policy

Next, name the policy and specify the Contract Central site in the Locations section to perform the auto-apply on. Save the policy.

Immediately, edit the same retention policy and click Policy settings to show the Keyword query editor. This time, enter the correct KQL query to find all Contracts that have expired. To do this, we query on a Content type of Contract and a Contract status of Expired. (image)

Second pass when defining the auto-apply retention policy

Wait for the auto-apply

Once you save the Retention Policy with this updated query, the auto-apply can take up to 7 days to apply the label to all content across your tenant. For this test, it took 3 days. As you can see from the results, the Contract retention label was only applied to documents where the Content type is Contract and the status is Expired:


Where to from here?

This capability brings a lot of flexibility to the retention label picture for SharePoint. It can be used to automate some of the retention scenarios in your organization making you less reliant on end-users to manually label a document.

Thanks for reading!



  1. Excellent and I look forward to your next post. Is it possible to update the keyword policy settings, say if there is a change to the IA / managed properties, and will this deploy?

  2. Most handy would be a Microsoft solution using a similar kind of construction as Flow: pick your query blocks (worded in nice, easy layman’s language), and add your details to each block…

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.