Use SDK Cmdlets to Add Properties to the Microsoft 365 User Profile Card

The Microsoft 365 profile card displays information about users. The information show in a profile card comes from the user’s Entra ID account. By default, Microsoft 365 limits the properties shown by the profile card to the set that they consider to be most important. Organizations can customize the Contact tab of the  profile card to reveal some of the properties that are not shown by default. However, not every property of an Entra ID user account is available for the profile card. Some, like the employee hire date, are not supported.

In 2020, I wrote about how to customize the profile card. At that time, the profile card API was in beta. The production Graph endpoint now supports the profile card API, and it’s also supported by cmdlets in the Microsoft Graph PowerShell SDK. I used version 2.9 of the SDK for this article.

The Microsoft documentation for customizing the profile card is a little outdated. At the time of writing, it uses V1.0 of the SDK and is based on the beta API. Because the API is now in production, it follows that the latest SDK cmdlets use that API. In any case, the instructions contained in the documentation are a reasonable guide.

Customized User Profile Card Available to All

The most important point about customizing the profile card is that any change is exposed to all users. You cannot customize the profile card for a subset of the user population such as a targeted administrative unit. This fact creates difficulties in multinational organizations where local privacy regulations might prevent the display of certain information held in user account properties.

As already mentioned, only certain user account properties are available for customization. Basically, you can add six standard properties:

• UserPrincipalName.
• Fax.
• StreetAddress.
• PostalCode.
• StateOrProvince.
• Alias.

Of course, including these properties in the profile card is useless unless information is populated in the directory for all user accounts. That often doesn’t happen.

The the fifteen custom attributes inherited from Exchange Server (different to the custom security attributes that can be defined for Entra ID) are also supported. Many organizations use these attributes to store information about users such as personnel numbers, cost centers, employee type, employee job codes, seniority level, and even the date of last promotion. Dynamic distribution lists and dynamic Microsoft 365 groups.

Add an Attribute to the Profile Card

To add one of the six standard or fifteen custom attributes to the profile card, construct a payload in a PowerShell hash table. The table contains the property name and its display name (annotation). Then run the New-MgAdminPeopleProfileCardProperty cmdlet passing the hash table as the body parameter (the same as passing a request body to a Graph request). This command adds CustomAttribute15 and tells Microsoft 365 that the user profile card should refer to the property as the “Employee Type.”

Connect-MgGraph -Scopes "PeopleSettings.ReadWrite.All","PeopleSettings.Read.All" -NoWelcome

$AddPropertyDetails = @{
  directoryPropertyName = "CustomAttribute15"
  annotations = @(
    @{ displayName = "Employee Type" }
  )
}

$AddPropertyDetails

Name                           Value
----                           -----
directoryPropertyName          CustomAttribute15
annotations                    {Employee Type}

New-MgAdminPeopleProfileCardProperty -BodyParameter $AddPropertyDetails

Id DirectoryPropertyName
-- ---------------------
   CustomAttribute15

It takes at least 24 hours before the profile card picks up customized properties. When they do, they appear on the Contact tab of the profile card. Figure 1 shows three custom properties for cost center, preferred drink (a historic part of the Active Directory schema), and employee type. If a custom properties doesn’t contain any information for a user, it won’t appear on the profile card.

To check the set of attributes added to the profile card with PowerShell, run the Get-MgAdminPeopleProfileCardProperty cmdlet. This output tells us that the profile card is configured to display three optional properties and three custom properties:

Get-MgAdminPeopleProfileCardProperty

Id DirectoryPropertyName
-- ---------------------
   userPrincipalName
   customAttribute12
   StreetAddress
   Postalcode
   CustomAttribute9
   CustomAttribute15

If you make a mistake, you can remove a property from the profile card by running the Remove-MgAdminPeopleProfileCardProperty cmdlet. For example, this command removes the Drink attribute (stored in CustomAttribute9) from the profile card:

Remove-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId CustomAttribute9

Note that the profile card property id parameter is case sensitive. You must pass the property name as returned by the Get–MgAdminPeopleProfileCardProperty cmdlet.

Adding a Translated Label for a Custom Profile Card Property

The documentation makes a big thing about defining a language-specific value for a custom property. This is done using the Update-MgAdminPeopleProfileCardProperty cmdlet. This example shows how to add a French language label for CustomAtrribute15:

$LocalizationHash = @{}
$LocalizationHash.Add("languagetag","fr-FR")
$LocalizationHash.Add("displayName","Type d’employé")

