Documentation

Directory synchronization

Version v2.5.1 · Updated
Interactive docs View on GitHub

Directory synchronization#

Directory synchronization imports teams, people and on-call schedules into IncidentRelay. IR reads the external API at the interval you choose. It does not send local changes back to that system.

A source is one connection: its API address, credentials, requests, field mapping and update rules. Each source belongs to one destination group in IR.

Before you start#

RequirementPurpose
An administrator accountGlobal administrators can choose any active group. Group user administrators can configure sources only in groups they administer.
The external API addressFor example, https://org-service.example.com, where the teams and schedules live.
External API credentialsFor org-service, a PAT that can read teams, employees, schedules and current duty.
A running IR schedulerIt processes previews, applies imports and runs periodic updates.
Network access from IRBoth web and scheduler processes must resolve the API hostname, reach its port and trust its TLS certificate.

When upgrading, run python manage.py migrate before starting the updated web and scheduler processes. See Scheduler and Installation.

The two connections use different tokens. The source's authentication headers contain the external system's token. An IR personal token is needed only when a script configures IR through its API. Configuration through the interface uses your existing IR login session.

First import through the interface#

1. Open the source form#

Go to Administration → Directory synchronization → Add source. Configuration opens in a modal. Configure on an existing source opens the same modal for editing.

The form already contains requests and mapping for org-service. Keep these defaults when connecting that system and enter your own connection details. For another API, use the request and mapping guides below.

2. Enter connection details#

FieldWhat to enter
NameA recognizable name, such as Platform on-call.
Destination groupThe IR group where teams should appear. This cannot change after creating the source.
API base URLFor example, https://org-service.example.com. The operations already contain the /api/v1/... paths.
Network accessUse public networks for a public API. For an internal API, configure the server allowlist and select the server-allowed networks option.
Skip TLS certificate verificationOff by default. Enable to connect to an API with a self-signed certificate without configuring CA trust. Disables certificate and hostname verification for this source only.
Authentication headersJSON headers expected by the external system.

For org-service:

{
  "Authorization": "PAT replace-with-your-PAT"
}

For a Bearer-based API, the value would be Bearer your-token. Use the external API's actual authentication scheme.

Headers are encrypted. The field becomes blank after saving because the server never returns the secret to the browser. On later edits, leaving it blank preserves existing headers, a new JSON object replaces them, and {} clears them. Keep tokens out of URLs and mapping fields.

3. Save the initial settings#

For the first import, the defaults are a useful starting point:

  • Full synchronization: 3600 seconds, once an hour.
  • Current-duty refresh: 60 seconds.
  • Calendar horizon: 2 months, the current and next month.
  • Local edits, managing matched existing teams and deleting missing objects: off.
  • Membership authority: Synchronization API.

Click Save configuration in the modal footer. The modal remains open. Saving creates the connection settings; teams and people are created when you apply a preview.

4. Inspect the response#

Click Inspect response fields. IR requests the first catalog page and displays field names and types, for example:

{
  "teams": [{"enrolledScopeUuid": "str", "name": "str"}],
  "nextPageToken": "str"
}

str means a string, not a real team name or ID. This checks the catalog connection and helps you select mapping paths. The other requests are exercised by the preview. After changing operations or mapping, save before checking again.

5. Preview and match teams#

Click Preview changes. The scheduler runs the job and the modal updates when it finishes. You can close it while waiting: the job continues. Click Configure again to retrieve its current state.

ActionWhat applying the preview will do
createCreate a user, team, membership, rotation or shift.
updateChange the listed object fields.
skipLeave a matched team unchanged because managing existing teams is off.
deleteRemove a missing managed object or deactivate its membership.

A preview stores the plan without changing teams, people or schedules. Review membership, planned changes and especially delete rows.

Once the catalog has loaded, the mapping section offers selectors for matching external teams to existing teams in the destination group. Without an explicit match, IR looks for one exact name match; if there is none, it creates a team. Multiple matching names require an explicit choice. Also enable Manage matched existing teams if the source should update that team.

