People Directory

The Directory (📇 in the sidebar) gives every signed-in user a searchable company directory: name, title, department, email, phone numbers, office, assistants, custom fields, and a profile photo. Search covers all of it, and email/phone entries are clickable (mailto: / tel:).

Since 1.2 the directory is something you configure rather than work around: every field is a row in a registry, every value can be mapped in from Entra or Google Workspace with a live preview, and every view — including the PDF export — reads the same configuration.

Finding someone fast

You don’t have to open the Directory to look someone up. Press @ anywhere in the app and the command palette opens in people mode: type a few letters of a name, email address, job title, or department and matching colleagues appear with their photos, ready to open. It floats over whatever page you were on, so you can check who runs Payroll without leaving the document you’re writing.

Views, groups & pins

Switch between three views (your choice is remembered per browser):

Cards — photo cards with contact links, assistants, and any fields marked “show on cards”. Optionally in sections by any group-by field.
List — a sortable table. Use the Columns menu to choose exactly which columns you see — standard ones plus any custom field, and both ends of a people field (Assistant / Assists). Each entry shows how many people have a value, so a column that would be empty says so before you add it. Sort names by (Full name, First name, Last name) in the toolbar, in every view, decides what names sort on: the list’s Name column, the cards, and the members of each group (when titles have no option order, which otherwise comes first). “Jane A. Smith”, “Smith, Jane” and “Dr. Jane Smith Jr.” all sort as Jane / Smith; “Ludwig van Beethoven” keeps his particle; a credential comes off the end only, so “JD Vance” sorts as JD / Vance. The choice is remembered in your browser, and an admin sets the starting value under Settings → Directory → Display (the Directory page defaults card). “What I see” exports carry the same order. The columns you start with are the admin’s defaults; Reset to defaults goes back to them.
Groups — everyone in sections by a field: department, title, office, a practice-group field — whatever an admin has marked group by. Sections appear in the order the admin gave the field’s options (Attorneys first, Marketing last — not the alphabet), people inside a section follow the Title field’s option order, and each person’s assistants are named on their tile. A section whose option names heads lists them first with a Head chip, and its heading reads “Engineering (13) · Head: Jane Smith” (see Section heads).

Pins. Admins pin people to the top of every view (reception, IT, the records desk), in an order they set. You can also star anyone for a personal My pins section; those stay in your browser.

Every name links to a profile page: photo, title, contact details, custom fields, people links in both directions, where they sit in the org chart, and — the useful part — Documents by that person, listing everything they’ve authored in the spaces you can see. From 1.18.0 the list leaves out handbook-only documents in spaces you can’t write in; you read those in their handbooks. And the directory feeds the Ask feature: questions like “who is the head of IT?” answer with the person’s name, title, and contact info, linked to their profile. Article bylines link too — click By {author} on any document to jump to the author’s profile.

Org chart

The fourth view, Org chart, draws the company from the built-in Reports to field: the people nobody reports to at the top, each person’s direct reports beneath them. Three levels open by default; a chevron opens the rest, Expand all / Collapse all do it at once, and the badge on a person counts their direct reports and, after the slash, everyone below them — click it for the team page. Search keeps the people who match and the line above each of them, so “Beta” shows Beta, Beta’s manager, and so on to the top. People whose Reports to is blank sit in a Not in a reporting line section at the end.

A reporting line that loops (A reports to B, who reports to A) is broken at one person and noted above the chart; the People page’s health card names the loop.

On a profile, the Team block shows the chain above the person, top of the company first, the people alongside them, and their direct reports, with Open in org chart (which opens the tree to them) and Whole team: a page of everyone below them, level by level, with an export of exactly those people as PDF, CSV or contact cards.

Reports to is one manager per person and Direct reports is its other end; both show on cards, the list, and every export like any people field. Fill it by hand on the People page, from a Reports to column in a CSV import (names or emails), or — on Enterprise — let the sync do it: the field comes mapped to Microsoft’s manager relationship (manager.mail) and Google’s manager relation, so the chart is complete after the first sync. Clear the mapping under Fields if you’d rather keep it by hand.

My team on the dashboard

From 1.17.0 everyone’s dashboard has a My team tile drawn from the same Reports to field, with up to three parts:

You report to: your manager.
Your team: everyone else who reports to your manager, as avatars (the first six, then “+3” to see the rest in the org chart).
Your direct reports: the people who report to you (the first five, then “and 2 more”, which opens the org chart on you).

Each person links to their profile, and Directory → opens the directory. Where Teams presence is on, the people synced from Microsoft 365 show it on the tile too.

