In my last post on Adaptive scopes, I walked through the creation of them using PowerShell. If you have not read this yet, then go here:

https://helloitsliam.com/2021/11/12/creating-adaptive-scopes-using-powershell

A key component of adaptive scopes is the properties available for Users, SharePoint sites, and Microsoft 365 Groups. For example, if using a “User” adaptive scopes, the supported attributes are First Name, Last Name, Display Name, Job title, Department, Office, Street Address, City, State or Province, Postal Code, Country or Region, Email Addresses, and Alias.

So the question then is, what happens if I want to use other properties and values?

Good news! for an adaptive scope for “Users,” you can use the Exchange custom attributes named “CustomAttribute1” to “CustomAttribute15.”

For an adaptive scope for “SharePoint Sites,” you can use the SharePoint custom properties named “RefinableString00” to “RefinableString99.”

For an adaptive scope for “Microsoft 365 Groups,” you can use the Exchange custom attributes named “CustomAttribute1” to “CustomAttribute15.”

Property names within SharePoint are based on managed properties, whereas the attributes for users and groups are filterable recipient properties within Azure Active Directory.

When building adaptive scopes, there are two ways to create the queries. The first is to use the query attribute/property window, which allows you to construct queries from the drop-downs. It is the most straightforward approach, allowing the flexibility of using different operators, using “AND” and “OR” queries, and grouping.

The second approach uses the “Advanced Query Builder,” a text box to paste the query you need. In the image above, you can see the query displayed in the “Query Summary.” If wanted, you can copy this query and switch to the “Advanced Query Builder” and paste it into the text field.

This querying aims to limit the scope of users, sites, and groups when assigned to retention policies. Often, records management requires the retrieved content and data to be filtered extensively to store the necessary items. An adaptive scope goes a long way to assist with this, including identifying newly added content that meets the adaptive scope query. The standard supported properties are excellent, and as you can see, you can create reasonably complex properties. However, the custom attribute and property fields are essential when you need to filter on custom values.

Adaptive scopes of type “Users” and “Groups” support the simple query building and OPATH queries; however, “SharePoint Site” scopes utilize “KQL” queries, not “OPATH” queries. The key to using any custom properties is to ensure their population within Azure Active Directory, Exchange Online, or SharePoint Online. You will be using property bag values mapped to the managed properties for SharePoint Online, which can take a few days to update and become searchable.

Example: Updating Custom Property for a User and Group

$mailbox = Get-Mailbox "AdeleV"

Set-Mailbox $mailbox.Id `
	-CustomAttribute1 "PowerShell" `
	-CustomAttribute2 "Top Secret" `
	-CustomAttribute3 "058347654"

To check the values now exist within the mailbox, use the following command.

$mailbox | Select-Object Id, CustomAttribute1, CustomAttribute2, CustomAttribute3

To validate the ability to filter on these new values, execute any of the following commands.

Get-Mailbox | Where-Object { $_.CustomAttribute1 -eq "PowerShell" }
Get-Mailbox | Where-Object { $_.CustomAttribute2 -eq "Top Secret" }
Get-Mailbox | Where-Object { $_.CustomAttribute3 -eq "058347654" }

To perform the same task for a Microsoft 365 group, you can use these commands.

$group = Get-UnifiedGroup -Identity "Operations"
Set-UnifiedGroup $group.Id `
	-CustomAttribute1 "PowerShell" `
	-CustomAttribute2 "Top Secret" `
	-CustomAttribute3 "USA"

To check the values now exist within the mailbox, use the following command.

$group = Get-UnifiedGroup -Identity "Operations"
$group | Select-Object Id, CustomAttribute1, CustomAttribute2, CustomAttribute3

To validate the ability to filter on these new values, execute any of the following commands.

Get-UnifiedGroup | Where-Object { $_.CustomAttribute1 -eq "PowerShell" }
Get-UnifiedGroup | Where-Object { $_.CustomAttribute2 -eq "Top Secret" }
Get-UnifiedGroup | Where-Object { $_.CustomAttribute3 -eq "USA" }

Managing the custom attributes for Exchange online for users and groups is very simple, and you can filter them instantly.

Example: Updating Custom Property for a SharePoint Site

Working with SharePoint sites is a little more complicated. The properties are called “Property Bag” items and are saved directly to a site. The main issue is the time it takes to convert the property bag values into managed properties. It relies on SharePoint Search to ensure the properties map to managed properties and is searchable.

Adding property bag values is done using PowerShell like this.

