Employee Directory

Recent Updates

• New: require:field rule in Exclusion Rules (Graph mode) — drops rows whose field is empty or whitespace-only (e.g. require:department hides accounts with no department). Pushed server-side as a Graph $filter so the result counter stays accurate.
• Fixed: Graph mode now correctly handles company / department / office names containing special characters (&, +, ?, #, etc.). Previously, names like "First United Bank & Trust" produced 400 errors or "unterminated string literal" failures because the & split the query string. $filter, $select, $search, and $orderby are now URL-encoded.
• Improved: scatter-gather sorting in Microsoft Graph mode — sorting by Department / Job Title / Office now sorts the entire population (not just the current page). The service bulk-fetches across cursor pages and merges client-side.
• Improved: "Showing X-Y of Z" counter is now accurate in Graph mode after server-side filters and exclusion rules are applied. @odata.count now reflects the filtered population the user actually sees.
• Internal: shared default constants (DEFAULT_ITEMS_PER_PAGE = 28, DEFAULT_PINNED_ITEMS_PER_PAGE = 12, DEFAULT_PINNED_ITEMS_PER_ROW = 4) now drive the property-pane slider, render defaulting, and the React component in lockstep.

Display Modes & Views

• Search Directory: Full directory with search, A–Z filtering, filter dropdowns, sort, and Card/List views.
• Pinned Employees: Curated people list. Two selection methods:
  • Select Individual Employees — pick specific people with a people picker.
  • Filter by Criteria — pick a managed property (Department, Office Location, Job Title, or a custom property via pinnedCriteriaCustomField) plus a value. The criteria value dropdown is populated with distinct values discovered in your tenant.

View Templates

• Card View (default): responsive grid of profile cards with a circular photo, name, title, department, and location. Email, phone, SIP/Teams, and other contact fields render as circular icon buttons at the bottom of each card.
• List View: compact row layout where every enabled non-image field becomes a column. The Name field renders as a brand-colored link, email and phone fields render as inline clickable text links, and the profile picture (when enabled) shows as a small avatar in the first column. On narrow viewports the column header row collapses.

Filtering & Sorting

In Search Directory mode, you can add a toolbar that lets users narrow results with dropdown filters and change sorting. Filters and sort combine with search text and A–Z filtering.

• Filter dropdowns: Department, Office, Job Title, Company (configured via filterFields)
• Active filter chips: removable chips with “Clear all”
• Sort dropdown: Name (A–Z / Z–A), Department, Job Title, Office
• Exclude non-employee accounts: one toggle to exclude guests/rooms/equipment/shared mailboxes

Exclusion Rules (Graph Mode)

When the directory uses Microsoft Graph (shown as "Active data source: Microsoft Graph" in Page 2 settings), use the Exclusion Rules field to hide employees. Two rule kinds, one per line:

-company:CohnReznick               # drop rows where company contains the value
-department:Terminations Org       # case-insensitive substring match
-title:Contractor                  # any of name, email, department, title, office, company
require:department                 # NEW: drop rows where department is empty/whitespace
require:title                      # NEW: drop rows where title is empty/whitespace

Rule Kinds

Available Fields

Both rule kinds use the same field tokens:

Exclude matches are case-insensitive and use contains logic — -name:Admin matches "Administrator", "Admin Account", and "ADMIN". Quotes are optional for values with spaces. The directory automatically URL-encodes special characters (&, +, ?, #, etc.) so values like "First United Bank & Trust" no longer break the underlying Graph request.

Custom Query Filter (SharePoint Search Mode)

When the directory uses SharePoint People Search, use the Custom Query Filter field with KQL (Keyword Query Language) syntax:

-Department:"Terminations Organization" -JobTitle:Contractor -WorkEmail:vendor -SPS-UserType:1

Common KQL Properties

KQL property names are case-sensitive. Values with spaces must be quoted. Multiple exclusions can be on one line separated by spaces. Use = for exact match (e.g., -SPS-RecipientTypeDetails:=16).

Configure Fields

• Enable/disable fields, reorder, and choose managed properties
• Select display type per field (Text, Email Link, Phone Link, Link, Icon + Text, Image)
• The Display Name you set becomes the column header in List View
• Reorder fields to control the column order in List View
• Reset to default if needed

Common Configurations

Copy these ready-to-use configurations:

Best Practices

Reference

Technical details for developers and advanced users.

Property Pane Configuration

Settings are split across two pages in the property pane. Page 1 contains the settings most users need. Page 2 contains advanced settings and adapts based on the detected data source (SharePoint Search vs Microsoft Graph).

Page 1 · General Settings

Page 1 · Display Mode

Page 1 · Pinned Layout (Pinned mode only)

Page 1 · View & Filter Options (Search Directory mode)

Page 1 · Display Fields

Page 2 · Data Source

Page 2 · Search Tuning (SharePoint Search mode only)

Page 2 · Customization

Features Checklist

• Name search (with optional wildcard matching)
• Alphabetical A–Z filter with automatic fallback to PreferredName if the configured field fails
• Profile photos from Azure AD / Microsoft 365, with fallback to SharePoint’s user photo endpoint and initials avatar
• Contact fields: email, work phone, mobile phone, SIP/Teams address (all configurable)
• Profile links to Delve / SharePoint profile (SP Search mode) or Delve by user id (Graph mode)
• Pagination (cursor-based when using Microsoft Graph)
• Pinned Employees mode — individual picker or filter-by-criteria
• Configurable fields via Configure Fields collection editor with reorder, enable/disable, and custom display types
• Responsive grid layout (Card view) and dynamic column layout (List view)
• Runtime view switching (Card/List toggle)
• Filter dropdowns populated from Search refiners or Graph aggregation
• Active filter chips with dismiss and Clear All
• Sort dropdown (Name, Department, Job Title, Office) — applied server-side in SharePoint Search mode; in Graph mode, sort is a hybrid of $orderby plus a client-side scatter-gather merge across cursor pages so non-Name sorts cover the entire population
• Standard non-employee exclusions toggle (external users, rooms, equipment, shared mailboxes, hidden from GAL)
• Custom KQL query filter (SP Search) or client-side exclusion rules (Graph)
• People content class enforcement (contentclass:spspeople) in every search to prevent non-people results
• Progressive search fallback — retries with reduced selectproperties / sortlist if SharePoint returns 500
• Microsoft Graph /users fallback when People Search is unavailable

Data Source

Employee Directory talks to two data sources and chooses between them automatically:

1. SharePoint People Search API (/_api/search/query) — the default. Indexes Azure AD user profiles, SharePoint user profile properties, and Microsoft 365 profile information. Supports KQL query filters, managed property refiners, and configurable result sources.
2. Microsoft Graph /users — automatic fallback when People Search returns no results or is unavailable. Requires User.Read.All to be approved for the Bonzai 2 package. Supports $filter, $orderby, $search, and cursor-based (@odata.nextLink) pagination.

Migration from Classic