The tile needs your account to be linked to a directory entry that isn’t hidden, and you must be able to see the Reports to field (it isn’t admins only). It is left out when your entry has nobody above, beside or below it.

Reaching someone

A profile is more than a page to read:

Save contact downloads a contact card (.vcf) with the name, title, company and department, work and mobile numbers as typed, email, the office’s address, main line and fax (from its profile under Offices), a link back to the profile, the assistant and card fields as notes, and the photo. It opens straight into Outlook, iOS Contacts or Android.
The QR code (next to it) holds the same card without the photo — point a phone camera at it and the contact is added, no app and no account.
Chat in Teams and Schedule a meeting appear for people synced from Microsoft 365; the card in the directory has the Teams and contact-card shortcuts too.
Export → What I see, as contacts downloads everyone on screen as one .vcf, each with their office’s details; a preset can be exported the same way (format=vcf).

Photos: the sync keeps a 240px copy for profiles and contact cards beside the 48px thumbnail lists use. Admins can upload a photo for anyone on the People page — it is cropped square and both sizes are made on the server; a provider’s photo replaces it on the next sync.

Dates, start dates and birthdays

A field can be a Date. Anything sensible reads — 2020-05-01, 5/1/2020, May 1, 2020, and Graph’s employeeHireDate — and it shows as “May 1, 2020” and sorts by time, not text. Under the field’s settings a date can mean the start date — profiles then show “Since May 2020 · 6 years”, and the directory opens with Started this month and Work anniversaries — or a birthday, for Birthdays this month. The strips appear only when there is someone to show, and never on the list view.

People this week on the dashboard

From 1.17.0 the same fields feed the People this week tile on everyone’s dashboard:

New starters: a start date within 7 days either side of today (“Joins Support”, “Joined Support”; the company name when the person has no department).
Work anniversaries this week (“3 years at Acme”).
Birthdays this week.

“This week” is Monday to Sunday, and “today” is in your own time zone (from your preferences, else the workspace’s). A birthday or start date on 29 February is marked on the 28th in other years. The tile shows up to five people, the ones nearest today, in day order, each linking to their profile. It is left out when there is nobody to show.

Hidden entries never appear, and a date field that is admins only is left out for everyone else: an admin-only birthday makes no birthday row. The tile doesn’t need your own account to be linked to the directory.

Who sees what

Every field can be for everyone signed in or admins only — set it in the field’s row under Settings → Directory → Fields (Who sees it). The three contact columns — email, phone, mobile — have the same choice in the Contact details block at the foot of that page; name, title, department and office are always shown.

An admin-only value is removed on the server before anything reaches a non-admin: the directory (every view, and the Columns menu), profiles and team pages, the people API, exports of every kind, contact cards, and from 1.17.0 the dashboard’s My team and People this week tiles. A mobile number the whole firm should not have, a birthday, a home office — admins keep them, nobody else sees them, and nothing has to be remembered per export.

Export to PDF or CSV

Export ▾ (top of the Directory) replaces the old print button:

A preset — one of the layouts an admin defined under Settings → Directory → Export. A preset is a row in the list on the left; its settings are six groups on the right, Document (what the preset is called, what the file is named, what it says at the top and bottom, and how names are written), Page (paper, orientation, density, margins, table or photo cards, the office information at the end), Columns (the columns in order, with their limits, the assistant’s details and the markers to print), Order and filter (sections, their order and their heads, sort, pinned people first, who is in it, one file per value), Schedule (emailing it) and Download link (a link that hands it out, below). Across those groups a preset sets: paper size (Letter, A4, Legal), orientation, density, one table across the page or two or three columns side by side (a short name-and-extension table fills the sheet instead of running down the left), margins (Normal, Narrow, Wide, or Custom inches per side), the workspace logo, title and subtitle, columns and their order, a character limit per column (Wrap after, 8 to 120) so a long title wraps onto a second line instead of running on or being cut short, assistant details (the assistant’s own phone or extension after their name, “Pat Lee · 602-555-0100 · x204”), sections by any group-by field, in the field’s order or one you set, a sort and a “then by” sort (Office, then Title — any field, synced or typed, a field with options in their order, or first name / last name: “Smith, Jane” and “Dr. Jane Smith Jr.” both sort as Jane / Smith, “Ludwig van Beethoven” under van Beethoven), shaded alternate rows, a filter (one office’s sheet), photo thumbnails, a key-contacts section, office information (below), and a footer with the printed date, “Page X of Y” and a confidentiality line. The file is rendered on the server, so it comes out the same on every machine. Download PDF on a preset waits until the page is saved, markers included: the button says so while anything is unsaved.
What I see — exactly the people, columns and grouping on your screen, as PDF or CSV. Filter to a department, trim the columns, export.
Copy download link… — a link to any preset’s file for an email or an intranet page (Download links).
Print… — the browser’s print dialog, as a fallback.

