Directory Records

A directory record is Roster’s normalized representation of a user, group, organization unit, role, or external email from an external provider. Directory records give participants and the resolver a stable Roster record to reference without treating Roster as the source of truth for identity data.

Directory records are separate from authentication identities. An identity authorizes access to Roster. A directory record represents someone or something that may handle workflow responsibility.

Record Types

Type	Represents	Common use
user	Human or service user from a provider directory.	Direct participant membership and delegated coverage.
group	Provider group or distribution list.	Participant membership that expands through group members.
org_unit	Organization unit, department, cost center, or region.	Routing context, metadata, and organization membership.
role	Provider or business role.	Responsibility context and role-based membership.
external_email	Email address that is not backed by a provider account.	External reviewers, contacts, or escalation recipients.

What Records Contain

Directory records keep a small canonical profile:

• record type
• display name
• primary email when available
• description
• source links
• metadata
• membership edges

The canonical profile is intentionally narrow. Provider-specific fields stay on explicit source fields or allowlisted metadata so Roster can search, resolve, and audit directory data without copying every provider attribute into the primary record.

When multiple sources are attached to the same record, the primary directory source owns the canonical profile fields such as display name, primary email, and description. Secondary connector values stay on directory_record_sources and directory_record_metadata so source-specific differences remain visible without overwriting the canonical record.

Sources

A source record connects a directory record back to one provider connection. It stores the provider, external ID, source type, source display fields, and refresh timing. Raw provider payloads are not stored.

Source records preserve provenance. When a record is enriched by another connector, Roster can keep the stable directory record while recording which provider supplied each source value.

Metadata

Directory metadata stores structured provider or business context such as:

{
  "department": "Finance",
  "region": "EMEA",
  "cost_center": "FIN-420"
}

Metadata values can be text, number, boolean, timestamp, or JSON. Metadata may also reference the source that supplied it, which lets admins understand where a resolved value came from.

Memberships

Directory records can be linked to other directory records. A group can include users, an organization unit can include members, and a source connector can mark whether the relationship is direct, transitive, or organization-based.

Roster uses these relationships during participant and delegation resolution. Member listings on a participant show direct participant associations. Resolver behavior can expand those associations using directory membership and active delegations.

Operational Boundaries

Roster does not edit upstream provider accounts. Connector refresh jobs update already-cached directory records, sources, and metadata from provider data. For cached group records already attached to participants, refresh jobs also reconcile direct membership edges in participant_record_members. They do not import every upstream user or group, and they do not sync unrelated upstream group memberships.

Use participant membership to decide which records can handle workflow action. Use identities, roles, scopes, and project ownership to decide who can manage Roster itself.