SharePoint Adaptive Scope Retention Label Policy | A Walk-thru

Reading Time: 9 minutes

Have you heard about Adaptive Scopes? It’s a new Microsoft Information Governance and Records Management (IG/RM) feature now in Public Preview (refer to Roadmap ID 70578). I’m really excited about this new feature because I think it addresses many of the challenging retention scenarios I see with customers looking to apply IG/RM controls at scale across their tenant.

Microsoft’s recent webinar provides walk-thru demos of the new Adaptive Scope feature for several common use-case SharePoint scenarios. Check it out: Building Advanced Queries for SharePoint Sites with Adaptive Policy Scopes

A few key things about adaptive scopes to understand:

  • They are scopes, not policies
  • They are referenced when publishing either retention policies or retention label policies
  • There will now be 2 types of scopes:
    • Static (what we’ve had up until now)
    • Adaptive (new)
  • There are 3 types of adaptive scopes:
    • User | based on Azure AD attributes
    • Site | based on SharePoint site properties
    • Microsoft 365 Group | based on Azure AD attributes
Adaptive scopes will help organizations gain compliance across their environment in a flexible, scalable, automated, and targeted way. Click To Tweet

Check out my Collection of posts to demonstrate how to use Adaptive Scopes to address common retention requirements I see in the field. Each post in the collection will demonstrate how to use an Adaptive Scope in a slightly different way.

This is the second post in the collection. 

The Retention Requirement ask for this post:

“Retain all content on Legal Matter sites for 5 years after the Legal Matter has concluded. All content must go thru a disposition review once the retention period has been met.”

To accomplish this, I’ll walk-thru how to use an Adaptive Scope with an auto-apply Retention Label Policy. I’ll show how to automatically apply a 5 year (5 days for my test) retention label, Legal Matter, to content on concluded Legal Matter SharePoint sites without having to manually add each Legal Matter site URL to the label policy once the matter is concluded.

Combining an adaptive scope with an auto-apply retention label policy is a powerful combination and opens up a world of possibilities for applying retention labels in a scalable, flexible, and automated way.

Tip: the implementation of this solution will be easier if you have some SharePoint Admin/Search experience.

High-level steps to make this happen:

  1. The Legal Matter SharePoint site setup
  2. The SharePoint search schema
  3. The Adaptive scope
  4. The Retention Label and Auto-apply Label Policy
  5. The end result

Let’s dig in.

Step 1: The Legal Matter SharePoint Site Setup

In this example, I’m using automation in my tenant to provision Legal Matter sites for my Law Firm customer. There are many ways to auto-provision a site and I won’t cover that in this post. Please refer to another post of mine, Auto-provisioning SharePoint Sites and Teams: A blog post list, where I reference several ways of doing it.

I need to use a SharePoint Adaptive scope for this retention requirement. The salient point during the provisioning process to allow us to use a SharePoint Adaptive Scope is to apply some custom properties to the Legal Matter site.

There are numerous ways you could kick off the provisioning process (SharePoint list, Microsoft Form, Power Automate Flow, custom app, etc.); however, for purposes of this post, I’ll skip over those details as they aren’t relevant to the Adaptive scope and retention configuration. As long as the process stores values you can use in the site property bag, you’re gold.

During the provisioning process, I’ll add a status to the Legal Matter site to indicate the overall status of the matter… either Active or Concluded. The status will be set to Active when the site is initially provisioned and Concluded when the legal matter is concluded. I do this because I only want concluded Legal Matter sites to be included in the Retention Label auto-apply policy.

Wondering how to set a property at the site level? You add a value in the site property bag during the site provisioning process. By setting a property at the site level, you can control the overall status of the entire site. In this way, once the legal matter is concluded, the status property on the Legal Matter site’s property bag is set to Concluded.

Updating the property bag of a SharePoint site is relatively straight forward once you know a few things. The site property bag is a dictionary of key-value pairs to define properties of the site… we want to add a few custom ones! To be clear, the site property bag can be used for far more than just Adaptive scopes; however for this post, that’s what I’m using them for. 🙂

I used PnP PowerShell in my provisioning solution to set 2 properties on the Legal Matter site: (in addition to enabling scripts prior to setting the property bag values, you should also disable scripts when you’re done!)

  • Property: customSiteType set to “LegalMatterSite”. This property is used to identify Legal Matter sites across the tenant. This property will be used in the Adaptive scope condition to only include sites of this type.
  • Property: customSiteStatus set to “Active” when the site is provisioned; “Concluded” when the legal matter is concluded. This property will be used in the Adaptive scope condition to determine if the Legal Matter site should be included in the Retention policy. We only want those with a status of Concluded to be included.

To demonstrate, I provisioned 5 modern team sites to represent 5 Legal Matter sites and set the 2 custom properties shown above on each site as follows:

  • Legal Matter 111: customSiteType = LegalMatterSite, customSiteStatus = Concluded
  • Legal Matter 222: customSiteType = LegalMatterSite, customSiteStatus = Active
  • Legal Matter 333: customSiteType = LegalMatterSite, customSiteStatus = Concluded
  • Legal Matter 444: customSiteType = LegalMatterSite, customSiteStatus = Active
  • Legal Matter 555: customSiteType = LegalMatterSite, customSiteStatus = Concluded