Values in the file are the same as on screen: a code that shows as “PHX1 – Phoenix” in a card is “PHX1 – Phoenix” on paper.

A column with a Wrap after limit takes a fixed width (about the limit in average characters) and wraps its value; the other columns share the rest of the page as they always have. In the two- and three-column layouts a wrapped row is counted for the lines it takes, so the columns still fill each page evenly (with a tenth in hand, so a value of capitals exactly at the limit never spills onto an unplanned page), and columns without a limit keep their one-line ellipsis. A limit belongs to the column while it is in the preset. Assistant details are read from the assistant’s own directory entry among everyone you may see, not from the rows in the file: a What I see export still shows an assistant’s phone when the assistant is off screen, a one-office sheet shows an assistant who sits in another office, and each file in a One file per zip reads the same list; an assistant you may not see at all shows their name alone. Custom margins take one decimal place; what you type is what is saved. Through the API, POST /api/directory/export accepts sort / sort2 of name:first or name:last, and the preset options column_limits ({ "title": 24 }), assistant_fields (["phone", "extension"]; a column you may not see is dropped), margins (normal | narrow | wide | custom) and margin_custom (inches per side, 0.2 to 2.0, one decimal). PUT /api/admin/directory/list-columns takes name_sort of full, first or last and refuses anything else.

The Directory page’s own starting point, the columns the list shows, the field the Groups view opens on and Sort names by, is the Display tab (Settings → Directory → Display), not a preset: a preset says what a file carries, Display says what the page shows before anyone changes it.

Name format

In a preset’s Document card, Name format chooses how a name is written on the file: As written; First name Last name; Last name, First name; First name Last initial; Last name, First initial; or First initial Last name. It applies to the Name column, the who’s-who cards and the names in the Assistant column, so “Smith, Jane A.” prints as “Jane Smith”, “Smith, Jane”, “Jane S.”, “Smith, J.” or “J. Smith”. Honorifics, suffixes and credentials come off the way the name sort already drops them, a surname with particles stays whole (“van Beethoven, Ludwig”) and its initial is the surname proper’s (“Ludwig B.”, and “Maria C.” for “de la Cruz, Maria”), and a one-word name prints as it is. Sorting is separate: Sort by still reads the stored name.

Section order

When a preset makes sections (Order and filter → Sections by), a Section order list opens under the field: one row per section, with the heading the file prints and how many people it holds, counted over the people the preset prints (its Only people where filter applied). The rows start in the field’s own order, the one every export used until now: a field with options in their order, any other value alphabetically. Move a section up or down to print it earlier or later; Reset to field order goes back to the field’s own. A value that is not in the list, a new office or a value nobody had when you set the order, prints after the listed sections, in the field’s order, and “No ” always comes last. Changing Sections by starts the order over for the new field. The PDF’s table, its two- and three-column layouts and the photo cards, the CSV’s Group column and the contacts export all follow the order, and a One file per zip split by the same field names its files in it. The Groups view on the Directory page keeps the field’s order; this is the file’s. When the field’s options name heads, a Section heads first toggle sits with the list and each row names its section’s head under the count (see Section heads).

Through the API, a preset’s section_order lists the group values (an option’s value, else the value as stored; up to 200), GET /api/admin/directory/export-presets/sections?field=<key> answers the sections with their counts (filter takes the preset’s filter as JSON), and POST /api/directory/export accepts section_order as an override; a request that sends its own group_by without one, as What I see does, prints in the field’s order.

Markers

The Markers card at the top of the Export page defines the symbols an export can print in front of a name for people who match a field value: a public notary, a partner, a first-aider. Each marker has a symbol (an asterisk, a dagger, or any character the PDF can print, up to three), a name for the key, the field it reads (any field but the name and the link columns: a synced attribute, a custom attribute, a manual one) and the value that earns it. The value matches the way Only people where matches: the stored value, an option’s code or its label, case-insensitively, and any one value of a multi-valued field. Leave the value blank to mark everyone who has any value in the field. Save the markers with their own Save markers; up to 24, and a symbol the PDF cannot print is refused by name. Add a marker puts you in the new row’s name; Remove moves you to the next row, or back to Add a marker when the table is empty.

