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)

---

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.

 

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.

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

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

Create the event

It’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

 

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.

• New-ComplianceRetentionEvent
• New-ComplianceRetentionEventType
• New-ComplianceTag

---

Monitor

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.

 

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.

-JCK

---

Credit: Photo by Roman Bozhko on Unsplash