With this setup, 3 of the 5 Legal Matter sites are Concluded and, therefore, will be the only 3 sites included in the adaptive scope.

I’ve uploaded some test content in each of the sites above and have joined them all to a Legal Matter Hub to make verification a bit easier:

Step 2: The SharePoint Search schema

The hard part is done! Setting up the search schema is the same as what you’re used to when defining managed properties for custom SharePoint columns, except this time we’re using crawled properties generated from custom site property bag properties instead of SharePoint columns.

Browsing to the tenant-level search schema, I see 2 crawled properties have been automatically generated that map directly to the 2 custom property bag properties: customSiteType and customSiteStatus.

I need to map each of these to a pre-built RefinableString managed property (00-99 only!) in the search schema so they can be added to the Adaptive scope condition. I pick RefinableString50 and RefinableString51 respectively. (**this post is using the same managed properties as defined in my previous post, so I don’t have to do this step – it’s already done!)

I initiated a re-index of the Legal Matter sites. This is only required in the setup step so I can verify the search results prior to using the RefinableString managed properties in the Adaptive scope condition.

I recommend validating the KQL query before using it in your Adaptive scope condition. For this particular query, it will work by entering it in either the Microsoft Search box (shown below) or using Content Search in the Compliance Center. As a general rule of thumb, ensure the query will return expected results from Content Search as this more closely aligns with the search used by Compliance features.

In both locations, this is the query to validate to meet our conditions.

RefinableString50 = LegalMatterSite AND RefinableString51 = Concluded

Microsoft Search:

Content Search:

… in both cases, it correctly returns the 3 concluded Legal Matter sites so I’m confident moving forward with my conditions when defining the adaptive scope. 

Step 3: The Adaptive Scope

You’ll see the Adaptive scopes tab in 2 places in the Compliance Center: within Information governance and within Records management. Two important things to know about this:

  • whichever place you create the adaptive scope, it will appear in both places once saved
  • the adaptive scopes can be used in both retention policies and retention label policies

In this post, I’ll be working in the Records management feature to build and auto-apply a retention label so I navigate to Records Management… Adaptive scopes:


I’ll create a scope called Concluded Legal Matters Site Scope:


And I’ll create a SharePoint sites scope because I want to use my site properties as the condition:

I’ll add my 2 RefinableString managed property conditions so I’m only including Concluded Legal Matter sites in this scope:


The Adaptive scope takes a bit of time to process in the backend to bring in the relevant locations that match the query. In my example, within a day, the 3 sites were included in the scope when viewing the scope details; however, please know you don’t have to wait for the sites to show in the below list before using the Adaptive scope in a retention policy or label policy.

Step 4: The Retention Label and Auto-apply Label Policy

If you recall, this is the retention requirement we’re implementing:

“Retain all content on Legal Matter sites for 5 years after the Legal Matter has concluded. All content must go thru a disposition review once the retention period has been met.”

I’ll create a new retention label, Legal Matter TEST, with the retention requirements to retain for 5 days (my shortened test period). I will configure it to start retention based on when it was labeled which will equate to when the legal matter was concluded and will require a multi-step disposition with both the Legal Team followed by the Records Managers:

Different than a retention policy, I want a retention label to be applied to individual items within the Legal Matter site. I want this because I require a disposition review on content within. To make this happen, there are 2 important settings in the retention label policy.

The first setting is the auto-apply condition to apply the retention label. There are many ways of doing this – I’m targeting specific file types to apply the retention label. I’m referencing the out-of-the-box FileExtension property. The query below will apply the retention label to any content with these file types across all libraries on the site. You can build your query to suit your own needs.


I then select Adaptive as the type instead of Static:

I’ll “scope” the retention label policy to the Adaptive scope created in the previous step, Concluded Legal Matters Site Scope:


… and last, but not least, I select the retention label, Legal Matter TEST, to auto-apply for this label policy:


When I look at the label policy summary, I can see it is scoped to my Adaptive scope:

Step 5: Wait and watch for the end result

Once the retention label policy is published and the adaptive scope reflects the correct scoped list of sites, the actions configured by the retention label policy begin (Remember, auto-applying a retention label can take up to 7 days so patience is required on this step).

In this example, all sites include in the Adaptive scope (the 3 concluded Legal Matter sites) will have their content labeled with the Legal Matter TEST retention label. Image below shows 1 of the 3 sites, Legal Matter 111, with the retention label applied to match the auto-apply condition. You can see it didn’t apply the label to the files NOT matching my condition. You could also use size>0 if you wanted them included (something I’ll verify in the next post).

Closing thoughts…

There is tremendous value in this model to scope retention in a flexible, scalable, and automated way. As I come across other use cases while working with customers, I’ll share the setup and configuration in the collection of posts.

If you have an example you’d like me to cover, share in the comments!

Thanks for reading.



Leave a Reply

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