Each preset then ticks the markers it prints under Columns → Mark people with. On the PDF the symbols sit in front of the name in the table and on the cards (*† Smith, Jane), every assistant’s name carries the assistant’s own symbols, and the footer prints the key on every page, one marker after another separated by a middle dot. The CSV carries the symbols in the Name column and, since a spreadsheet has no footer, ends each row with a Markers column listing the labels (“Public notary; Partner”). The contacts export (.vcf) ignores markers. An export made by someone who is not a directory admin prints only the markers the preset lists, and a marker on a field they may not see (a contact column kept for admins) is left out of its key and its Markers column altogether. Through the API: GET / PUT /api/admin/directory/markers, and a preset’s markers (marker ids; as an export override, a non-admin can drop one of the preset’s markers but not add one) and name_format.

Who’s who: photo cards

A preset’s Layout can be Photo cards instead of the table: a grid of two to five cards a row, each with the person’s photo (the 240px one the sync or an upload stored; initials otherwise), their name, title and department, and the preset’s other columns beneath — in the preset’s sections and order. Turn on Photos for the pictures; the office blocks still close the document. Four a row suits portrait letter; five wants landscape.

One file per office

One file per on a preset makes a zip instead of one document: a PDF (or CSV) for each value of the chosen group-by field — every office its own sheet, each titled with the office, named after it inside the zip. The Export menu marks such presets ZIP. So does the preset list on the Export page. Any export can ask for it ad hoc with split=office (or any group-by field key); split=0 asks a zipping preset for one file.

Presets that email themselves

The Schedule group on a preset sends the file it makes — weekly on a weekday, or monthly on a day of the month, at a UTC hour, as PDF or CSV — to the addresses you list, as an attachment. It is the same file the button makes, split into a zip when the preset says so. A schedule starts from the moment you save it, so the first send is the next slot rather than the one that already passed; if the app was down at the hour, the next hour catches up, once. The panel shows when each preset last went out and whether it worked; SMTP comes from Settings → Notifications. Until it is set up, the group says so and the schedule is kept without sending. A preset with a schedule carries a Scheduled chip in the list, with the schedule written under it.

Download links

A download link puts a preset’s file one click away from an email, a Teams message or an intranet page: “The phone list is here” with the link, and whoever clicks it gets the current list, made that moment.

To copy one: under Settings → Directory → Export, open the preset; its Download link group has the link with a File picker (PDF, CSV or contact cards, .vcf; a preset that makes one file per office sends its PDF and CSV as a ZIP, and the picker says so) and Copy link, plus an icon that opens the link in a new tab to try it. On the Directory page, Export ▾ → Copy download link… does the same for anyone who can export, with the preset to pick. A new preset has its link once it is saved; while the page has unsaved changes, the link serves the preset as last saved.

When someone clicks it:

A signed-out visitor goes to the sign-in page first (password or SSO) and comes straight back, as with a link to a document.
The link opens a page that starts the download at once. It says “Preparing your PDF…” while the file is made (a few seconds for a large directory), then Downloaded with the file name once it is in their downloads folder.
Back to home takes them to the dashboard; Download again fetches a fresh copy. If the browser blocks the automatic download, a Download it directly link sits under the status, while the file is made and after; taking it hands the download to the browser, which shows its progress. Coming Back to the page from the dashboard shows “Downloaded” again rather than downloading a second copy; reloading the page, or opening the link afresh, downloads a new one.

The file is made for the person who opens the link, from what their own account can see: admin-only fields, restricted contact columns and hidden people stay out exactly as in their own Export menu, whoever copied the link. The link itself carries no secret and grants nothing, so it is safe to paste anywhere your colleagues read; someone without access to the directory is told so instead of getting a file.

Links look like https://<your domain>/directory/download/phone-directory (with ?format=csv or ?format=vcf for the other files) and use the workspace’s custom domain when one is set (Settings → Domain & HTTPS). The last part is the preset’s id, which a preset takes from its name the first time it is saved and keeps: renaming a preset never breaks its links. Deleting one does: its links then open a page saying “This download link no longer works” with a way to the directory, rather than serving a different list. A deleted preset’s id is not given to a preset made later in the editor, so a new “Phone directory” made after the old one was deleted gets a link of its own (phone-directory-2); send that one out. (Through the API, a preset saved with an explicit id keeps it, which is how to bring a deleted preset’s links back on purpose.) The export rate limit applies (30 a minute per person); a refusal, or a download cut off half way, is said on the page with Try again. Each download is an Exported directory entry in the audit log, with via: "link".

Office information on the PDF