After changing matches, save and request a new preview. Once applied, an external team's stored identity cannot be rebound to a different local team.

6. Apply and enable updates#

Click Apply preview within 15 minutes. If it has expired, or local data has changed enough to alter the plan, request another preview.

After a successful application:

  • Check the imported teams and rotations in IR.
  • Enable Periodic synchronization enabled in the source settings.
  • Click Save configuration.

Run now performs the next full import without waiting for its interval. The source list shows status, any error and the last successful import time.

Choosing update behavior#

SettingOffOn
Allow local editsImported resources are protected against manual edits.Local edits are allowed. The next import replaces matching imported fields.
Manage matched existing teamsPre-existing teams are skipped.The source can update matched teams. A team owned by another source cannot be adopted.
Remove missing managed objectsObjects that stop appearing are retained.A complete successful import removes only objects managed by this source.
Periodic synchronization enabledAutomatic refreshes are paused.Full imports and current-duty refreshes run on schedule.

Teams created by the source continue to update regardless of the setting for matched existing teams. Shared and pre-existing user profiles are not overwritten.

Team and rotation removal uses IR soft deletion. Shift removal is limited to the successfully fetched window. When a person leaves, owned memberships are deactivated; the global account and OIDC identity remain. A failed request does not delete previous data.

IntervalWhat it refreshesValues
Full synchronizationTeams, profiles, memberships and calendar shifts3600 means hourly; 600 means every ten minutes. Range: 60–604800 seconds.
Current dutyActual assignments from the current operation60 means every minute. Range: 10–3600 seconds.
Calendar horizonCalendar months, including the current month2 in November includes November and December. Range: 1–11 months.

Window boundaries use UTC. For example, on November 10, 2026, a horizon of 2 requests 2026-11-01T00:00:00Z through 2027-01-01T00:00:00Z.

To change an active source, uncheck periodic synchronization, edit and save. Configuration or credential changes require a new preview and application before periodic updates can be enabled again.

Users, roles and OIDC#

Every referenced person needs a stable external ID and a valid email. On first import, IR matches email case-insensitively. One matching account is reused; no match creates an account without a local password or global administrator privileges. Subsequent imports use the stored external identity.

To let imported people sign in through OIDC:

  • Configure and enable the OIDC provider in IR.
  • Enable email linking (auto_link_by_email).
  • Ensure the directory email matches the email supplied by OIDC at login.
  • The person's OIDC login links to the existing account. auto_create_users is not required for that account.

Provider domain and verified-email policies continue to apply. Missing emails, duplicates or a matching deleted account stop the import: resolve the conflict first.

Membership authority chooses who assigns access:

  • Synchronization API (sync) creates memberships from the external roster and protects its owned roles from OIDC synchronization. Default roles are group viewer, team member responder and responsible person manager.
  • OIDC (oidc) leaves memberships and roles to configured SSO mappings. The source still imports accounts, teams and schedules. Configure the SSO mappings before people sign in.

Either option permits OIDC login. Set source roles through group_role, member_role and responsible_role in mapping JSON. Personal notification and interface preferences remain personal.

In org-service, roster means on-call participants, not necessarily every employee in a department. In sync mode, the responsible person also becomes a team member. Shift and replacement participants outside that roster receive accounts, but participation alone does not make them team members. The source also creates group access for them if absent.

Adapting another API: operations#

API operations (JSON) describe where to request data. Field mapping and membership roles (JSON) describe how to read the response, such as which field contains an email.

OperationPurposeResponse after selecting items
teamsRequired team catalog.Array of teams.
teamOptional details when the catalog does not include membership and schedules.Team object.
userOptional profile lookup when the roster does not include profile/email data.Object or one-element array; a catalog with user_fetch: all.
shiftsRequired shifts for one team and time window.Array, including [] when there are no shifts.
currentOptional actual duty lookup.Array of slot results in batch mode.

