Collaboration is at the heart of the SharePoint Community. I created this article as a favor to many who have asked for a SharePoint app solution for an employee directory. MVP Scot Hillier developed an employee directory solution a LONG time ago and then in creating some additional demos I added a few touches that made it work for me and my demos. Since then, folks have asked over and over for the code. Scot has made all of our code available through GitHub. The thing I really like about this project is that it demonstrates how to use Search in an app. This may seem like a small thing, but if you haven’t heard Search is BIG in SharePoint (and will continue to gain traction as many new features are introduced…just watch…).
What Scot and I decided to do is simply make the project available and then post two articles. This first article, this one, describes how to get the code and how to deploy it. This is for the folks who just want to get up and running quickly. The next article will dive into the details of how the app is built. I’ll discuss the development approach and key lines of code that make this such a useful app.
Lather, rinse, repeat
I know you may be thinking to yourself, hasn’t this topic been beat to death already? Can’t we just use People Search? While I would say you are preaching to the choir, I spend a lot of time on SharePoint.StackExchange.com and see this question come up over and over (and over and over and over). You can find many options for creating employee directories; Marc Anderson has a great walk through on his blog: http://sympmarc.com/series/create-a-simple-sharepoint-2013-employee-directory-on-office365/. Marc presents an out-of-the-box strategy that I think works quite well. Scot and I wanted to demonstrate a slightly different approach that can show the value of development enhanced with a custom UI, either tabular or in “contact cards.”
OK, we are talking about SharePoint apps here. So you need to configure a few items to make this all work. I’ll explain it all in a sec, but here is the list:
- Make sure your farm will support apps (if you are on Office 365 you are all set)
- Get the code
- Create the Last Name Sortable Managed Property
- Provision an App Catalog (or use the one already provisioned)
- Deploy the app
If you are using Office 365, bam, you are done! See, wasn’t that easy! (Oh, you really need to be a tenant administrator to create the App Catalog entry, but more on that later.)
SharePoint 2013 on-prem
If you are using SharePoint on-prem you need to configure your farm to support apps. This means configuring an App Domain. If you don’t know how check out Mirjam’s excellent post on the topic: http://sharepointchick.com/archive/0001/01/01/setting-up-your-app-domain-for-sharepoint-2013.aspx. You also need to create an App Catalog site for the Web Application that is going to host your app. It’s just a site template. Here’s how: https://msdn.microsoft.com/en-us/library/office/fp123530.aspx
Once you have this part done, you are ready to support SharePoint and Office app development and deployment.
Git the code
Download the code from the IT Unity GitHub repo.
Configure the sortable LastName managed property
In SharePoint on-prem all you need to do is change the LastName managed property. In Office 365 you have to reuse one of the built-in “RefinableString##” fields for the purpose, because they are already marked as Refinable and Sortable. (Of course these steps work for SharePoint on-prem, just be sure to perform these steps in the Search Service Application and not in a Site Collection.) Here’s how:
- Go to the SharePoint Administration Center and choose Search.
- Under Search Administration choose Manage Search Schema.
- Search for the LastName managed property and notice that it is not marked Refine or Sort (figure 1). This is our issue. All we need to do is edit an existing RefinableString## field and duplicate the field mapping.
Figure 1: In the LastName property, Refine and Sort are not marked.
- Search for RefinableString10 (I am using #10 because Scot Hillier and I plan to release this code later.) Notice that this property is both Refinable and Sortable. Yay! Hover and click the Edit/Map Property link (figure 2).
Figure 2: Choose Edit/Map Property of the RefinableString10.
- On the edit page enter an Alias of LastNameSort. We’ll use this later when requesting sorted search results (or as a Refiner).
- Scroll down to the Mappings to crawled properties section. Click Add a Mapping.
- In the Crawled property selection dialog, change the category to People and Search for “Last”. Click Find. You should see People:LastName and People:SPS-PhoneticLastName (figure 3).
Figure 3: Search for crawled properties People:LastName and People:SPS-PhoneticLastName.
- Select People:LastName and click OK.
- When you are done, confirm that your mapping contains the LastName property (figure 4).
Figure 4: Confirm that the mapping contains LastName.
- Click OK to save your changes.
- If you are on premises you can kick off a full crawl of the content source that contains your People (sps3://) start address. In Office 365, we wait. The User Profiles are supposed to be re-indexed once a day (thereby picking up our change). Or you can try this trick: http://techmikael.blogspot.com/2014/12/how-to-trigger-re-indexing-of-user.html
Quick Tip: To test that your settings worked, try this REST call (replace your tenant URL). If you get a Server error like 400 bad request you need to recheck your settings:
http://<your tenant url>/_api/search/query?querytext='*'&selectproperties='LastName,FirstName,PreferredName '&sourceid='B09A7990-05EA-4AF9-81EF-EDFAB16C4E31'&sortlist='LastNameSort:ascending,FirstName:ascending'
- Once the code above is working you should be able to begin using the LastNameSort field in your code and refiners.
OK, enough chit chat. How do you make this work? I have included all of the steps and graphics so you can see how all the pieces fit together. Obviously you will want to change the images, but I included them so you can see how a fully implemented App Catalog entry looks.
If you are on Office 365: Go to your App Catalog
- Log in to your Office 365 Tenant Administrator for SharePoint.
- Locate your App Catalog Site. (Usually it is https://<your tenant>/sites/apps.)
If you are on SharePoint on premises: Go to your App Catalog
- Log in to Central Administration.
- Navigate to App Management.
- For your Web Application ensure that you have an App Catalog Site created. If not, create one.
- Navigate to your App Catalog Site.
Create the App Catalog Entry
- Copy all the images into the app catalog Site Assets library. (You can use my images to get started and then swap them for your own images later.)
- Navigate to the Apps for SharePoint list.
- Drag the App Package into the Apps for SharePoint list. (Or use upload; it does not matter.)
- Edit the properties of the app to suit your needs, for example:
- Name: EmployeeDirectory
- Title: Employee Directory
- Short Description: This app searches the SharePoint User Profiles and returns employees by Last Name.
- Description: This app creates a tabbed employee directory that enables users to click through an employee directory (of SharePoint User Profiles).
- Icon URL: https://<your tenant>/sites/apps/SiteAssets/Address-Book-96.png
- Category: Utility
- Publisher: Your Company
- Support URL: Put in any URL you like except for www.shillier.net or www.ableblue.com! :-) (Or leave it blank.)
- Image URL 1: https://<your tenant>/sites/apps/SiteAssets/EmployeeDirectory1.jpg
- Image URL 2: https://<your tenant>/sites/apps/SiteAssets/EmployeeDirectory1.jpg
- Enabled: Checked
- Featured: Checked (for now, you may choose to uncheck it later).
- Click Save to close the page.
Test your work
Once you have the App Catalog Entry you should be able to navigate to the Site Contents Page and choose Add an App. You should see the App icon (figure 5).
Figure 5: The App icon.
If you click App Details you will see the rest of the App Catalog entry (figure 6) including the screen shots.
Figure 6: The App Catalog.
Install it already!
Click Add It and the app will display the consent dialog (figure 7). Click Trust It after carefully reading what you are consenting to.
Figure 7: Indicate that you trust the Employee Directory app.
The app will take a moment to deploy (figure 8).
Figure 8: Waiting while the app deploys.
Once deployed you will see the Employee Directory app ready to go (figure 9).
Figure 9: The Employee Directory app is installed!
Click the link and choose a tab from the top. Figure 10 shows Table View.
Figure 10: The Employee Directory app in Table View.
Figure 11 shows Slide View.
Figure 11: The Employee Directory app in Slide View.
In the next article I’ll dive into detail about how the app is built and how to query SharePoint through REST. Until then, enjoy.