When working with Microsoft 365 Retention, a core task is to choose the content to apply the policies. There are two types of scopes “Adaptive” and “Static.”

An adaptive policy automatically updates where it applies based on attributes or properties. Static policies apply to content in a fixed set of locations and must be manually updated if those locations change.

All scopes can apply to the following list of locations. “Static” scopes utilize selected locations, filtered as includes and exclude. “Adaptive” scopes only allow selection of locations based on supported query properties available within locations.

  • Exchange email
  • SharePoint sites
  • OneDrive accounts
  • Microsoft 365 Groups
  • Skype for Business
  • Exchange public folders
  • Teams channel messages
  • Teams chats
  • Teams private channel messages
  • Yammer community messages (Preview)
  • Yammer user messages (Preview)

Using “Adaptive” scopes requires creating; they are available within retention policies, limiting the locations based on the selected scope.

For example, selecting “Users” populates the dropdown with only properties found within Azure Active Directory Users. Selecting the other options filters to just those.

The full list of properties is available here:

https://docs.microsoft.com/en-us/microsoft-365/compliance/retention-settings?view=o365-worldwide#configuration-information-for-adaptive-scopes

The filtering options allow the creation of constructed queries based on properties and values.

When creating a Retention policy, the “Adaptive” scopes need to exist first. Once selected within the policy, only supported locations become available.

All other options disappear from the retention policy location picker to ensure only the supported locations remain. The rest of the retention policy creation process is normal.

As you all know by now, I advocate for using PowerShell for any many things as possible. This scenario included.

To create an “Adaptive Scope,” you can use the “New-AdaptiveScope” command. It uses the following properties: NameCommentLocation TypeFilter Conditions, and Raw Query.

The “Filter Conditions” is the raw structure you would create using the builder, and the “Raw Query” is an “OPATH” query. For example, if we want to query users by department, you can construct a simple query like this “‘Human Resources Equals Department.'” 

Create a Simple Adaptive Scope using Single Filter

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement

Connect-IPPSSession

$name = "PowerShell Adaptive Scope Single Filter"
$comment = "PowerShell Adaptive Scope Single Filter"
$locationtype = "User"

$filterconditions = @{
	"Value" = "Human Resources"
	"Operator" = "Equals"
	"Name" = "Department"
}

New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

Create an Adaptive Scope using Multiple Filters

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement

Connect-IPPSSession

$name = "PowerShell Adaptive Scope Multiple Filter"
$comment = "PowerShell Adaptive Scope Multiple Filter"
$locationtype = "User"

$filterconditions = @{
	"Conditions" = @(
		@{
			"Value" = "Human Resources"
			"Operator" = "Equals"
			"Name" = "Department"
		},
		@{
			"Value" = "Chicago"
			"Operator" = "Equals"
			"Name" = "City"
		}
	)
	"Conjunction" = "And"
}

New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

Now that the adaptive scope exists, you can use them within standard retention policies.

Creating the adaptive scope using either the “Filter Conditions” or the “Raw Query” requires the usage of supported properties. A more advanced scope could look like this:

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement

Connect-IPPSSession

$name = "PowerShell Adaptive Scope Multiple Advanced Filter"
$comment = "PowerShell Adaptive Scope Multiple Advanced Filter"
$locationtype = "User"


$filterconditions = @{
	"Conditions" = @(
		@{
			"Conditions" = @(
				@{
					"Value" = "Human Resources"
					"Operator" = "Equals"
					"Name" = "Department"
				},
				@{
					"Value" = "Chicago"
					"Operator" = "Equals"
					"Name" = "City"
				}
			)
			"Conjunction" = "And"
		},
		@{
			"Conditions" = @(
				@{
					"Value" = "Wash"
					"Operator" = "StartsWith"
					"Name" = "StateOrProvince"
				},
				@{
					"Value" = "New"
					"Operator" = "StartsWith"
					"Name" = "StateOrProvince"
				}
			)
			"Conjunction" = "Or"
		},
		@{
			"Value" = "Security Analyst"
			"Operator" = "StartsWith"
			"Name" = "Title"
		}
	)
	"Conjunction" = "And"
}

New-AdaptiveScope `
	-Name $name `
	-Comment $comment `
	-LocationType $locationtype `
	-FilterConditions $filterconditions

As you can see, PowerShell brings a great experience for creating adaptive scopes. Standard Microsoft 365 PowerShell commands for querying users, sites, mailboxes, and groups allow us to validate what we are searching for. Then we can use that query either as the “Raw Query” or convert it to a “Filter Condition.”