A PDF closes with a block for every office that appears in it: the Phoenix sheet (a preset filtered to Office = PHX1) ends with the Phoenix address, main line, fax, parking and shared spaces; a firm-wide list ends with one block per office. The blocks sit after the last row of the table — a block that does not fit in what is left of the last page moves whole to a new one. The blocks stand side by side — one to four to a row, chosen per preset. What the blocks say is set up under Settings → Directory → Offices (below); each preset has an Office information switch, on by default, and the Export menu has one for “what I see” exports.

Managing entries (admins)

The directory’s settings are six pages under Settings → Directory — People, Display, Fields, Offices, Export and Sync — with a tab row under the section header. Display holds the Directory page defaults: the columns the list opens with, the field the Groups view opens on, and how names sort. On People, admins can:

Add people by hand — name plus any of title, department, email, phone, mobile, office, custom fields and people links. Available in every edition.
Edit anyone, synced people included. On a synced person the name, title, contact details and office belong to the provider and are shown read-only; every custom field is yours, shown next to the synced value with a use synced value link to clear your override. Your values survive every sync.
Link people — pick assistants (or the people someone assists) from either end; a link the sync made shows as synced and is changed in the identity system, a link you made is kept when the sync runs.
Pin people to the top of every view and order them.
Hide any entry (including synced ones) from the directory without deleting it — hidden entries survive future syncs and never appear in a link.
Fix the blanks — a “No office” or “No department” section on the Groups view links admins to the People page filtered to exactly those people.

Directory health

The People page opens with a Directory health card: what the data says needs a hand, each with a count, a few names, and a link to the page that fixes it.

Finding	What it means
No office / title / phone / email	The value is blank (phone counts a mobile).
Values not in the option list	A choice field holds something its options don’t know — those sort after the real options as strays. Add an alias or fix the person.
Two people share a name	People links by name can’t tell them apart; add emails.
Reporting lines loop	Someone reports, through others, to themselves; fix Reports to on one of them.
People references that matched nobody	The last sync’s unresolved assistant (or other people-field) values.
Sync has not run recently	A provider that used to sync has gone quiet for more than a week.
Hidden entries / no photo	Worth knowing, not urgent.

When there is nothing to fix, the card is one quiet line.

Import from CSV

Import from CSV on the People page takes the file the export produces — or any spreadsheet with a name or email column — in three steps, and writes nothing until the last one:

Read columns. Upload or paste the file (commas, semicolons or tabs; the first row is the header). Each column gets a suggested target — a built-in like Title or Office, any custom field, or a people field such as Assistant (names or emails, several separated by ;). Set the ones it guessed wrong to ignore or the right field.
Check what would happen. Every row is listed with what it would do: Add a new manual entry, Update an existing person (and which fields), Unchanged, or a problem it names — no name and no email, a duplicate email in the file, a name two people share. Rows match people by email first, then by exact name.
Import. Only the adds and updates go through; problem rows are left out for you to fix in the file and check again.

A row that matches a synced person updates only the manual layer and links — the provider still owns name, title, contact details and office — so the import never fights the next sync.

A person you type in by hand before a sync runs is adopted by the sync that later matches their email — same row, now owned by the provider — so their links, pins and custom values carry over.

Offices

Settings → Directory → Offices describes each office beyond the people in it. The page lists every office the directory knows — the Office field’s options first (in your order), then any value people carry that has no option, then offices you add by hand for a location nobody is in yet — with a head count and a dot that says whether anything has been entered. Pick one and fill in its fields.

The fields are yours: Address, Main phone, Fax, Hours, Parking and Shared spaces to start, and any you add (a mail stop, a security desk, a conference-line PIN), renamed, reordered, or marked multi-line so an address or a room list keeps its line breaks and takes a full row on paper. Fields and values save together with one button.

An office’s block prints only if it has something in it, and only on exports that include at least one of its people.

Directory fields

Settings → Directory → Fields lists every attribute the directory shows, built-in columns (Title, Department, Office, Assistant) included. A field has:

a kind — text (anything), choice (one of the options you define), or people (links to other directory entries, shown from both ends with an inverse label such as “Assists”);
options — an ordered list of values, each with an optional label, aliases, and a colour, and, on a field the directory can make sections by, heads: up to five people who head that section (a department’s head, an office’s manager), picked by name under the options table, each shown with their own value for the field (see Section heads). The order is what the Groups view, sorting and exports follow. The label is what a code shows as (PHX1 → “Phoenix”, or “PHX1 – Phoenix”, or the raw value — your choice). Aliases fold raw values into one option: *Attorney*, Partner, Of Counsel → Attorney, with * as a wildcard. Values seen in data lists what the field actually holds, with counts, and flags anything that matches no option — add it as an option, or fold it into one, in a click;
a display — text, chips, or a phone number (dialable);
group by, show on cards, show beneath another field (a legal group’s chips under the department), and for chips whether they use the accent colour (they are neutral by default);
(Enterprise) a mapping per connected provider — see below.

