Set advanced filters

  • Last update on September 27th, 2024

Table of Contents

By default, Configuration Manager will not export certain configurations that are not assigned or referenced by other configurations in the tenant. This can include users, groups, distribution groups, mailboxes, and other similar configurations.

If you would prefer to have Configuration Manager export these configurations, this can be done by applying advanced filters. 

Advanced filters require knowledge of the Configuration Manager repository structure and familiarity with Microsoft APIs and JSON schema.

These filters should only be set if you understand this functionality! If in doubt, please contact the support team for assistance before setting advanced filters.

 

Setting advanced filters

Setting advanced filters is done in Azure DevOps by manually updating the

config.tenant.json

file in the tenant repository. 

To do this:

  • Navigate to Azure DevOps
  • Select “Configuration Manager project” > “Repos” > select the desired tenant > “Source” > “Resources” > config.tenant.json > Edit

 

Changes made to the baseline tenant will apply to all tenants downstream from that baseline. 

If you would prefer to set a filter on a specific downstream tenant only, you should set the filters in that tenant's repository, not the baseline.

 

For reference, a new or unused config.tenant.json file typically looks like this (though it may look different across different environments, don't worry if your file looks different):

{
  "ResourceContext": {
      "M365Licenses": "[]"
  },
  "ResourceProcessing": {
      "IncludeFilters": [],
      "ExcludeFilters": []
  }
}

These filters should be added at the top-level of the file, outside of

ResourceContext

and

ResourceProcessing

Please note that you must maintain the correct JSON schema, or you may break the Sync!

 

Below is an example of a config.tenant.json file with advanced filters to export all users and groups from the tenant:

{
  "ResourceContext": {
      "M365Licenses": "[]"
  },
  "ResourceProcessing": {
      "IncludeFilters": [],
      "ExcludeFilters": []
  },
  "Users:Filter": "userType eq 'Member' or userType eq 'Guest'",
  "Groups:Filter": "mailEnabled eq false or mailEnabled eq true"
}

Example filters

Below are examples of filters that can be used to customize the Sync. This is not an exhaustive list. You may need to customize these filters to achieve the desired results.

Users filters

To export all users in the tenant:

"Users:Filter": "userType eq 'Member' or userType eq 'Guest'"
 
 

Group filters

To export all groups in the tenant:

 "Groups:Filter": "mailEnabled eq false or mailEnabled eq true"

To specify groups to export, use the following filter:

"Groups:Filter": "startswith(displayName, 'Good employees') or startswith(displayName, 'Mediocre employees')
 
 

Directory Roles filters

To export Directory Roles in a tenant:

"DirectoryRoles:Filters": "displayName eq 'Global Administrator'"

Note:

  • Directory roles are exported if they are referenced by other configs
  • MSGraph only accepts the 'equals' query parameter for this filter, meaning you can only list one directory role per filter. To export multiple directory roles, you must add multiple filter lines, one for each role you wish to export. Refer to the list directoryRoles article in the Microsoft documentation for details.
 
 

Mailboxes filters

To export all mailboxes in the tenant:

"Mailboxes:Filters": [
"Alias -like '*'"
]
 
 

Distribution Groups filters

To export all distribution groups:

"DistributionGroups:Filters": [
"Name -like '*'"
]

Note:

  • Distribution group members are only exported if they are referenced by other configs
  • To export all distribution group members, you would need to add the filter for Distribution Groups and Mailboxes. 
 
 

Service Principal filters

To export only referenced service principals, which will prevent exporting service principals that are not referenced by other configurations:

"ServicePrincipals:OnlyReadReferencedServicePrincipals": true
 
 

Group Members filters

To export groups without their members:

"Groups:MembersFilter": "startswith(displayName, 'donotexportany')"

To export specific group members:

"Groups:MembersFilter": "startswith(displayName, 'membername')"

To export all group members:

"Groups:MembersFilter": ""
 
 

 

 

Related Articles

DID THIS PAGE HELP YOU?