These org-service operations can be pasted as the entire operations field:

{
  "teams": {
    "method": "GET", "path": "/api/v1/support-team-catalog", "items": "teams",
    "pagination": {"mode": "cursor", "parameter": "pageToken", "next_path": "nextPageToken", "size_parameter": "pageSize", "size": 100}
  },
  "team": {"method": "GET", "path": "/api/v1/duty-scopes/{team_id}"},
  "user": {"method": "GET", "path": "/api/v1/employees", "params": {"uuid": "{user_id}"}, "items": "employees"},
  "shifts": {
    "method": "GET", "path": "/api/v1/duty-scopes/{team_id}/shifts",
    "params": {"from": "{from}", "to": "{to}"}, "items": "shifts"
  },
  "current": {
    "method": "POST", "path": "/api/v1/duty-schedules:batch-current",
    "body": {"scheduleUuids": "{schedule_ids}"}, "items": "duties"
  }
}

method is GET or a data-reading POST. path is appended to the base URL; params become query parameters; body is the POST JSON. items selects the array or object: use result.teams for {"result":{"teams":[]}}. If the response itself is an array, leave items empty or use $.

VariableValue
{team_id}External ID from team_fields.id; available in team, shifts and individual user requests.
{user_id}External person ID for individual user requests.
{from}, {to}Window boundaries for catalog, details, profile and shift requests.
{schedule_ids}External schedule ID array for current.
{schedule_id}One schedule ID with current_fetch: per_schedule.

In {"scheduleUuids":"{schedule_ids}"}, the whole value is replaced with a JSON array. URL variables are encoded automatically.

user_fetch: per_user requests individual profiles; all loads a paginated directory and selects people by ID. current_fetch: batch requests up to 500 schedules at a time; per_schedule requests each schedule separately and accepts an object or a one-element array.

Pagination#

pagination.modeChoose whenCompletion condition
noneOne response contains all records.One request.
cursorThe response supplies a next-page token.Missing or empty next token.
offsetThe API accepts offset and page size.Fewer records than size.
pageThe API accepts page number and page size.Fewer records than size.

parameter names the token/offset/page parameter; size_parameter names page size. Use start: 1 for one-based page numbering. next_path locates the cursor in the response. Org-service uses pageToken, pageSize, nextPageToken, with at most 100 records per page.

Repeated cursors and reaching max_pages fail the import. null or an error object in place of an array is not treated as a successful empty result.

Adapting another API: field mapping#

The left side names an IR field; the right side gives a path inside the external response. For this profile:

{"uuid":"person-1","contacts":{"email":"anna@example.com"},"firstname":"Anna","lastname":"Petrova"}

the user_fields value can be:

{
  "id": "uuid",
  "email": "contacts.email",
  "name": {"paths": ["firstname", "lastname"], "join": " "}
}

This is only the user_fields value. Replace that part of the mapping JSON and keep the other sections. IR receives ID person-1, email anna@example.com and name Anna Petrova.

SectionMeaningMain IR fields
team_fieldsTeam catalog entryid, name, description.
detail_fieldsAdditional team detailsname, description, enabled.
team_filterCatalog field that must be nonemptyenrolledScopeUuid for org-service.
membersTeam member arraypath plus fields with id; optional name, username, email, inactive.
responsibleResponsible person's objectpath and member-like fields, or null if unused.
schedulesSchedule slot arraypath plus fields: id, optional name, timezone (defaults to UTC).
user_fieldsProfile returned by userid, email, username, name, phone, inactive.
shift_fieldsOne shiftid, schedule_id, user_id, start, end, title, unavailable, inactive.
replacementsReplacements inside a shiftpath plus fields: id, user_id, start, end, precedence, inactive; an empty array means none.
current_fieldsActual dutySchedule id, status, user_id; optional valid_until, start, end.
team_matchesExplicit team matchesFor example, {"external-team-1":42}, where 42 is an IR team ID.

