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 “dark” data

[Update December 6, 2019] To clarify, it is also possible to set a retention label programmatically using  CSOM and Powershell with the SetComplianceTag method. This was not mentioned because the intended audience for this post was power users and not developers.

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!! 🙂

  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. 😊

Leave a Reply

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