Smarter ideas worth writing about.

Creating a Robust Employee Directory Using SharePoint Search

No matter whether a SharePoint portal is used in an organization for information sharing or just team collaboration, one request that always seems to come up is for a "corporate phone book". This is usually a directory of employees that hopefully one can use to quickly find someone using filters such as name, location, or department. Back before the Internet and computers were so prevalent (a bit before my time), a typed list of people with their phone numbers was photocopied and passed around, and almost immediately became out of date as people moved about.

A people directory can be useful to list all people in an organization, usually starting out by an alphabetical letter, without your users having to put in a search query where they would need to know some keyword. Searchers can then refine their search even more by using filters such as Department, Location, or Job Title to narrow the results. When the organization contains more than a few hundred people or several locations, this can help users discover their coworkers in the organization without having to know their names.

Since SharePoint receives its people details from the Active Directory (AD) to Azure AD / SharePoint synchronization and then indexes those User Profiles and their metadata properties just like it does documents and List items, we can use a Search Results Web Parts to show these users and their attributes in a meaningful way that can also be stylish. That way no one has to keep a list of people up to date and print it out ever again!

So how do we get started? Let's break it down into manageable sections so we can get this implemented easily. The primary goal is to help users find each other quickly and show information about them that's most important when looking for these users.

Design the 'outputs', or the look-and-feel

The first thing I always suggest when implementing a directory is to figure out how to display each user in the directory. We already have the default template provided by Search of course, which is a good start, but I mean which existing and new properties need to show for each user and the layout of those properties inside the result.

It's always best practice to start from the default rendering by making a copy of the Display Template to start from, then move around or add/trim sections as you need. For each user returned in the results this new template will show the users picture with their Skype status, first / last name, job title, and department if filled in from the Active Directory (AD) to Azure AD / SharePoint synchronization.

But since the default template is designed as an 80% solution to get organizations started, we need to determine a layout that matches the business needs and styling. You'll want to create a few mock-ups, even if just white boarding them, to make sure the design will work. Then we'll figure out the details by asking some leading questions:

  • What profile properties do we want to add and/or remove from the Person template, that aren't there?
  • What order do we want to display them in, top-to-bottom and left-to-right?
  • How do we want to show / filter people (e.g. alphabetical letters, first / last name text search, departments, offices, etc.)?
  • Should any headers always show, or dynamically hide the section like the default Display Template does?
  • What should the styling be for the major portions: border, core properties, and sub-properties?

From these questions, we can create a few quick mock-ups that help the organization decide on a layout that showcases the right data quickly. Also, usually users will want to filter or reorganize the People Results by different ways that help them find others fast. I my example I created a JavaScript widget that allows for several different options, but you can apply this approach to any information stored in the User Profile Properties.

Determine the 'inputs', or the User Profile properties to display

Now that we have the design of a new template to work from, we need to figure out which properties to pull from the Search index to meet this need. We'll start out by investigating the User Profile Service properties attached to each person synchronized into the store.

Note: You'll need the help of your SharePoint or Office 365 Admin to look for these properties if you're not one yourself.

After navigating to the User Profile Service application, click on the Manage User Properties link under the People header. This interface is where all the existing properties are stored and updated including their type, Privacy level, and if the user can self-edit. New properties that enhance a user's profile can also be created from here.

Note: Some properties are directly controlled by the synchronization from AD to Azure AD / SharePoint and cannot be altered.

To show different user properties, we need to find the behind-the-scenes (system) name for it that the Search Indexer stores them by. In the list of properties, scroll down or use Ctrl+f to look for the property you want to show in the directory. Hover over its title and click the Edit link to view its settings. After the property page loads, the first section will show the Name field which is the system name of the property, and what we'll need to use with the Search Index properties to pull the information in. Repeat for any other properties you need to show as well.

Note: If needing to create new User Profile properties, build them and set the values in a few profiles. It may take a few hours to a day for them to show in the Search Index as the indexing User Profiles may not be done until then depending on your platform.

After gathering the system name of all the target user properties use my previous blog post, Making SharePoint Search Results Even Better For Your Users, to walk through how to find these magic data bits in the Crawled / Managed properties section of SharePoint Search. Refer to that detailed guide, using the User Profile properties found above, for creating or mapping properties for use in the Display Templates.

Create the Display Template and get the properties to show

Once we have the magical Search names to use, it's time to create our own Display Template to show people results the way we want. The first thing needed is to navigate to your Tenant, Site Collection, or Site where you want this template used (we have all these capabilities). Go to Site Settings and click on Result Types under the Search header.


Once the Manage Result Types page loads, scroll down to under the section marked 'Provided by the search service' and find the Person Result Type. Hover over it until the arrow appears, then left-click on it and choose the Copy choice. This will create a copy of the settings currently in use and setup the new Result Type that will take precedence over the default SharePoint ones.

Note: This method will make it so that every people result that shows will utilize this Display Template for the Site Collection / Site. A different process would be needed to show just for a specific Search Result Web part.

On the Edit Result Type page, append a descriptor that sets this Result Type apart from the default, then click Save. We'll come back here later and change the Display Template dropdown once we have created it.

As in the previous article I mentioned before, we need to open SharePoint Designer to our Site Collection / Site URL. Once tool loads our Site, start in the left pane by clicking on All Files then in the right pane double-click on _catalogs > masterpage > Display Templates > Search to quickly load all the templates. Scroll down until you find a file named "Item_Person.html", then right-click on it and select the Copy choice.

After copying it, right-click anywhere in the right pane and select paste. A new duplicate will appear in this area with a similar name. Right-click on the new .html file and select the Rename choice, keeping the first part of the original but adding in your own descriptor. After doing this right-click again and choose the Check Out option. Lastly, left-click in the Title area and append your descriptor to the existing one. This will give it a unique name to select from when we go back into the Result Types page.