Use dotted paths such as employee.employeeUuid and person.inactive. A numeric segment selects an array index, such as contacts.0.email. $ selects the complete value.

Other mapping options:

{
  "timezone": {"value": "UTC"},
  "inactive": {"path": "state", "values": {"enabled": false, "disabled": true}},
  "phone": {"path": "contacts.phone", "default": null}
}

value supplies a constant. values translates external values into IR values. default handles missing fields or unmatched translations. inactive and unavailable must resolve to JSON booleans, not strings. Timestamps need a timezone, for example 2026-11-10T09:00:00+03:00.

Org-service identifies a team by enrolledScopeUuid, not the CMDB externalId. Filtering on this field includes enrolled teams; filtering by eligibility or schedule type can exclude some already enrolled teams. People use employeeUuid/uuid, and rotations use schedule UUIDs.

Calendar versus actual duty#

One external scheduleUuid becomes one IR rotation. Two parallel team slots create two rotations. IR stores concrete intervals without expanding recurrence again. Higher numerical replacement precedence wins; overlapping shifts in one slot do not select an arbitrary person.

The calendar shows imported intervals. With current configured, actual assignment uses its response:

StatusMeaning
activeAssign the known active person.
gapNo assignee in the slot.
unavailableThe person is unavailable.
ambiguousThe source could not determine a unique assignee.
stale in IRNo fresh response yet, or the previous response expired.

The last four states do not assign someone from stale data. Normal IR routing/escalation behavior follows. Without current, assignment follows imported shifts and replacements. Permitted local edits and ordinary rotation overrides also apply.

Responses remain usable for at most current_max_age_seconds, default 120, configurable in mapping JSON. valid_until and the effective end can shorten this period. After an API failure, the previous answer is usable only until expiry. Current duty refresh runs separately from full imports and accounts for absence changes without relying on schedule revisions.

Pausing periodic synchronization retains the calendar but lets current-duty data expire. With local editing enabled, use Imported schedule in the rotation actions to edit shifts and replacements. This form uses UTC times.

Connecting to an internal API#

The server calls the external API. A successful request from your laptop does not establish access from IR's container or host.

  • Check DNS, routing and API port access from web and scheduler.
  • Add the API IP/subnet to server configuration, for example:

``ini [orchestration] webhook_private_network_allowlist = 10.20.30.0/24 ``

  • Restart IR processes to reload configuration.
  • Select server-allowed networks in the source (private_network_policy: allowlist).
  • For an internal CA, install trust in the IR processes' environment. To connect without verifying the certificate, enable Skip TLS certificate verification in the source and save its settings.

The API setting is config.verify_tls: true (the default) enables verification; false disables it. It applies to response samples, previews, imports and current-duty refreshes. After changing it, fetch and apply a new preview before re-enabling periodic synchronization. This setting does not bypass the server allowlist or affect other sources or outbound webhooks.

Separate multiple subnets with commas. Plain HTTP also requires webhook_allow_http = true in that section. Selecting allowlist in the form does not add addresses to the server list: this uses IR's existing outbound network policy.

Check DNS, TCP and TLS in a standard Docker deployment without sending a PAT:

docker exec incidentrelay curl --noproxy '*' -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  --connect-timeout 10 --max-time 20 \
  'https://example.com/api/v1/support-team-catalog?pageSize=1'

Replace the URL with your API address and repeat for incidentrelay-scheduler: web fetches response samples, while scheduler runs imports. HTTP 401/403 is expected without a PAT and confirms an HTTP connection, but does not validate token permissions or the API path. Could not resolve host indicates a DNS failure; Connection refused indicates a rejected connection; a timeout means no response arrived within the limit. Certificate verification failures require configuring internal CA trust in both containers. --noproxy '*' checks a direct connection, matching synchronization's transport, which does not use HTTP_PROXY/HTTPS_PROXY. A successful curl request does not validate IR's server allowlist.

Connecting a script to IR#

