On this page

Getting started with the Staff Directory app

About this guide

This guide explains how to install, configure, and use Cloudwell Staff Directory in SharePoint and Teams.

Existing screenshots and videos illustrate earlier interfaces; use the current settings panel for available options. Staff Directory can be used as a SharePoint web part or full-page app, with configuration also available for Teams tabs.

Add the app for your organization

  1. Find Staff Directory by Cloudwell in the SharePoint Store or Microsoft AppSource, and add it to your organization’s app catalog.
  2. In the SharePoint admin center, open API access. Have an authorized administrator review and approve the pending permission requests from the Staff Directory by Cloudwell package.
  3. Add the web part to a SharePoint page and check that directory data loads. The app checks required Microsoft Graph permissions and displays a message when permissions are missing.

Add the app to a SharePoint page

  1. Go to the page where you want to add the app.
  2. Click edit at the top right of the page.
  3. Hover your mouse above or below an existing web part and you’ll see a line with a circled +.
  4. Click + and you’ll see a list of web parts to choose from. To easily find the Staff Directory by Cloudwell web part, start typing in the Search box and then select Staff Directory by Cloudwell in the search results.

Configure the app

Configure the Staff Directory web part from its settings pane while editing the SharePoint page. Expand a settings group to change its options. Some controls open a separate configuration panel.

The settings groups are Layout, Celebrations, Cards, List, Filter and sort, and Advanced settings. The Cards and List groups appear only when their respective views are enabled.

For a Teams tab, open the tab’s settings to configure the app.

Layout settings

Use Layout settings to control the directory title, paging, initial results, presence, hover cards, exports, actions, and available views.

Show title

Show title shows or hides the web part title. It is on by default.

Page size

Page size sets how many people appear on each page. The default is 12.

Show page number buttons

Show page number buttons shows or hides the numbered page buttons. It is on by default.

Show all by default

Show all by default shows people before a search or filter is applied. It is on by default. When it is off, users need to apply a search or filter to see results.

Show presence

Show presence displays Microsoft 365 presence information. It is on by default and requires the Microsoft Graph Presence.Read.All permission.

Show hover card

Show hover card enables hover cards for people. It is on by default.

Show export actions

Show export actions makes export options, including Excel and CSV, available to users. It is on by default. Review the exported columns and results before distributing a file.

Configure actions

Configure actions selects and orders actions on person cards and list rows. Email, chat, call, and share are selected by default. Call and share options can be configured in the panel.

Default view

Default view chooses the initial view: Cards or List. Cards is the default. After changing it, save the page and reopen it to confirm the intended view loads.

Available views

Available views chooses which views users can switch between. Cards and List are both enabled by default. Disabling a view also hides its settings group.

Multiple view options to meet your user experience needs.
Multiple view options to meet your user experience needs.

Celebrations

Select the celebration types to display: birthday, anniversary, or new hire. None are selected by default. When a type is selected, the related settings become available:

  • Birthday field: Selects the user property containing the birthday. Defaults to birthday.
  • Hire date field: Selects the property used for new-hire and anniversary dates. Defaults to employeeHireDate.
  • Anniversary milestones: Selects which work anniversaries to include. By default, every anniversary is included.
  • Show only celebrations: Limits the directory to people with a selected celebration in the configured window. Off by default.
  • Celebrations window: Sets the date range: current month, current week, next 7 days, next 14 days, or a custom period. Defaults to current month.
  • Show future celebrations first: Prioritizes upcoming celebrations. On by default.
  • Auto-page on celebrations: Automatically cycles through card pages when showing only celebrations. On by default; the interval can be set from 1 to 60 seconds and defaults to 5 seconds.

For a custom window, set how far back and ahead to include, in days, weeks, or months. Confirm that the selected birthday and hire-date properties contain data and that the configured window includes the people you expect.

Example of Staff Directory celebration styling.

Cards settings

Card layout

Card layout selects small, medium, or large cards. Large is the default. The Cards settings group appears only when the Cards view is enabled.

Configure card layout

Configure card layout chooses and orders the properties shown on the card. Select the properties you need, arrange their order, and review the card preview.

Card sizeDefault front fieldsFront property limitCard back
LargeJob title, department, phone, office location, company5Can be configured
MediumJob title, department, office location3Can be configured
SmallJob title, department2No back

Custom properties defined in Advanced settings are available for card configuration. Check profiles with populated and empty fields before publishing.

Example of the Staff Directory card builder.

Card backs and custom properties

Large and medium cards can have a back configured for additional profile information. Small cards have no back. Use the card builder to select the properties displayed on the front and back.

Define custom Microsoft Graph user properties and their display labels under Advanced settings → Custom properties before selecting them for cards or lists. Labels control how fields are presented; they do not change the underlying profile data.

Fax number is also supported as a card property. Check that source profiles contain the property before adding it to a layout.

Contact, person actions, and sharing

