All the ways to automatically apply a retention label in Office 365

Reading Time: 2 minutes

Do you want to apply retention labels across your Office 365 tenant, but you’re concerned about relying on end-users to manually apply them? If you do, you’re not alone. Nothing against end-users, but they have other things to focus on… retention isn’t one of them.

Here are the current ways to automatically apply a retention label and a use-case for each one. The options available are license-dependent (shown after the options), however please weigh the license cost against the cost of non-compliance. At the end of the post, I have links to my Ignite video and presentation for more details and a step-by-step walk-thru of each option.

  1. Automatically apply at a document library level
    • Approved Budgets document library
  2. Automatically apply at a folder or document set level
    • Financial Services Fiscal month folders
  3. Auto-apply based on a sensitive information type
    • Custom sensitive information type for customer # content
  4. Auto-apply based on a keyword query
    • Executive team sites
  5. Auto-apply based on a content type
    • Project documents across all Project Sites
  6. Auto-apply based on a metadata value
    • Expired Corporate Policies
  7. Automatically set using Power Automate
    • Custom logic: Approved Budgets over $20K
  8. Auto-apply using Trainable Classifiers (Preview)
    • Machine learning used to intelligently classify your unstructured data at scale

[Update December 6, 2019] To clarify, it is also possible to set a retention label programmatically using a REST API call, CSOM and Powershell. This was not mentioned because the intended audience for this post was power users and not developers. Please refer to a great post by Martin Lingstuyl for a deep-dive on doing this thru code: Managing and applying Purview retention labels using code

[UPDATED November 12, 2020] In addition to the techniques described in this post and on the Ignite 2019 video linked to below, please refer to another post of mine, SharePoint Syntex. First Steps with Intelligent Content Types and Compliance as an additional feature available to automatically apply retention labels.

Retention label licensing as of November 2019

Retention Label licensing

Note: licensing for Trainable Classifiers is yet to be determined.

I did a 20-minute theater session on this topic at the recent Microsoft Ignite conference. Check out these 2 resources for more info:


Image credit: Photo by Alex Knight on Unsplash


  1. Hi Joanne, thank your for this clear and concise summary of how to auto-apply a retention label.

    Regarding #1 and #2 in your table, I don’t understand why you wrote “No” in the E3 licence column.
    From what I know, an owner can set a default label for a ginv document library or folder, even if this retention label policy is deployed within an E3 licence (and then this “auto-applies” itself on the documents within this container).

    But maybe with Advanced Compliance, we can go further in applying a label at the library or folder level, directly through the rentention label policy settings/rules ? I’m not aware of that.

    Thank you for any piece of information you’ll share regarding my question.

    1. Hi Romain,
      The license table was verified by the Microsoft Security & Compliance team. If you have further questions, please follow-up with your Technical Account Manager for a better explanation.

    2. Hi Romain,

      I can confirm that in my E3 tenancy i can still very happily set default Retention Labels on Folders and Libraries. I hope that the Security and Compliance team have missed this and we aren’t going to be seeing this functionality become up-licenced (as I have used this feature in enterprise-scale scenarios for several of my E3 clients).


      1. Hi Rob,
        From my experience, the capability won’t be *hidden* from you, however it will require the elevated licenses I refer to. As of November 2019, the license requirements were confirmed by Microsoft for me so I could communicate them at my Ignite session.

  2. Thanks Joanne, do you have any insight on Microsoft’s view on only giving E5 to compliance admins to start using automate tagging, but leaving the rest of the org on E3 for example?

    This is a question that applies to many areas. For example, at the moment I am avoiding using conditional access that includes “All users”. Even though it works, we do not have AAD P1 applied on all users. I have previously heard that cloud licensing should follow: “all users that benefit from a feature should have the necessary license applied”. Meaning org wide E5 or compliance add on to make use of auto tagging

    Thanks again.

    1. Hi pontust,
      I am not a licensing expert. Please ask you Microsoft Technical Account Manager this question for the best answer.

      To my knowledge, if a user benefits from the service/feature, they need the license. Automated tagging sounds like one of those things – end-users will be using the content that may have an automated tag placed on it. (Particularly if they have contribute permissions or greater to the content) There may be exceptions if they only have read access.

  3. Great post as always, thanks Joanne, I notice there is now a removal of the limts on Flow(Power Automate) runs in a tenant so for those who cannot afford the extra licenses the API option is a really good one.

    I have been also found it possible with CSOM and Powershell options using the SetComplianceTag function is there a reason this wasnt included in your list and any reason why clients shouldnt be taking this route?

    Also looking forward to playing with some of the machince learning pieces!

    1. Hi Colin,
      This post was based off my Microsoft Ignite session and was limited to 20 minutes. I decided to cover off “Power User” options and didn’t include the CSOM/PowerShell options. To be clear, those are perfectly legitimate ways to set a retention label too.

      I will likely add a note to my blog post calling that out. Thanks for mentioning it.

      Thanks for your support!! 🙂

      1. Hi Joanne, this blog is a fantastic resource and I’ve referred to many of your posts over the pasts year, especially this one.

        The one thing I am getting really variable results on with auto-applying via KQL is the contenttype: “Content Type Name” syntax through the UI to SPO (have E5 license)

        I’ve checked my syntax using Search Query Tool and Content Search. I’ve powershelled Get-ComplianceTag to understand what the policies and rules applied are and looked at things like precedence. I’ve searched online forums to find if others are experiencing this issue and can’t find any discussions – I’m stumped.

        Any ideas on what I should be looking at to troubleshoot this before I concede defeat and contact Microsoft?

      2. Hi Aerial, thank you for your support! I’m assuming you’ve waited at least 7 days for the label to apply? You didn’t mention anything about timing so had to ask. Also, is there a default and/or manual label already applied to the item? If so, auto-apply won’t overwrite it.
        If you’ve verified both of those things, then opening a service ticket is the best course of action.

  4. Joanne,

    Great post very informative! Do you have a good reference for all the methods available, such as SetComplianceTag?

  5. Joanne,

    Is there a way to apply a default retention label ?

    As we can do it under “Sensitivity label policies” we can select a default sensitivity label, similarly, can we select a default retention label ?

    1. Hu Gurujyot, you can set a default retention label at a document library or folder level. Note: the retention label must be published to the site first. You cannot default everything in a site to have a retention label unless you use auto-apply and target the path to a site to apply a retention label. You’ll need an E5 or advanced compliance add-on to do that though.
      Hope that helps!

  6. Thank you so much Joanne for the response.

    Could you please elaborate on “publish the label to the site”?

    As per this article :

    It only speaks about assigning labels to the library not the the site 🙁

    Goal is to set a default retention label at a tenant level, since that can’t be done, so if we apply a label to the site, the user is creating a new library under that site, that library should inherit the same label.

    Do you think if that is posible?

    1. Hello, you should read up on the difference between a retention policy and a retention label. A retention policy is built in the Compliance Center and is published to a site. It applies retention to the entire site like you describe however it is NOT done thru a retention label. Instead, content is preserved in a special library called ‘Preservation Hold Library’. A retention label is also published in the Compliance Center thru a label policy and you can publish it to a site. However, when you do this, it DOES NOT mean every document on the site will get that label. The label still needs to be set as default on each library in the site. Alternatively, if you have the license to do so, you can do an auto-apply on a retention label and use the site path as a condition to apply the retention label to all content on the site. You can also read my ‘Retention in SharePoint Online: The WHAT’ to understand it better. Hope that helps.

  7. Hi Joanne, do we still need E5 license to autoapply retention labels? Microsoft page doesn’t state this requirement anymore.

  8. Hello Joanne,

    As it relates to #6, it seems that the KQL query used to identify content cannot make use of the Alias of a Managed Property and must use the actual Name of the Managed Property.

    For example, suppose we have mapped a crawled property named ows_MyColumn (from a column named MyColumn in SharePoint) to the RefinableString01 Managed Property in the Search Schema, and given the Managed Property an Alias of MyColumn.

    Using a KQL query of RefinableString01=”My Value” works fine but a KQL query of MyColumn=”My Value” (using the Alias as the property name) throws an error.

    Do you (or anyone else) see the same behavior?

    1. Hi Jim, i haven’t tested the use of Alias in the KQL for a retention label condition. Sounds like it doesn’t recognize it. I’ll see if i get an error as well. Note: fwiw… if memory serves, I’ve had issues using the alias on a query in a Highlighted Content web part too which means you can’t use alias literally everywhere you can use the original mp name.

  9. Hi Joanne, if i have a Deletion Policy that says delete content aber 10 years (without retention) and the user applys a label with a deletion after 20 years (also without retention): When will the content get deleted?

    1. Hi Dominik, I believe it will be deleted after 20 years due to the principles of retention. Explicit inclusion (retention label) wins over implicit inclusion (retention policy). It won’t go to the shortest deletion period rule because of that.
      My suggestion would be to test this with shorter periods to confirm. 😊

    1. Hey Brad, that was a link from Microsoft Ignite… they must have removed them. If they bring them back I’ll update it.

  10. Hi Joanne,
    Could you please let me know if there is away to set retention labels for individual documents (not to entire library) using Powershell

  11. Hi Joanne, a quick question. If you don’t want to immediately apply a label to a file that will make it a record, is there a way to have the label apply after a the document has been not modified after a certain amount of time (ie 6 months), so then the retention label can declare it as a record and the retention can start ticking? I just don’t want to auto apply a records label that makes a document a record if people are still working on the document (if that makes sense). I’m sure theres probably a way to do this with a custom workflow… or maybe a retention policy. To me it seems like this should be in the product but i haven’t seen it yet…

    1. Hi Kevin,
      No way to do this using the native retention label capability right now. Assuming you have an advanced license (if you’re referring to record labels I assume you do), then soon you will be able to take advantage of the multi-stage disposition that will allow you to do something like this… you could apply a default label to content with a retain for 6 months past last modified with disposition review and then relabel it with a record label during disposition.
      I have to ask… what’s your concern with applying the record retention label while people are working with it? You would need to train people to unlock/relock I guess, but if it truly is a record then seems it is a reasonable expectation – would like to know your thoughts.
      A retention policy is applied to content immediately and will retain for/delete after whatever length of time you specify – don’t think it does what you’re asking.
      Hope some of my rambling helps. 🙂

  12. Hi Joanne,
    I’m wondering if there is any way to auto-apply retention label to folders in the document library.
    In this scenario I can’t relay on my end users to manually applay RL on every new crated folder.
    When i saw your #2 I was very happy, but I can’t see how that is auto.

    1. Hi Johan, no there isn’t a way to automatically apply a label to one specific folder. You can default the entire library (which would then apply the label to all files within the library including within folders) however once you do that, an auto-apply label will never override a file that has a default label on it. This may not be of concern to you though.
      Defaulting at the library level is a good way of getting a label on the files within and then relying on end-users to change the label if/as required.

Leave a Reply

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