Use the IR base URL, destination group ID and a personal token owned by an administrator of that group. Grant directory-sync:read and directory-sync:write. Legacy resources:* and team-bound tokens cannot manage these sources.

To check the connection, with the IR token in the IR_TOKEN environment variable:

curl --fail-with-body 'https://ir.example.com/api/admin/directory-sync/options' \
  -H "Authorization: Bearer ${IR_TOKEN}"

The response contains accessible groups, teams and a ready preset configuration. These group/team IDs are local IR IDs, not external UUIDs.

RequestPurpose
GET /api/admin/directory-syncList accessible sources and IDs.
POST /api/admin/directory-syncCreate with name, group_id, config, headers, enabled: false. Use the modified preset object as config.
GET /api/admin/directory-sync/{id}Read configuration, current revision, results and job status. Secrets are not returned.
PUT /api/admin/directory-sync/{id}Update with the current revision. Omit headers to preserve credentials.
POST /api/admin/directory-sync/{id}/sampleInspect catalog response shape.
POST /api/admin/directory-sync/{id}/previewQueue a preview with {"revision":1}.
POST /api/admin/directory-sync/{id}/applyApply with revision and the resulting preview_token.
POST /api/admin/directory-sync/{id}/runImport an approved configuration with its revision.

Execution endpoints return 202, meaning queued. Poll the source: pending_mode and running indicate unfinished work; last_error holds failures, preview_result holds the preview and last_result holds the application result. Current-duty failures use current_error. The full schema is available in IR OpenAPI.

Concrete shift endpoints reuse rotation permissions: GET/POST /api/rotations/{rotation_id}/imported-shifts, PUT/DELETE /api/rotations/imported-shifts/{shift_id}. Lists use after/next_cursor; user_id is an IR user ID. Local deletion remains a tombstone until the next import.

Troubleshooting#

SymptomCheck
Missing menu or IR API returns 403Group administrator role, destination group and token scopes.
Preview stays queuedScheduler: systemctl status incidentrelay-scheduler; logs: journalctl -u incidentrelay-scheduler -f. Docker: docker compose logs -f incidentrelay-scheduler.
API target blockedHTTPS, server allowlist and the source network policy.
External API returns 401/403PAT validity, permissions and header format. An IR token does not replace the external PAT.
API DNS resolution failedDNS inside both web and scheduler containers.
API TLS connection failedCA trust, certificate hostname and TLS settings in the IR environment.
API connection refused or API connection failedAPI address, port and direct network access from IR containers.
API request timed outNetwork access, API response time and timeout_seconds.
API response exceeded the 8 MiB limitReduce the API page size.
items mapping must resolve to an arrayThe operation's items path must select an array.
No teams in the previewCatalog data and team_filter; org-service needs nonempty enrolledScopeUuid.
A team is marked skipIts local match and whether managing matched teams is enabled.
Email conflictEmails for everyone referenced, including leaders and replacements; duplicates and deleted matching accounts.
Cannot enable periodic updatesApply a preview of the current configuration after edits.
Preview expired or Local data changed since previewFetch and review a new preview.
Calendar exists but no current assigneecurrent_error, current status/freshness, user activity and enabled periodic updates.

Transient failures receive up to three attempts. Limits are 8 MiB per response, 10,000 requests and 30 minutes per run, and 100,000 records per operation. Set the 1–60 second request timeout with timeout_seconds. Redirects are rejected; authentication failures are not retried. Headers and raw response bodies are excluded from errors and logs.

Response sample requests report external API failures as sync_api_error: HTTP 502 for connection or response failures, and HTTP 504 for timeouts. HTTP 409 sync_conflict refers to synchronization state, such as a busy source or stale revision. Earlier versions also returned teams: API connection failed as sync_conflict; that code alone does not prove a team conflict or concurrent run. Background execution requests still return HTTP 202; read subsequent failure details from last_error or current_error.

A full import is applied in one transaction after all data has loaded. A failed request prevents a partial result from being applied. A per-source lock limits concurrent runs, and queued work survives scheduler restarts.