Skip to main content

Audience Targeting

ABSTRACT
An audience targeting rule could be applied to a template to define who can access and therefore use it, based on the user profile data. Intrinsically, targeting rules are a combination of tags and expressions that are evaluated against a user profile to determine if a template is shown or not.

Available tags

Targeting rules can use user profile information through the following tags:

TagDescription
user.displayNameUser full name (for example "Bob Dirac".)
user.userPrincipalNameUser UPN. In Active Directory, a User Principal Name (UPN) is the name of a system user in an email address format. A UPN (for example: "bob.dirac@contoso.onmicrosoft.com") consists of the user name (logon name), separator (the @ symbol), and domain name (UPN suffix).
Important: A UPN is not the same as an email address. Sometimes, a UPN can match a user's email address, but this is not a general rule.
user.mailUser email (for example: "bob.dirac@domain.com").
user.preferredLanguageUser preferred language in Microsoft 365.
Language and locale codes are limited to those in the ISO 639-1 standard.
user.givenNameUser given name (for example: "Bob").
user.countryUser country (for example: "France").
user.companyNameUser company name (for example: "Contoso").
user.departmentUser department (for example: "Marketing").
user.cityUser city (for example: "Paris").
user.jobTitleUser job title (for example: "Product Manager").
user.surnameUser surname (for example: "Dirac").
user.usageLocationOffice 365 usage location. (for example: "US")
Rely on the ISO 3166-1 alpha-2 country codes....
user.groups.directAll the groups that the user is a DIRECT member of.
Case sensitivity

Be careful: These tags are CASE-SENSITIVE and therefore must be always used lower-cased.

Examples

In combination with tags, targeting rules can use any standard JavaScript operator and function. This section provides some typical examples, from the simplest to the most complex one, to target your templates to specific audiences in an organization.

Comparison operators

To compare two values, your expression can use any standard JavaScript comparison operator.

// From France
user.country === 'FR'
// From any country except from Germany
user.country !== 'DE'
Evaluation

N.B: The template will be shown to a user only if the expression is evaluated as true

Combining multiple criteria

Rules follows the standard JavaScript operator precedence, so you can combine multiple rules in one expression.

// From France or Belgium, member of the Marketing Department
( user.country === 'FR' || user.country === 'BE' ) && user.department === 'Marketing'

Functions

As part of your rules, you can use any standard JavaScript function, for instance strings methods, or for more advanced scenarios, regular expressions.

// English speakers from any country
user.preferredLanguage.includes('en-')
// users with @contoso.com or @contoso.fr in their email domain name
user.mail.includes('@contoso.com') || user.mail.includes('@contoso.fr')

Using groups membership

The user.groups.direct tag gives you access to all the groups that the user is a DIRECT member of, as an array of groups objects. Therefore, you can use any standard JavaScript array function for your evaluation.

There are several types of groups, that can be differentiated by their @odata.type property:

Note

The response object shown here might be shortened for readability. All the default properties are returned for each group in an actual call.

{
"@odata.type":"#microsoft.graph.directoryRole", // Standard Azure AD groups, such as the admin roles from your Microsoft 365 environment
"id":"3b4b0f4e-d037-4116-bd0e-1a2173d95d5a",
"deletedDateTime":null,
"description":"Company Administrator role has full access to perform any operation in the company scope.",
"displayName":"Global Administrator",
"roleTemplateId":"72e90394-69f5-4237-9190-012177145e10"
}
{
"@odata.type":"#microsoft.graph.group", // Microsoft 365 groups, associated with a team or a SharePoint site.
"id":"e9090752-4430-4361-8594-e6ce98a7fbfa",
"deletedDateTime":null,
"classification":null,
"createdDateTime":"2020-08-04T15:39:08Z",
"description":"A fantastic group!!!",
"displayName":"Onboarding",
"groupTypes":["Unified"],
"mail":"Onboarding@contoso.com",
"mailEnabled":true,
"mailNickname":"Onboarding",
"preferredDataLocation":null,
"preferredLanguage":null,
"resourceProvisioningOptions":["Team"],
"visibility":"Private"
}

In this example, we're testing user membership by checking if one of its groups contains the word "Onboarding" in its display name:

// Is a member of an "Onboarding" group
user.groups.direct.some(group => group.displayName.includes('Onboarding'))
Case sensitivity

Be careful, evaluations are case-sensitive. Therefore to make sure your evaluation work independently of the case, you can use the toLowerCase function, such as: group.displayName.toLowerCase().includes('Onboarding')

In this example, we're testing is the user is a member of a specific group by checking if one of its groups has a specific ID:

// Is a member of a specific group by its ID
user.groups.direct.some(group => group.id === ('a937979b-5dbb-4f54-a405-936046244b0b'))

Azure AD Schema Extension

To use Azure AD schema extensions in your audience targeting rules, please refer to this article

Validate and test your audience targeting rule

Syntax Assistant

A "Check Syntax" button is available to test the rule against the current logged user. You can expect 3 kind of outcomes.

  1. You would have access
  2. You would not have access
  3. An error is detected. In case of error, the technical details are also available, helping you solve the issue.