Microsoft Graph based Employee Directory

Use this guide, if you want to add the WPO365 Microsoft Graph based Employee Directory to a WordPress page. Please note that there are two versions of this app:

  • The basic version offers a fairly simple Microsoft Graph based search for (Azure AD) users that cannot be customized.
  • The advanced version allows for the following customizations

Please note that the advanced version is included in the WPO365 | INTRANET extension (see https://www.wpo365.com/downloads/wordpress-office-365-login-intranet/ for pricing and details).

Before you start

  • You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
  • Additionally, you must also already have configured the integration capability of the plugin.
  • You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to edit the Azure Active Directory App registration that was created previously when the single sign-on capability was configured).
  • You are an Administrator for your WordPress website.

App registration

  • In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
  • Navigate to Azure Active Directory > App registrations.
  • Select the App registration that you created when you configured the single sign-on capability of the plugin.

API Permissions

  • Click API permissions from the 'App registration' menu on the left
  • Click + Add permission.
  • Select Microsoft Graph > Delegated permissions.
  • Check
    • User.Read.All
  • Click  Add permissions.
  • Click Grant admin consent for … as an administrator to grant consent for all users in your tenant to use this ‘App registration’.

Integration

  • Navigate to WP Admin > WPO365 > Integration.
  • Click Delete tokens.
  • Click Save configuration.
  • Sign out of your WordPress website.
  • Sign back in with Microsoft.

When you click Save configuration you may see an error that states "... No authorization code and refresh token found when trying to get an access token for https://graph.microsoft.com/User.Read. The current user must sign out of the WordPress website and log back in again to retrieve a fresh authorization code that can be used in exchange for access tokens ..." Then please sign out of your WordPress website and immediately sign back in (with Microsoft) into your site. This will ensure that the plugin retrieved a fresh set of access tokens on your behalf.

Generate an Employee Directory / Contacts BASIC shortcode

  • Navigate to WP Admin > WPO365 > ... > Employee Directory (Graph).
  • Update the translations as you see fit, for example for Dutch you could update the translations as below.
{
  "search": "Zoeken",
  "hasResults": "{0} resultaten gevonden",
  "hasNoResults": "Geen resultaten",
  "moreResults": "Meer resultaten"
}
  • Uncheck the option to display a Skype for Business (instant messaging) link instead of Microsoft Teams.
  • Click to Copy the shortcode.
  • Create a new page or post in WordPress.
  • Add a new (Gutenberg) Shortcode block (alternatively insert the shortcode as Custom HTML).
  • Paste the shortcode into the input area of the Shortcode / Custom HTML.
  • Save, publish and view the page.

Note The BASIC version of the app will always use the following default query.

/users?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'

Generate an Employee Directory / Contacts ADVANCED shortcode

  • Navigate to WP Admin > WPO365 > ... > Employee Directory (Graph).
  • Use (Handlebars) template allows you to fully customize how the users that are returned by Microsoft Graph are rendered / presented to your users. The option to use templates has been added since v9.5 and are now the preferred way to render search results. However, you can still uncheck this option and use the legacy placeholders for primarysecondarytertiary and meta text. Refer to the following online documentation for instructions on how to create your own fully custom Handlebars template.
  • Template (only visible when you checked Use (Handlebars) template) allows you to configure the location where the app should try and download the (custom) Handlebars template from. Please note that for reasons of security modern browsers won’t allow you to download content from other servers than your own (unless CORS has been properly set up). By default the shortcode generator proposes to use the Handlebars template that ships with the plugin.
  • Primary / Secondary / Tertiary / Meta text (only visible when you unchecked Use (Handlebars) template) allows you to connect the built-in static template’s Primary / Secondary / Tertiary / Meta text placeholders with properties of a (Microsoft Graph) user. You can refer to this Microsoft article to understand what properties are available. Read the Select properties section further down for information on how to retrieve non-default properties.
  • Try retrieve user photo tells the app to try and connect to Microsoft Graph and download a user’s Office 365 profile image to show along with the user’s information.
  • Query  allows you to take control of the Microsoft Graph query and allows for advanced queries to search in users, (transitive) members of groups and benefit from the latest Microsoft Graph tokenization as explained in this article https://developer.microsoft.com/en-us/identity/blogs/build-advanced-queries-with-count-filter-search-and-orderby/

Default query

/users?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'

Example query (search transitive members of an Azure AD group)

/groups/8c6ed1df-a9e6-42dc-b213-8ff8ce93af72/transitiveMembers?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'

Please note that {searchterms} will be automatically replaced by the plugin with the keyword(s) that the user entered in the search box.

  • Use default select properties tells the app to retrieve the default set of properties of a user e.g. surname, given name etc. This is the default set up and will work for general purposes. If you have more advanced requirements e.g. if you have custom properties in Azure AD such as employeeId and you’d like to retrieve and surface such properties in the results then you’d need to uncheck this option and manually enter (all) properties you’d like Microsoft Graph to return. You can do so in the next field Select properties that will only become visible when you uncheck this option first.
  • Select properties allows you to manually enter (all) properties you’d like Microsoft Graph to return (see Use default select properties).
  • Auto search tells the plugin not wait for the user to enter a search query but instead start and search immediately. This is especially usefull when used in combination with a Query Template.
  • Results per page allows you to restrict the number of results displayed per page.
  • Min. input length tells the plugin to wait before executing the search query entered by the user until at least a minimal number of characters has been entered into the search box. This setting does not prevent Auto search from executing a search immediately as soon as the app has finished loading.
  • Add wildcard to each search term adds an * (asterix) to each word that the user enters into the search box and will therefore change the behaviour of the app significantly by instructing the app to search in SharePoint for content that contains the query text entered by the user (instead of returning only items that match exactly with the query text entered by the user).
  • Hide Search box / Message bar / Paging will hide the corresponding elements when checked. This is especially usefull when used in combination with an Query template and Auto search.

Then finally

  • Click to Copy the shortcode.
  • Create a new page or post in WordPress.
  • Add a new (Gutenberg) Shortcode block (alternatively insert the shortcode as Custom HTML).
  • Paste the shortcode into the input area of the Shortcode / Custom HTML.
  • Save, publish and view the page.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.