# 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.


TABLE OF CONTENTS


# Available tags

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

Tag Description
user.displayName User full name (for example "Bob Dirac".)
user.userPrincipalName User 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.mail User email (for example: "bob.dirac@domain.com").
user.preferredLanguage User preferred language in Microsoft 365.
Language and locale codes are limited to those in the ISO 639-1 standard (opens new window).
user.givenName User given name (for example: "Bob").
user.country User country (for example: "France").
user.companyName User company name (for example: "Contoso").
user.department User department (for example: "Marketing").
user.city User city (for example: "Paris").
user.jobTitle User job title (for example: "Product Manager").
user.surname User surname (for example: "Dirac").
user.usageLocation Office 365 usage location. (for example: "US")
Rely on the ISO 3166-1 alpha-2 country codes... (opens new window).
user.groups.direct All 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 (opens new window).

// 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 (opens new window), 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 (opens new window), or for more advanced scenarios, regular expressions (opens new window).

// 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 (opens new window) 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.
classification:PUBLIC