Built-in fields can’t be deleted, and a custom field can’t take a built-in key. Deleting a custom field removes its values from every person.

Section heads

Many organisations keep their department heads in an executive or admin department. Give the option its heads under Settings → Directory → Fields → Options (the Heads list under the table names each option; a picker searches people by name and shows where each one sits), and the head leads that section wherever it is made, whatever their own value: on the Directory page’s Groups view the group lists its heads first with a Head chip, and its heading reads “Engineering (13) · Head: Jane Smith”; on a PDF whose preset makes sections by the field, each section starts with its heads as rows like any other, the name followed by “ · Head“ (after the name format and any marker symbols), the heading carries “ · Head: Jane Smith“, and a head who sits in the section they head prints once, at its top. Every file of a One file per zip draws its heads from everyone the export covers, so a head whose own value is another section still leads their section’s own file. A head whose own value is another section is an ordinary row there too. The CSV says it in a column instead: once any sections field has a head, every row ends with Section head of, the sections the person heads (“Engineering; Design”), sectioned or not. A head prints once in the CSV, where their own value puts them (a head of the section they sit in leads it), as in the contacts export, so Section heads first changes no row of a spreadsheet. The contacts export is unchanged.

A preset’s Order and filter card gains Section heads first (on, and shown only once the chosen Sections by field has a head): off, heads print only where their own value puts them, and the Section order list names each section’s head under its count while it is on. Heads are drawn from the people a file prints, so a head left out by Only people where, or by what is on screen for What I see, leads no section in that file. Someone hidden or removed from the directory stops heading a section at once. A rollback to 1.12.x reads a field with heads and ignores them; saving that field on the older build writes its options without their heads, which must be picked again after the re-upgrade.

In the API an option’s heads is a list of directory person ids (GET / POST /api/admin/directory/fields, PATCH …/fields/{id}; a list that holds a non-number, more than five, or someone the directory does not have is refused with 400), a preset’s section_heads is a boolean that POST /api/directory/export also takes as an override, and GET /api/admin/directory/export-presets/sections names each section’s heads ([{ id, name }]).

Mappings (Enterprise)

A mapping tells the sync how to fill a field from a provider’s record. It is no longer a single property name:

Mapping	Example
A property	`officeLocation`, `onPremisesExtensionAttributes.extensionAttribute3`, `businessPhones.1`, Google’s `organizations[primary].title`
Compose	`{officeLocation} – {city}` — a separator beside an empty part is dropped
Extract with a pattern	`businessPhones` with `x(\d{2,5})$` → the extension
First of several	try an extension attribute, then derive from the name
Group membership	each provider group a person is in contributes a value — a practice-group field from your Entra or Workspace groups
Derived	initials from the name, or the part of the email before `@`

What the records hold lists every property the stored records actually contain, with how many people carry a value and a sample — click one to map it. Click Preview before saving: the mapping runs over the records the last sync stored and reports “fills 84 of 96 synced people”, samples, and the distinct values it produced. Saving applies the mapping to everyone immediately — no resync. Built-in fields take mappings too, so Office can be composed from two properties rather than typed as a code.

People fields from Entra. Microsoft Graph has no assistant property — the on-premises AD assistant and Exchange msExchAssistantName fields never reach it — so there is nothing named “assistant” to pick. A people field maps to wherever your tenant keeps it: an Exchange custom attribute (onPremisesExtensionAttributes.extensionAttribute1…15) or a directory extension holding emails, sign-in names, object ids, display names (“Dana Ruiz” or “Ruiz, Dana”), mail nicknames, SAM account names or distinguished names (CN=Dana Ruiz,OU=…), separated by commas or semicolons — and you say which way it points: the value on an attorney lists their assistants, or the value on an assistant lists the people they assist. Object ids are the robust choice (a renamed sign-in name still resolves); a display name two people share links nobody, and the sync report says so. Letter case never matters: Dana.Ruiz@Firm.com names the account Entra holds as dana.ruiz@firm.com, so a case-only change that Entra Connect did not carry over cannot break a link.