Note: After copying from the original, SharePoint will detect that this is a Display Template and auto-generate the .js version of the file for us. This may cause the .html to not let you change its Title for the first 2 - 4 times you try but don't give up, otherwise you'll have trouble picking the right Display Template later on.

After our new Display Template is ready, right-click on it and select the Check Out option only on the .html file, then right-click again and select the Edit File in Advanced Mode choice to open the editor surface. As in my previous blog post, we need to add our new index Managed Properties from above to the "

Now scroll down past the <div id="Item_Person">HTML and you'll see the JavaScript compiler section again. In here, you'll see a lot more Out-of-Box variables that include Boolean checks on whether a User Profile property has information in it. The Display Template uses these variables to decide whether to show property sections about users. You may want to leave these as dynamically showing, or based on the mock-up have the always show to keep the result consistent for each user.

Based on our mock-up above, we'll need to decide which properties to check for hiding sections and create variables to watch for this. Create these new variables at the end of the JavaScript section using your new mso:ManagedPropertyMapping properties values.


Note: The "&#39;"you sometimes see in this line is the URL-encoded value for the single-quote (‘). Put a single-quote or the URL-encoded value around the Managed Properties name for them to show.

Scroll down some more until the beginning of the HTML, <div id="_#"$htmlEncode(containter_id)=#_"class+"ms-srch-people-outerContainer ms-srch-resultHover">, and you'll also notice that there is quite a bit more HTML and embedded JavaScript checks than any other of the Display Templates. This is where SharePoint is using the Boolean variables defined above to show User Profile properties only if they are set. Based on our mock-up above we'll want to replicate this process as well, or add our headers in to always show. Wash, rinse, repeat throughout the Display Template until you have it looking like you need, then do a Check-In to publish the template.

Note: Based on the mock-up, new HTML elements with CSS may need to be added, or just require changing of the default dynamic sections. Best practice is to make small changes, save often, and preview after each change to make sure the template displays the way you want.

Finally the easy part, create the Employee Directory itself

After doing all that hard prep work above, we can finally build out the directory. In your Site Collection or Site, navigate to Site Settings and click on Result Types like before. In the top section of items Defined for this Site Collection / Site, hover over the Person type we created and select the edit menu. On the edit page, scroll down the Actions section and in the dropdown that currently says "People Item", change it to select our new Display Template (the reason for giving it a good Title above). Click Save at the bottom of the page and the page will refresh, showing that our template is now being used for all People results.

Now navigate to the Site where you want the directory to be accessed from and select Site Contents > Site Pages. In the Library click on the +New link and give the page a descriptive name (e.g. "Employee Directory", etc.), then click Save.

On the new Page, click Edit if not already active, click in the left-most Web Part Zone, then in the Ribbon choose the Insert tab, select Search in the right Categories scroll list, and finally click on the Search Results Web Part followed by OK to insert it.

Note: you can also use a Content Query Web Part, but I find the Search Result Web Part a little easier to work with.

After the Search Results Web Part is added in the Page, click on its top-right corner and select Edit Web Part. This launches the properties pane so we can configure the results.

In the Edit Web Part menu, change the Settings as needed. I usually use the following settings:

  • Number of results per page: 50
  • Show ranked results: checked / true
  • All other checkboxes: unchecked

When ready, click on the Change Query button to launch the results wizard to configure what to pull from the Search Index.

In the Query Wizard, the first tab showing is for the Basics of using the tool. Start with changing the Result Source dropdown to 'Local People Results' to filter just to people, then setup how you want the Web Part to receive input for searching. Since we want People Results to show as soon as the user lands on the page, I change the Select A Query dropdown to use 'Value of A Parameter from URL'. This allows me to use JavaScript to post back to my directory page with a key that tells it whether to show/filter People Results by Last Name, Department, or Office Location. I then tie this key to a target in the Search Index to show/filter users (see Property Filter).

The Query Text box shows us our changes to the Keyword Query Language (KQL), which is what the Search Results Web Part will post for us to pull in results. In my example below I will have a QueryString variable called "kp" that I'll pass, which will filter the value it has against LastName in the Search index (e.g. ?kp=A), and the "*" at the end says add a wildcard at the end of the value so it gives me 'fuzzy' matches. For a deeper reference on KQL, review the Change settings for the Search Results Web Part article.

Note: There are many ways to set this up, including the easiest of just giving users a Search Box, but a Search Box doesn't pre-load People Results for them. Also, when I pass my QueryString variables, I set an 'AND' condition to exclude any accounts not sync'ed from On-Premise AD.

Now we click on the Test tab and then on the Show More link to open the full interface. In the middle Query Template Variables section, input testing values and then click the Test Query button to verify that users are being returned in the right panel as your filters state. When done, click OK in the wizard and then OK in the Edit Web Part pane to save your changes.

Note: These Query Template Variables will change depending on the filters set on the Basics tab.

After saving our Web Part and Page, review the results coming back on the page and that our new Person Display Template is looking good. If you see any changes needed just wash, rinse, repeat the above Display Template or Search Result filter steps until you get it as you want.

While it is a number of steps to get setup, once you're done you'll have a dynamically-generated Employee Directory that has all the power and capability of Search. The best part is that no one ever again needs to pester users about updating their contact information as it pull's from the core source of this information and shows the updated values as the Search Index finds them.



About The Author

Business Productivity Managing Consultant
Craig is a Managing Consultant for Cardinal Solutions Charlotte office.  He leads client initiatives on Microsoft platforms to help solve business problems by envisioning and architecting Office 365, SharePoint, .NET, and JavaScript/jQuery solutions. Craig has worked with Microsoft development and server technology's for the last 15 years, including integrating SharePoint since it was a beta product.