Syncing your org directory from Microsoft Graph
A Microsoft Graph connection is scoped to one org tree, not to a board — it exists to build a reporting hierarchy, not to feed a project's issues. Point it at a root person and it walks direct reports down from there.
An org tree rooted at a VP, synced from Microsoft Graph.
What it does, and where the data comes from
Set a root person (their email or UPN) and Deckgauge resolves them by UPN via Graph's user-lookup endpoint, then recursively follows each user's directReports to build the whole tree beneath them. Each pass populates: name, business title, email, office location, phone, employee ID, employee type, hire date, role, and the manager relationship that reconstructs the hierarchy. Someone who drops out of the traversal (left the company, or moved outside the root's scope) is marked departed rather than deleted — their historical data stays intact.
How to connect it
- Open the org tree → Source tab.
- Open Microsoft Graph Explorer, sign in, and copy your Access token.
- Paste the token and set the root person (email/UPN) — everyone reporting up to them gets imported.
- Press Sync now.
The token model, and why sync sometimes asks you to reconnect
Three ways to authenticate, each with different expiry behaviour:
| Model | Expiry behaviour |
|---|---|
| Pasted access token (Graph Explorer) | Short-lived, roughly one hour. When it expires mid-sync, Deckgauge clears the stored token and asks you to paste a fresh one — it never silently retries with a dead token. |
| Delegated refresh token (device-code sign-in) | Long-lived and self-renewing: Microsoft rotates the refresh token on every exchange, and Deckgauge persists the rotated value after each sync so the next run doesn't fail with an invalid-grant error. |
| App registration (client credentials) | Fully hands-off — an app-only token is fetched and cached with a safety margin before each expiry, no user token ever pasted. Configure the tenant/client id and secret in the environment to use this path. |
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Sync fails: "Microsoft token expired" | The ~1-hour pasted access token ran out | Paste a fresh Graph Explorer token in the Source tab and re-sync |
| Sync fails: "Root person not found in directory" | The root UPN doesn't match a real Graph user, or the token can't see them | Double-check the email/UPN and that the signed-in account can read that user |
| Someone who left is still shown as active | They fell outside the root's reporting scope rather than being removed from the directory | Confirm the root person's scope still covers them; otherwise they'll show departed on the next sync that can't find them |
Related
- Org trees — what an org tree is and how it's used.
- Employee boards — the per-person view built on top of the tree.
- Connecting a calendar — the other Graph-backed source, scoped per board instead of per org tree.
Last updated