Distinguished names. AD’s own assistant attribute, synced through a directory extension, holds the assistant’s distinguished name, and a name in the “Last, First” form is escaped in it: CN=Ruiz\, Dana,OU=Staff,DC=firm,DC=com (or \2C, or CN="Ruiz, Dana"). Since 1.14.1 the escaped comma is read as part of the name, and the sync also asks Entra for each person’s own on-premises distinguished name, SAM account name, on-premises sign-in name, mail nickname and proxy addresses whenever a people field is mapped. A DN then names the exact account it points at, whatever escape spelling it uses, even when two people share a name or the CN is not the display name; a DN that is nobody’s own (the assistant moved OU and the attribute kept the old DN) falls back to its CN as a display name. Several DNs in one value (a multi-valued attribute, or a DN after an address) are told apart and linked one by one. A SAM account name or mail nickname two people hold (they are unique only within one AD domain) links nobody and is reported, like a shared display name. Earlier releases matched a DN only by its name and left a “Last, First” one unmatched; the first sync after the upgrade fills the missing links, and a DN that still matches nobody is listed whole on the sync panel. The manager relationship is available as manager.mail (or manager.userPrincipalName) for a “Reports to” field, or, pointed the other way, for a field that lists a manager’s reports. References that match nobody are listed on the sync panel and retried on every sync. On Google Workspace, relations[assistant].value reads the assistant relation; a bracketed word other than primary keeps the entries whose type matches.

Two layers. What a sync produced and what an admin typed are stored separately; the admin’s value wins per field, and a value cleared at the provider clears here on the next sync. Manual-only workspaces use the same registry with no mappings — options, groups, pins and exports work identically.

Microsoft 365 sync (Enterprise)

With the Enterprise edition and the directory_sync entitlement, the directory fills itself from your Microsoft Entra tenant — users, titles, departments, phone numbers, offices, and profile photos — plus whatever your mappings read, and membership of the groups they depend on.

The fast way — one click

On Settings → Directory → Sync, click Set up automatically with Microsoft, then sign in at microsoft.com/devicelogin with the code shown, as a tenant admin. CompassDocs creates the app registration with the User.Read.All and GroupMember.Read.All application permissions, grants admin consent, mints a 24-month client secret, and fills in the configuration. Then choose your filters and click Sync now.

The one-time sign-in token is discarded afterward, and the panel shows the secret’s expiry date — set a reminder to rotate it. Prefer manual setup (or your tenant blocks the device-code flow)? Steps below.

1. Register an app in Microsoft Entra (manual)

In the Entra admin center, go to App registrations → New registration. Name it e.g. CompassDocs Directory; no redirect URI is needed.
Under API permissions → Add a permission → Microsoft Graph → Application permissions, add User.Read.All (and GroupMember.Read.All if you’ll limit the sync to a group or map group membership), then click Grant admin consent.
Under Certificates & secrets, create a client secret and copy its value immediately (it’s shown once).
From the app’s Overview page, note the Directory (tenant) ID and Application (client) ID.

2. Connect it in CompassDocs

In Settings → Directory → Sync, enter the tenant ID, client ID, and client secret (stored write-only — never shown again), choose your filters, and click Sync now.

Teams presence

Show Teams presence on the Microsoft 365 sync settings puts a dot on every synced person’s avatar — on cards, in the list, on the grouped tiles and beside the name on their profile — that reads Available, Busy, In a meeting, Do not disturb, Away or Offline, live from Microsoft 365 while the page is open (refreshed every minute, one request for the whole page). Hover for the detail. From 1.17.0 it shows on the dashboard’s My team tile too.

It needs the Presence.Read.All application permission on the sync’s app registration. The one-click setup grants it; a registration you made by hand gets it under API permissions → Add a permission → Microsoft Graph → Application permissions, then Grant admin consent. Without it the directory simply shows no dots. Presence is only ever read, never stored.

Keeping the junk out

Real tenants are full of service accounts and shared mailboxes. The sync excludes disabled accounts always and guests by default, and offers:

Control	Effect
Require a job title	Skips accounts with no title — cuts most service accounts.
Require a phone number	Only people with a business or mobile number.
Limit to an Entra group	Sync only the (transitive) members of one security group — the cleanest option for large tenants.
Sync profile photos	Small (48 px) photos, stored locally.

Synced entries are labeled Microsoft 365 in the admin list. You can hide individual synced people; hides persist across syncs. People who leave the tenant (or stop matching your filters) are removed on the next sync — manual entries are never touched.

One exception: a sync that would remove more than half the people it previously synced holds those removals back and says so, on the assumption that a credential or filter broke rather than that most of your staff left. The panel then offers Sync and remove the N to allow them once. Syncing again without it won’t clear the hold.

