SharePoint custom metadata and Event-based Retention

Reading Time: 5 minutes

I’ve previously blogged about event-based retention and how you can use the automatically-generated ComplianceAssetId column to set a unique identifier for a set of documents (Automate Compliance Asset Id on SharePoint Documents). This pre-configured, unique identifer can be a project #, student #, patient #, etc. The ComplianceAssetId is visible on a library when an event-based retention label has been associated to the library.

Leverage your custom metadata in SharePoint to trigger event-based retention! Click To Tweet

Refer to a post by Martin Lingstuyl here: Blimped | Working with Purview event-based retention using code where he explains how to work with an event-based retention label and the ComplianceAssetId all thru code!

What if you don’t want to use the ComplianceAssetId, but instead leverage an existing piece of custom metadata you already have? You can do this!

Examples:

---

To demonstrate how event-based retention could be automated using custom metadata, here are the steps using one of the examples above, Legal Case #:

Step 1: Create the home for the records

Create a SharePoint site to house the content you want to store the event-based content in. To be clear, this can be any kind of SharePoint site – whether it was created as part of a Microsoft Teams, an Outlook group, or a standalone SharePoint site)

For the Legal Case file… I created a Legal Affairs SharePoint site:

---

Step 2: Create the event type

All events must be associated with an event type. The type of event is, in turn, associated with a retention label to drive the retention. The event type has no settings other than a name and description. It is really just used to associate an event with the retention label. In the Office 365 Security & Compliance center, event types are defined under Records Management… Events… Manage event types.

For the Legal Case file… I created a Case Settled event type

---

Step 3: Create the event-based retention label

Create a retention label pointing to the above event type. Depending on the retention requirements, you may also configure a disposition review. Publish the label to the location where your records reside.

For the Legal Case file… I created a Legal Case File retention label based on an event and publish to the Legal Affairs SharePoint site.

---

Step 4: Create Document set content type with retention metadata

* To be clear, you don’t have to use a document set for event-based retention, but it works extremely well as you’ll soon read. 🙂

Create a custom document set content type to identify your set of documents. Ensure you have at least 2 pieces of metadata defined on the Document Set: one to uniquely identify the set of documents and one to trigger retention.

For the Legal Case file… I created a Legal Case File document set and ensured I had these 2 columns (I had others as well, however they have nothing to do with retention)

• CaseNo
• LitigationStatus

---

Step 5: Default the unique identifier for all documents

Configure the document set to automatically set the unique identifier on each document within the document set. This means once that column is set at the Document Set level, it will be automatically synchronized to all documents added within. You do this in the Document Set settings on the site content type.

For the legal case file… I ensured the CaseNo column was shared.

---

Step 6: Document library settings

Assign the custom Document Set to the library on your SharePoint site and configure the retention label to be default for the library. Both are done in library settings.

For the Legal Case file… I added the custom Legal Case File document set into the Legal Case File library on the site. I then set the default retention label to be the Legal Case File event-based retention label created in Step 3.

---

Step 7: Create/map managed property in Search Schema

When the event is triggered, it will find the content relating to the event using search, and specifically, managed properties. You must ensure a managed property has been created in the search schema mapped to the crawled property for the unique identifier of your document set. **Load some test data in your library to ensure the crawled property will be generated.

For the Legal Case file… I loaded some test data in the library and waited for the crawl process to create the crawled property for the column CaseNo which is ows_CaseNo. Once created, I mapped a managed property, CaseNumber, to it. The managed property will be used in the query for the event in Step 8.

---

Step 8: Trigger the retention event

When the time comes to trigger the retention event, it can be done either manually (not scalable) or automated with a Power Automate workflow. It should be triggered off a metadata value on your Document Set. Provide a unique name for the event, the event type it’s associated with and the query condition for the event.

For the Legal Case file… I built a Power Automate workflow to be triggered off a LitigationStatus of Closed. The workflow makes a REST API call, ComplianceRetentionEvent, passing in the following values: (circled in blue)

• Event title: “Case File – <CaseTitle>”
• event type (Case Settled)
• query (CaseNumber:<CaseNo>)
• Retention start date

---

Step 9: Monitor the retention status

The retention event engine will find all content for the event you triggered, matching anything tagged with the CaseNo and the retention label Legal Case File and then start retention on it. The number of items found matching the criteria will be reflected in the event status.

For the Legal Case file… the retention label Legal Case File was published to 1 SharePoint site so the only items found were for the CaseNo specified in the REST API call (2019-0012 in this example) which was 5 items. You can view these details under Records management… Events:

You will also see a column populated on all documents in the document library matching the condition called Label Event Date which will match the event date in your trigger.

And that’s all there is to it! 🙂

 

 

---

Some good things to know…

Did you know? Retention works at the granular document/email level. It will never delete the containing folder. In the above solution, once the retention period has been met and the documents within the document set have been deleted, the document set “shell” will still exist. If you wanted to remove the document set, this would have to be done manually or with a custom solution.

The same goes for documents deleted within a library. The library or folders within will never be deleted.

Thanks for reading!

-JCK

---

Credit: Photo by Dominika Roseclay from Pexels