Staff Directory supports clickable email attributes and a phone selector that can include both a main phone number and a mobile number. Phone icons can be shown or hidden.

Configure the available call options and custom person actions to suit how colleagues contact one another. Verify each configured action with a test profile before publishing.

Native sharing is supported on compatible devices. Use the share action offered by the app; the available sharing destinations depend on the device and browser.

List settings

Compact mode

Compact mode uses a more compact list layout. It is off by default. The List settings group appears only when the List view is enabled.

Configure list view

Configure list view chooses and orders the list columns. The default columns are job title, department, manager, and office location.

Select the columns required by your organization and arrange their display order. Custom properties defined in Advanced settings are also available for list configuration.

Example of Staff Directory list-column configuration.

Filter and sort settings

Sort by

Sort by sorts people by first name, last name, or display name. Last name is the default.

Initials filter by

Initials filter by chooses which name field the letter filter uses: first name, last name, or display name. Last name is the default. Choose Display Name when colleagues commonly search by a preferred or displayed name.

Show search

Show search shows or hides text search. It is on by default. Search includes first name, last name, job title, department, and office location.

Add more user properties under Advanced settings → Search properties. Configure the property name and validate it before saving.

Search supports locale-specific characters. Test accented or other special characters using the spelling stored in the profile.

Exclude disabled accounts

Exclude disabled accounts excludes disabled accounts from directory results. It is on by default.

User types

User types selects which account types to include. Members are included by default; guests and accounts with no user type can also be selected.

Available quick filters

Available quick filters chooses which quick-filter fields users can use. Country, department, job title, office location, and company name are enabled by default.

The selected order determines the display order of filters. Dropdowns are searchable, and cascading filters narrow later choices based on the current selections.

Advanced filters

Advanced filters adds conditions based on person properties using operators and values. Conditions can match all or any values. Manager and group-membership fields use pickers.

The default filters require job title, first name, and last name to contain data. A person missing one of these values may be omitted even when their account is otherwise included.

Configure each condition using the supported field, operator, and value or picker, then save the filters. Test with expected people and excluded people. When results are unexpected, start with one condition and add further conditions after verifying the results.

Advanced settings

  • Custom properties: Defines additional Microsoft Graph user properties and their display labels, making them available when configuring cards and lists.
  • Search properties: Adds user properties to text search. Configure the property name and validate it before saving.
  • Show message when no people: Shows a message when the directory has no results. On by default.
  • Custom message when no people: Sets the message shown when no filter is applied and there are no people to display.
  • Custom message when no people filtered: Sets the message shown when a search or filter returns no people.
  • Refresh people interval: Sets how often directory data is refreshed from Microsoft Graph. The default is 20 hours. Shorter intervals can increase Graph API requests.

Loading, caching, and troubleshooting

Staff Directory uses shimmer placeholders while directory information loads. These placeholders follow the site theme and are replaced by profile content when loading completes.

Staff Directory uses caching to improve responsiveness. The Refresh people interval under Advanced settings controls how often data is refreshed from Microsoft Graph and defaults to 20 hours. Shorter intervals can increase Microsoft Graph API requests.

  • Missing or unexpected people: Check search text, letter filters, quick filters, advanced filters, user types, disabled-account filtering, and any manager or security-group selection.
  • Missing profile fields or celebrations: Verify the underlying profile property or hire date with your administrator, and check the chosen celebration range.
  • Permission message: Ask an administrator to review the required Microsoft Graph permission requests in the SharePoint admin center.
  • Stale data: Confirm the source data and installed app version. If cache refresh or clearing still fails after updating, report it to Cloudwell.
  • Startup or licensing error: Record the error message and deployed version for Cloudwell support.

Upgrade the app

Upgrading to the most recent version of the app is simple.

  1. In your organization’s App Catalog, find the app and select the checkbox on the left.
  2. In the Files ribbon, select Upgrade Store App.
  3. Once updated, you will notice the updated App Version number in the app catalog. Additionally, you can view the app version in the web part settings panel on a SharePoint page.

After upgrading, review any pending API permission requests, confirm the deployed version, and test default and available views, custom properties, filtering, celebrations, sharing, and export. Consult the release notes for changes since your previous version.

Uninstall the app

  1. Go to your tenant’s SharePoint App Catalog and click the “Apps for SharePoint” link in the quick launch navigation.
  2. Select Staff Directory by Cloudwell in the list of apps and click delete from the menu.

Troubleshooting and support

For version-specific fixes and changes, see the Staff Directory release notes. If an issue persists on the current version, contact Cloudwell with the deployed app version, whether it occurs in SharePoint or Teams, the steps to reproduce it, and the displayed error message.

See the Staff Directory release notes for the history of enhancements and fixes.

PRODUCT DEMO

See Cloudwell products in action

Choose a time to explore our Microsoft 365 apps and discuss your team’s needs.

LET’S TALK

Let’s talk about your next project

Choose a time to discuss your goals, explore your options, and find a practical next step.