$UpdatePropertyDetails = @{
   annotations = @(
    @{
    displayName = "Cost Center"
   localizations = @( $LocalizationHash )
     }
    )
}
Update-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId 'customAttribute15' -BodyParameter $UpdatePropertyDetails

This command works, but it only works for a single language. If you want to have labels for multiple languages, you’ll be sadly disappointed because Update-MgAdminPeopleProfileCardProperty (and its Graph API counterpart) overwrite the language configuration each time.

You could argue that this is disappointing for multinational organizations that want to have fully-translated interfaces for all languages in use. Being restricted to a single language alternative is a strange approach to localization, especially for a company that does so much to deliver local language translations for user interfaces. The counterargument is that the properties chosen for display in the profile cards are likely to be well understood by anyone in an organization.

Work Still to Do

Not much has changed in customizing the profile card since 2020. The API is now production rather than beta and the Graph SDK supports the action, but that’s it. Coverage for multiple local language labels would be nice but that’s still elusive.

Support the work of the Office 365 for IT Pros team by subscribing to the Office 365 for IT Pros eBook. Your support pays for the time we need to track, analyze, and document the changing world of Microsoft 365 and Office 365.

Users Can Decide What Pronoun to Display in Profile Card

Updated March 30, 2023

Announced in message center notification MC515531 (last updated 21 February 2023), the ability to enable pronouns in Microsoft 365 profile cards is available in the Microsoft 365 admin center. Once enabled, users can set their preferred Microsoft 365 pronouns using the preview version of Teams. The pronoun feature is covered by Microsoft 365 roadmap item 86352 (Teams) and 115511 (OWA).

I have been able to update pronouns in Teams, OWA, and the latest build of the Monarch (“One Outlook”) client.

Employee Engagement

Microsoft’s documentation for the pronoun feature says that “the simple act of using the right pronouns for one another can help build trust and improve communication among colleagues.” Microsoft goes on to highlight that “Whether or not to share or publicly display pronouns is always up to an individual. Pronouns should never be assigned to one person by another person. It should be up to the person using them to decide when, where, and which pronouns are used – including whether to use this feature.”

In other words, organizations should do some thinking and employee engagement before they implement pronouns for profile cards.

Implementing Pronouns on the Microsoft 365 Profile Card

The first step is to enable pronouns for the organization. Go to Org settings in the Microsoft 365 admin center and select the Security & privacy tab. Pronouns is one of the listed options (Figure 1).

Microsoft says that it can take up to 7 hours before users can change their pronouns. In practice, expect the change to take a day before it is effective. If you disable pronouns, it will take the same length of time before pronouns disappear from view for all users. Microsoft 365 removes pronoun data if an organization disables the feature. Like most deletions in Microsoft 365, deletion is not immediate and if you reenable pronouns, previously set values will reappear.

After the software change is effective, users will see the option to update pronouns on their profile card. For instance, I clicked on my photo for a message posted to a Teams channel to reveal my profile card and see the option to add pronouns (Figure 2).

Remember Microsoft’s point that pronouns are a personal decision for users? To enable freedom of choice, you can add whatever text you like for a pronoun. The profile card suggests the commonly-used values such as “She/Her,” but you can ignore these values and use whatever text you prefer (up to 30 characters).

The important thing to remember is that pronouns are visible to all members of the organization. There’s no way to restrict pronoun display to a certain segment, such as members of a group. Guest members and external members of shared channels can’t see pronoun information on profile cards.

Building the Profile Card

Microsoft 365 stores user pronouns in a hidden folder in user Exchange Online mailboxes. Apps that support the profile card retrieve the information from the mailbox along with other properties (including custom attributes) to display the profile card (Figure 4).

A Change to Plan

Microsoft’s FAQ for pronouns contains some other useful information to consult before implementation. Displaying pronouns in the profile card is obviously something that an organization should think through before implementation. For example, some organizations also add pronouns to account display names, meaning that the information shows up in address books and other places where people see display names, like email headers, listings of documents in SharePoint Online and OneDrive for Business, and so on. Don’t rush to deploy just because someone (maybe a vocal proponent) thinks that pronouns are a good idea. Pause, consider, and then decide.

Support the work of the Office 365 for IT Pros team by subscribing to the Office 365 for IT Pros eBook. Your support pays for the time we need to track, analyze, and document the changing world of Microsoft 365 and Office 365. Even pronouns deserve analysis…