Auto-apply Retention Labels in Office 365 using Content Types and Metadata

Reading Time: 4 minutes

I think we all agree automating as much retention as possible is a good thing. The less we have to rely on information workers to manually apply a retention label, the better. The information architecture you’ve diligently defined in your tenant can now be leveraged using auto-apply conditions to automatically set an Office 365 retention label.

Microsoft has also announced machine learning classifiers to help with the growing amount of corporate “dark data”  (not within a well-defined information architecture). This will apply out-of-the-box and custom classifiers to intelligently apply retention across your tenant by classifying content based on meaning and context. I haven’t seen this in any tenant I’ve worked with yet, but this will add another level of automation many organizations are waiting for! Once I see it, I’ll blog about it…

Licensing… the capability to auto-apply labels described in this post requires an Office 365 Enterprise E5 license for each user who has permissions to edit content that’s been automatically labeled in a site. Users who simply have read-only access do not require a license.

If you don’t have the license for the auto-apply functionality or you have advanced logic to determine if a retention label should be applied that can’t be done in the auto-apply condition, refer to another post of mine where I show an alternative way to automatically set a Retention Label using Microsoft Flow: Setting a Retention Label in SharePoint from Microsoft Flow. This provides a lot of flexibility to include any kind of logic you may require to set the label.

Retention labels can be auto-applied based on 3 conditions:

  • sensitive information types (both out-of-the-box and custom)
  • keywords
  • content types and metadata

This post describes the third option above to demonstrate the auto-apply behavior across several column data types and content types in SharePoint. Due to the fact that the retention label isn’t applied immediately (controlled by a back-end process that runs ~once per week), this is not a quick test to do. I’ve spent the time testing this, so I’m sharing the results and learning with you!

Please refer to the ‘Important things to know’ section at the end of this post for some key takeaways on this functionality. I will update the takeaways as I learn more.

Apply a Retention Label based on a Content Type

Content type called Contract document has been added to a document library. Retention label called Contract has been created and auto-applied based on the condition below:

ContentType:’Contract document’

The result? Within a week, any SharePoint site the retention label is published to had the Contract retention label applied to all documents with the content type of Contract document.

Apply a Retention Label based on a Choice Metadata column

A choice metadata column, ContractType, has been added to a library. I want to use one of the choice values to set a retention label. The auto-generated managed property from the search schema cannot be used in the auto-apply condition. You must manually map the crawled property to a RefinableString property (it’s queryable). For this example, I’ve mapped the crawled property generated for metadata column, ContractType, to RefinableString00.

Retention label called Hardware has been created and auto-applied based on the condition below:


The result? Within a week, any SharePoint site the retention label is published to had the Hardware retention label applied to all documents with a choice value of ‘Hardware’ on the ContractType metadata column.

Apply a Retention Label on a compound condition

What about combining conditions? You can do this too! This test combined a content type name of Contract document with a choice value of Software. A retention label called Software has been created and auto-applied based on the condition below:

ContentType:’Contract document’ AND RefinableString00:Software

The result? Within a week, any SharePoint site the retention label is published to had the Software retention label applied to all documents with a content type of Contract document and a choice value of ‘Software’ on the ContractType metadata column.

Apply a Retention Label on a Date column <= Today

Can you include date logic in the condition? Yes. I have added an optional date column, DateExpired, to a library and want to apply the retention label once a date has been entered and is today or in the past. To filter on a date column, you must map it’s crawled property to a RefinableDate column (it’s queryable), so in this case I mapped it to RefinableDate01. A retention label called Expired Contract has been created and auto-applied based on the condition below:


The result? Within a week, any SharePoint site the retention label is published to had the Expired Contract retention label applied to all documents when a date either equal to today or in the past has been entered into the DateExpired metadata column.

Note: if a date isn’t entered in the column OR a future date is entered in the column, a retention label is not applied.

Important things to know:

Through my testing, I learned a few things that are important to understand and communicate to the Information Management team:

  1. The back-end timer process to update the retention labels only runs weekly. If it is your expectation that the label will be updated soon after the metadata or content type is updated, this is incorrect. In tenants I’ve tested with, the process runs in the early hours of the morning (UTC-6) on Friday or Saturday mornings.
  2. If a retention label is already applied on a document, the auto-apply process will NOT override/replace the label even if an auto-apply condition is met. Example: if you set the column Contract Type to Software and this auto-applied a label to ‘Software’, and then you subsequently change the Contract Type to Hardware, the label will not change to ‘Hardware’ if you had an auto-apply condition set to that. The original label, Software, would remain.
  3. The columns filled in when the label is auto-applied are: Retention label, Retention label applied, and Label setting. The Label applied by is not filled in.
  4. You can still manually remove the retention label by editing the properties. If you do this, the next time the back-end process runs, it will re-assess the document based on the auto-apply conditions and, if met, re-apply the correct label.
  5. A simple way to test out your conditions before creating your label policies is to enter the query directly in the Microsoft Search box thru the SharePoint UI. It will return the same results.
  6. Although I’ve seen other posts where an auto-apply condition was based on a managed metadata term value, I’ve been unable to get this to work. I have a ticket open with Microsoft to understand the issue. Once resolved, I’ll update this post.

Thanks for reading.


Credit:Image by Jess Watters from Pixabay


  1. Thanks so much for the time you’ve put in to this post! Just a quick question – your point 2 above is quite worrying. Would there be a way around this, for example when a metadata entry is changed this triggers a Flow that removes the retention label? So then your point 4 could happen and the new label would be applied.

    1. I’m also interested in point 2, there’s a point here within Microsoft’s documentation that states:

      “If there are multiple rules that assign an auto-apply label and content meets the conditions of multiple rules, the retention label for the oldest rule is assigned.”

      I interpret this as how an auto-applied retention label is applied to a new un-labelled document.

      If this is by design and intended it might by because it prevents manipulation of the retention period of the original record, although this would negate the ability to alert the retention period through different stages of its lifecyle.

      If it is by design I feel that Microsoft should include another point in their documentation that should state something like this:

      “If content has had an auto-apply label assigned in the past and metadata values are changed to meet different conditions a new auto-apply label is not auto-applied.”

      I’ll see if i can raise that as a request in the Microsoft documentation and have them at least clarify. If i have any success i’ll report back via this post.

  2. Thanks for another valuable post! I was triggered by the statement at the beginning of the blog “Microsoft has also announced machine learning classifiers…”. I actually noticed an Ignite session (BRKBRK3223) from 2018 where Microsoft outlined this capability ( With such an advanced feature, I’m thinking why I missed it before. I am super excited to go hands-on when it becomes available.

  3. Once again thank you for documenting all of this, it is invaluable!

    I have one question on your use of the built in managed properties, have you tried creating your own queryable managed properties and mapping them to your crawled properties? Just wondered if that was an option as it’s possible some other process is already making use of the built in RefinableXXX managed properties and there’s (albeit a very small) chance a label could get applied with a “false positive”.

    1. Hi Colin, no I haven’t tried that but I see no reason why that wouldn’t work. Thanks for the feedback!

Leave a Reply to Colin Rippey (@finarne) Cancel reply

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