Install-Module -Name PnP.PowerShell
Import-Module -Name PnP.PowerShell

$siteurl = "https://m365x.sharepoint.com/sites/ContosoBrand"
Connect-PnPOnline -Url $siteurl -Interactive

Set-PnPSite -DenyAndAddCustomizePages $false

Set-PnPPropertyBagValue -Key "pgCreation" -Value "PowerShell"
Set-PnPPropertyBagValue -Key "pgSecurity" -Value "Top Secret"
Set-PnPPropertyBagValue -Key "pgCountry" -Value "PowerShell"

Set-PnPSite -DenyAndAddCustomizePages $true

NOTE: Remember to set the “DenyAndAddCustomizePages” property back to “True.”

To check the property bag is updated, you can execute either of these commands.

Get-PnPPropertyBag
Get-PnPPropertyBag -Key "pgCreation"
Get-PnPPropertyBag -Key "pgSecurity"
Get-PnPPropertyBag -Key "pgCountry"

Next, these properties need indexing within SharePoint so we can convert them into managed properties. It can take some time due to waiting for SharePoint to index the property bag values, so they are available to map to managed properties.

You can view crawled and managed properties within the SharePoint admin center. Once the crawled properties display in the list, you can then navigate to the “RefinableString” property and associate the crawled property.

View Crawled Properties

https://{domain}-admin.sharepoint.com/_layouts/15/searchadmin/ta_listcrawledproperties.aspx?level=tenant

Edit Managed Property Mapping

https://{domain}-admin.sharepoint.com/_layouts/15/searchadmin/ta_managedproperty.aspx?property=RefinableString50&level=tenant

With this in place, you can now create the adaptive scope needed based on the properties.

Create Adaptive User Scope from Custom Attributes

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
 
Connect-IPPSSession
 
$name = "PowerShell User Adaptive Scope Multiple Custom Filters"
$comment = "PowerShell User Adaptive Scope Multiple Custom Filters"
$locationtype = "User"
 
$filterconditions = @{
	"Conditions" = @(
		@{
			"Value" = "PowerShell"
			"Operator" = "Equals"
			"Name" = "CustomAttribute1"
		},
		@{
			"Value" = "Top Secret"
			"Operator" = "Equals"
			"Name" = "CustomAttribute2"
		},
		@{
			"Value" = "058347654"
			"Operator" = "Equals"
			"Name" = "CustomAttribute3"
		}
	)
	"Conjunction" = "Or"
}
 
New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

Create Adaptive Group Scope from Custom Attributes

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
 
Connect-IPPSSession
 
$name = "PowerShell Group Adaptive Scope Multiple Custom Filters"
$comment = "PowerShell Group Adaptive Scope Multiple Custom Filters"
$locationtype = "Group"
 
$filterconditions = @{
	"Conditions" = @(
		@{
			"Value" = "PowerShell"
			"Operator" = "Equals"
			"Name" = "CustomAttribute1"
		},
		@{
			"Value" = "Top Secret"
			"Operator" = "Equals"
			"Name" = "CustomAttribute2"
		},
		@{
			"Value" = "USA"
			"Operator" = "Equals"
			"Name" = "CustomAttribute3"
		}
	)
	"Conjunction" = "Or"
}
 
New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

Create Adaptive Site Scope from Custom Properties

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
 
Connect-IPPSSession
 
$name = "PowerShell Site Adaptive Scope Multiple Custom Filters"
$comment = "PowerShell Site Adaptive Scope Multiple Custom Filters"
$locationtype = "Site"
 
$filterconditions = @{
	"Conditions" = @(
		@{
			"Value" = "PowerShell"
			"Operator" = "Equals"
			"Name" = "RefinableString50"
		},
		@{
			"Value" = "Top Secret"
			"Operator" = "Equals"
			"Name" = "RefinableString51"
		},
		@{
			"Value" = "058347654"
			"Operator" = "Equals"
			"Name" = "RefinableString52"
		}
	)
	"Conjunction" = "Or"
}
 
New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

Now you wait for a few days, allowing the process to validate the queries and return some results. You can click the “Scope details” button for any scopes, which will take you to the results page to validate it worked as expected. Do not assign scopes to any policies until you are 100% sure the results are correct.

Final Thoughts

Do not rush into using Adaptive scopes. Take time to define what you need, populate existing property and attribute values, and then define any custom ones, including those requiring indexing within search. Due to the nature of how the scopes work, plan it out first, write down the mappings and then create what you need.