The panel also reports how many people have a stored record (what mapping previews run against), how many hand-typed entries the sync adopted, and any people references that matched nobody.

Google Workspace sync (Enterprise)

Google Workspace connects alongside Microsoft rather than instead of it — each provider owns the people and groups it synced, so neither removes the other’s.

Under Settings → Directory → Sync (Google Workspace), you need two things:

A service-account key. Create a service account in the Google Cloud console, download its JSON key, and paste the whole file. CompassDocs checks it as you paste — the wrong file or a truncated copy is refused there and then, rather than failing later with an error that points somewhere else. The key is encrypted at rest and never shown again; only its client ID is displayed, because that’s what the next step needs.
An administrator to impersonate. Google’s Directory API has no application-level access — a service account reads the directory by acting as a real admin through domain-wide delegation. Without this, every call fails with a permissions error that looks like the key is wrong.

Then, in the Google Admin console under Security → API controls → Domain-wide delegation, add the client ID CompassDocs shows you and authorise the three read-only scopes it lists. They’re displayed for copying because the delegation screen wants them comma-separated, and one wrong character produces an unauthorized_client error that doesn’t say which scope.

Checking it before you rely on it

Test connection does a single cheap read and reports what it found — the domain it reached and how many users are visible. It’s worth clicking before the first sync, because the two things that go wrong here (delegation not saved, wrong impersonation target) produce API errors that read like a bad key. CompassDocs translates both: unauthorized_client becomes check the client ID and scopes in domain-wide delegation, and invalid_grant becomes check this is a real administrator.

What the sync pulls

Sync people now imports everyone in the account (or just one group, if you set the group filter), mapping:

Google	CompassDocs
`name.fullName`	Name
`primaryEmail`	Email
Primary organization’s `title` / `department`	Title, Department
`phones` (work, then mobile)	Phone, Mobile
Primary location’s building/area/desk	Office
`thumbnailPhotoUrl`	Photo (optional)

Suspended accounts are excluded unless you turn them on; archived accounts always are. Every field mapping with a Google source — including custom schemas like customSchemas.HR.employee_id, and relations.value for a people field — fills on every sync. Google is only asked for custom-schema data when a mapping actually needs it, since that’s a heavier read.

Import groups brings Workspace groups in as CompassDocs groups you can grant on private spaces. Membership resolves by the member’s Google user id, which is how an account linked through Google sign-in is recorded, then by email address. Since 1.16.0 an email matches only when it is confirmed and exactly one account has it confirmed: an email a person typed on their own profile is Unconfirmed until an admin confirms it (see Users & roles). A group member with no CompassDocs account is skipped, and the panel tells you how many were; a member whose email isn’t confirmed on exactly one account is skipped too. Nested groups are followed, so a member of a group inside a group still lands in the right place.

Google-synced entries are labeled Google Workspace in the admin list and are owned by that provider: a Microsoft sync never removes them, and hiding one survives future syncs, exactly as with Microsoft 365.

Preview, schedule and reports (Enterprise)

Both providers share three controls on Settings → Directory → Sync.

Preview (beside Sync now) fetches from the tenant or the Workspace account exactly as a sync would and shows who would be added, changed (with the fields that differ), removed, or adopted from a hand-typed entry — and whether the removal brake would trip — without writing anything. Run it after changing a filter, a group, or a mapping. A real sync reports the same breakdown when it finishes.

Schedule & reports runs each provider on its own — every hour, or every day at the UTC hour you pick — from the hourly maintenance tick, one instance at a time. Scheduled runs never allow removals past the brake; if it trips, the report says so and the Sync page offers the one-time override. After each scheduled run an email goes to the recipients you list (SMTP from Settings → Notifications) with:

people synced, added, changed (and which fields), removed, adopted;
the removal brake, if it held anything back;
people references that matched nobody;
a link to the Sync page.

A run that changed nothing sends no email unless you turn on Email even when nothing changed. The panel shows when each provider last ran on schedule and what it did.

Linking accounts to directory entries

CompassDocs accounts can be linked to their directory entry, which powers byline links, profile “documents by” lists, and keeps them working even when a name changes on either side. From 1.17.0 it also powers the dashboard’s My team tile and the Team compliance tile, which find you, and the people who report to you, through these links. Links are made automatically — by SSO identity first, then email — via the Auto-link directory button in Settings → Users, and after every enterprise directory sync. Since 1.16.0 an email links an account only when it is confirmed and no other account has it: an email a person typed on their own profile is Unconfirmed until an admin confirms it (see Users & roles). Links already made are kept.

CompassDocs service status