Event-driven retention in Office 365. A walk-thru.

Reading Time: 5 minutes

Being able to set retention based on an event is a common requirement in any organization. Here are some typical examples:

  • delete a contract 5 years after its completion date
  • make employee documents immutable after their termination date and retain forever

In the Office 365 world of retention labels and policies, how would we implement this sort of thing? Just released as generally available, you can configure retention based on an event rather than solely on when something was created, modified, or labeled.

Reference: Overview of event-driven retention

GA announcement: Events based retention is now GA in Advanced Data Governance

I show a walk-thru on event based retention in this post. I end with my observations on the process so if you’re short on time, skip ahead to that part. ūüėČ

Set up Classification label and associate it to an event type

For this blog post, I’ll walk thru the first example from above –¬†delete a contract 5 years after its completion date.

An event-based label is defined as a Classification label where you have chosen to Retain the content and either Delete it automatically or trigger a disposition review AND is based on an Event rather than when a document was created, modified or labeled. (image)

label dropdown

Associate an Event Type to the label

Once you select an event from the dropdown above, you must associate it with an event type.¬†There are currently 16 pre-defined event types (image). Event types are a mechanism for organizing all the labels relating to any one event. For this example, I selected¬†Expiration or termination of contracts and agreements but you can add your own event type if there isn’t a suitable one in the list.

Pre-defined event types


This is my label configuration… retain for 5 years after contract expiry and then delete it:



Publish the label

Like is done with non event-based labels, you must publish them to a policy in all consuming site collections. Once the policy is published, it can take up to a day for the label(s) to appear. In this example, I’ve provisioned a Modern Team site called Contract Central to hold all contract documents so this is the site collection I published the label policy to. You can also auto-apply a label if it makes sense to do so.

Apply a Contract Label to documents

Now that enough time has passed, the Contoso Contract label is now viewable in the¬†Contract Central¬†SharePoint site.¬†I’ve included both the label and the Compliance Asset Id in the document library view of the Contract documents for demonstration purposes:

On every list and library in SharePoint Online, there is a new hidden text column titled “Compliance Asset Id” with an internal name of “ComplianceAssetId”. This is how event-based retention is managed in the back-end.

You will need to apply the label and associate an Asset ID with each document. The Asset ID will be used when you define the event later on. In this example, we will put in a Contract #, CN9999. For any contract documents relating to this contract, they will all have the same Asset ID.

Document Property

I’ve labeled 3 documents in my library with the¬†Contoso Contract label and have assigned the CN9999 Asset ID to 2 of them.

Documents Tagged with Asset ID

Event-driven retention is search-based so we will wait for this content to be crawled.

Create the event

AddEventIt’s now time to create the Contract End event. When I was first introduced to the idea of event-driven retention, I was under the impression we would be able to generically define a date column that could trigger an event, but in fact you must manually create EACH event in the Security & Compliance Center for any particular event type.

In this example, when contract CN9999 ends, an Administrator would add that event by going into the Events section under Data governance. (image)

In this example, I create an event called Contract CN9999 terminated and associate it with an event type, in our case Expiration or termination of contracts an agreements, and Asset ID CN9999 (although you could specify more than one Asset ID if required). Finally, you enter the date the event occurred which can be a current, past, or future date.

You must enter the Asset ID in the form propertyname:value so in our case that is ComplianceAssetID:CN9999

Event Settings


Note: to retain content in Exchange, you cannot use Asset ID, but keywords instead.

To automate this process at scale, you can leverage the PowerShell cmdlets.


Once you’ve saved the event, its distribution status will move from Pending to¬†Success and¬†you will be able to view how many mailboxes, sites and items have been processed. In this example, the status is¬†Success and I see the number of sites(1) and items(2) it has detected matching the event for CN9999. In my testing, it took a couple of days for the numbers to appear.


Monitor Status page

To confirm the content the above Event will find, you can enter the search query in SharePoint to return the results. When I entered this query, it returned 2 documents, as expected.

compliancetag:”Contoso Contract” AND complianceassetid:CN9999

You can also go to Content Search in the Security & Compliance Center to search across your entire tenant for the above Compliance Tag and Compliance Asset ID.

My Observations

With event-driven configuration in Office 365, you will really need to understand the relationship between labels, event types, asset IDs and events. Once again, the Information Management team in your organization will need to work closely with the Security & Compliance Administrator to configure the event labels. In some cases, this will be the same person while in others, these roles will be in different teams. There will also have to be a concerted effort to plan and define the Asset IDs to be used across your tenant to be able to apply any event-driven retention.

Another big consideration is deciding who will be responsible for entering the events into the Data governance section of the Security & Compliance Center. As you can imagine, this could be a very large undertaking in an organization so make sure you plan ahead for that extra workload.

No one said compliance was easy.

Thanks for reading.


Credit: Photo by Roman Bozhko on Unsplash



  1. Thanks Joanne, great walk-through. Love your closing line! Really looking forward to trying this out and showing our records and compliance team how SPO can help them

    1. Hi Josh. Event-driven retention is part of Advanced Data Governance which, at this time, is included in Enterprise E5 only.

      1. Hi Joanne,

        Trying this out with a new E5 trail subscription. Not able to see the unified labelling nor the event based retention options


      2. Hi Reza,
        The unified labeling is still in private preview. The event based retention was in preview (which is what I built my blog post on) but has recently been released as GA. I can’t see it in my E5 tenants just yet, but it will likely be rolling out very soon. Check your tenant’s message center.

    1. Hi Reza…I just read in my client’s message center… Event-based retention should be rolled out globally by end of May.


      1. Great !!!

        Joanne one more question:-
        E5 would cover event based retention
        However there is the concept of unified labeling – which merges the features of both AIP and Labels within the security and compliance center. When will this be GA and is this applicable for E3?

      2. Hi Reza,
        I can’t find a date for when it will be GA. It’s currently in private preview, hopefully public preview soon and we’ll be able to try it out. AFAIK this is applicable for E3.

  2. Had a go at setting this up myself, following your guide, but can’t seem to get it to work. Applied the event-linked label to some Sharepoint list items and then fired an event linked to the correct type, but it shows no files or sites processed when the status has since changed to ‘success’.

    I can still find these files in a content search for the tag / asset ID though – it’s just the event itself that doesn’t find them.

    You mention about this being an E5 thing (we’re on E3), but I assumed if the create event is available for us (and we can do the exact set up as above) then it means it should also work on E3?

    Very confused right now.

    1. Hi James,
      I apologize, I think I had the license comment wrong. That had more to do with auto-applying labels, which as far as I know is an E5 feature. If you’re seeing the option with E3, that’s great! My bad.

      As for the event based issue you’re having… I recall having to wait quite a while (days) for the numbers to show up even though I think the status said success. Not sure how long you’ve waited so that might not be the case for you. If you feel you’ve waited long enough, I’d open a ticket with Microsoft.

      1. Hello Joanne and James,

        I noticed the same “issue”. In my case it took nearly one week for the numbers to show up. So be patient, as it will work ūüôā

  3. Hi Joanne. Great post. E3 is working for me but it takes days. I’m using ‘=’ for an exact match rather than ‘:’ contains (which could including the wrong items, i.e. CN123 and CN1234) and ‘=’ seems to be working. Have you tested this? Also, I would like to set a default value for the compliance asset id say for the library and folder, as users won’t bother and it is standard behaviour for the label. I’ve put this on Microsoft user voice. Your views / votes would be appreciated. Thanks Keith

Leave a Reply

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