Skip to main content

Approval Routing

When an agent pauses with delegate_to_human, ZenSearch picks the right person to ask. This page covers the inputs that make that routing accurate: the org chart, on-call schedules, and service ownership.

Automatic policy approvals are different: they are visible in the originating chat surface and the Governance queue, and team admins or owners decide them. The resolver described here applies to delegated human approvals.

Why this matters​

Without routing config, every delegated approval falls back to the team owners — which works, but means a 24/7 on-call rotation can't be honored, sub-team managers don't get the requests their reports trigger, and "who owns the Salesforce connector?" is anyone's guess.

Set these inputs once and approvals route themselves correctly going forward.

Org chart​

The org chart tells ZenSearch who reports to whom — used to escalate approvals to a requester's manager when no closer match exists.

Importing the chart​

In the team admin dashboard, open Org Chart and upload a CSV with one row per person:

email,reports_to_email,title,department,job_role
[email protected],[email protected],Staff Engineer,Platform,IC
[email protected],[email protected],Engineering Manager,Platform,Manager
[email protected],,VP Engineering,Engineering,VP
ColumnRequiredNotes
emailYesMust match an existing team member.
reports_to_emailNoEmpty for top of chart. Cross-team reporting is not modeled.
titleNoFree-text job title.
departmentNoFree-text department.
job_roleNoOne of IC, Manager, Director, VP, Exec. Used for role-scoped procedures and routing.

Header order doesn't matter — only column names. Unresolved manager emails are reported in the upload response so you can fix and re-upload.

Auto-sync from your IdP​

If your identity provider includes manager / department / title claims in the SSO token (Okta, Azure AD, and Google Workspace can all be configured to do this), ZenSearch upserts org chart rows on each sign-in. Empty claim values don't clobber populated ones — the CSV import remains authoritative for fields the IdP doesn't provide.

On-call integrations​

Connect PagerDuty or Opsgenie to route approvals to whoever is actually on-call right now.

In the dashboard, open On-Call, pick the provider, and complete the OAuth flow. ZenSearch:

  • Imports the schedules visible to the connecting account
  • Refreshes shifts on a daily cycle so the lookahead window stays current
  • Maps on-call user emails to ZenSearch team members so approvals can resolve to the right person

Unmapped on-call users (someone in the rotation who isn't a ZenSearch member) are skipped cleanly — the resolver continues to the next fallback.

Service ownership​

Service ownership tells ZenSearch which team owns which connector or collection, so a delegated approval about (say) the Salesforce connector can page the team that runs Salesforce, not just the team that triggered the action.

In the dashboard, open Service Ownership and add mappings:

  • Map a connector ID or a collection ID to an owning team
  • Each mapping is exactly one connector/collection → one owning team
  • Mappings are scoped to the team that configured them; a mapping by team A doesn't affect team B's routing

The agent doesn't have to know about ownership, but the proposed action must include a ZenSearch connector_id or collection_id either at the top level or inside its params object. The resolver uses that ID to find the service owner and current on-call user.

How resolution works​

When a delegated approval pauses, ZenSearch tries (in order):

  1. Explicit approver UUID supplied as preferred_approver
  2. Preferred approver email supplied as preferred_approver, if it matches a team member
  3. Service owner + on-call: if the action references a known connector or collection and a service-ownership mapping exists, find the owning team's current on-call person
  4. Manager: the requester's manager from the org chart
  5. Team owners: the final fallback

Each step that has nothing to return falls through to the next; you don't have to configure everything for routing to work — you'll just rely more on team-owner fallback for the gaps.

Service ownership and on-call are a combined step. If the service owner has no active mapped on-call user, ZenSearch continues to the manager fallback rather than notifying a generic service owner mailbox.

Best practices​

  1. Import the org chart first — it's the cheapest input to set up and the one most fallbacks depend on.
  2. Connect PagerDuty / Opsgenie before you wire up sensitive automations. Otherwise off-hours approvals route to managers who may not respond promptly.
  3. Map service ownership for the few connectors that get the most write-action approvals; you don't need to map every connector.
  4. Keep approver identities current — when someone leaves, remove their team membership before they show up on a rotation.