ORGONAUT
Login Signup
Docs
Imports and setup
Orgonaut Docs

HRIS live sync (BambooHR and Dynamics 365 HR)

Plan availability: HRIS live sync is available on the business, enterprise, and agency plans.

Use Settings → Integrations to connect a single HRIS integration for your tenant. Supported providers are BambooHR and Dynamics 365 HR.

The integrations page is visible only to roles that include integration management. In the default tenant role bundles that means owner and admin.

Astro can read HRIS connection health, recent sync status, and related operational context, but it cannot connect, pause, resume, disconnect, or rerun integration workflows for you. Those remain human-owned settings and operations.

Connect an HRIS provider

  1. Open /settings/integrations/hris.
  2. If no provider is connected, use the BambooHR or Dynamics 365 HR tab to choose a provider.
  3. Use the provider setup action to open the connection form, then enter provider credentials:
    • BambooHR: subdomain + API key
    • Dynamics 365 HR: environment URL, tenant ID, client ID, and client secret
  4. Choose where incoming changes apply:
    • Live Baseline
    • one or more active scenarios
    • all future scenarios (optional)
  5. Click Test connection to validate credentials.
  6. Save the connector to activate reconciliation jobs for the selected provider.

Webhook auth requires config_encrypted.webhook_secret on the integration record. The current UI saves subdomain + API key; webhook secrets must be provisioned through deployment/config automation before callbacks are accepted.

Dynamics 365 HR (reconciliation-only)

  • Dynamics 365 HR runs through nightly reconciliation in Orgonaut v1.
  • No Dynamics webhook endpoint is required for this release.
  • Configure Microsoft Entra OAuth2 client credentials in the integration form.
  • Workforce scope should be constrained in your source tenant (for example, legal-entity scoping and app permissions).

Webhook endpoint (BambooHR only in this release)

  • Endpoint: POST /api/v1/integrations/bamboohr/webhook/{tenant}
  • The endpoint acknowledges quickly (202 Accepted) and queues asynchronous processing.
  • Validation order:
    • X-BambooHR-Signature HMAC SHA-256 (if provided), or
    • X-Orgonaut-Webhook-Secret shared-secret fallback.
  • Payloads are processed idempotently via event_idempotency_key in integration_sync_logs.

Scheduled reconciliation

  • Nightly reconciliation runs at 02:00 server time.
  • Reconciliation uses queued jobs and writes integration_sync_logs with kind = reconcile.
  • Archived/snapshot scenarios remain read-only and are automatically excluded from writes.
  • When all future scenarios is enabled, only scenarios created after the toggle is enabled are auto-targeted. Existing scenarios remain unchanged unless explicitly selected.
  • If a tenant is downgraded below HRIS integration availability, webhook callbacks (where configured) acknowledge without queueing work and queued sync/reconcile jobs no-op until the tenant upgrades again.

Operational runbook

Initial sync

  • There is no dedicated “Run initial sync” button on the connection form.
  • Initial full-directory sync runs as a manual_sync execution in the HRIS sync engine.
  • After setup is complete, validate outcomes in Recent sync logs and drill into View run details.

Webhook processing

  1. Configure BambooHR to call POST /api/v1/integrations/bamboohr/webhook/{tenant}.
  2. Include either:
    • X-BambooHR-Signature (HMAC SHA-256), or
    • X-Orgonaut-Webhook-Secret (shared secret fallback).
  3. Confirm 202 Accepted responses and inspect queued runs in Recent sync logs.

Nightly reconciliation

  • Laravel scheduler enqueues reconciliation daily at 02:00 (integrations:reconcile-nightly).
  • Reconcile runs are logged with kind = reconcile, event_type = nightly_reconciliation.

Where to look when sync fails

  1. Open /settings/integrations/hris.
  2. Review integration status plus last sync/reconciliation timestamps.
  3. Open View run for the failed row.
  4. Check error summary, structured error JSON, run details JSON, and affected identities.

How to re-run a sync safely

  • From /settings/integrations/logs/{integration_sync_log}:
    • Re-run this sync for non-reconcile runs with an affected employee identity.
    • Re-run reconciliation for reconcile runs.
  • Reruns enqueue new jobs and preserve tenant + scenario targeting.

Important guardrails

  • Orgonaut allows only one active HRIS integration per tenant.
  • Tenant boundaries are enforced for integration-scoped API access; probing another tenant's integration ID resolves to 404.
  • The scenario target selector excludes read-only contexts:
    • archived scenarios
    • snapshots / immutable kinds
  • Sync changes mutate actor and organisational data in the selected contexts.
  • Sync-driven model mutations continue through the standard observer pipeline so audit_events remains complete.
  • Department/division mappings prefer stable BambooHR source IDs when available, so source-side renames update existing records instead of creating duplicates.
  • Actor matching now prefers actor-side Bamboo source identity first:
    • actors.source_hris = bamboohr
    • actors.source_hris_id = Bamboo employee/Person ID
  • Email is now treated as contact data and a compatibility fallback, not the canonical Bamboo identity key.
  • When a legacy actor is matched only through IntegrationIdentityMap or old Bamboo metadata, the sync self-heals by persisting the Bamboo source identity onto the actor record.

Manage an existing connection

From the same page you can:

  • Pause sync processing
  • Resume sync processing
  • Disconnect to deactivate the integration and remove stored credentials

The page also shows:

  • current status
  • last sync timestamp
  • last reconciliation timestamp
  • recent integration_sync_logs entries (shown only after a connector is configured)

Connection health notification

  • Connection health is surfaced with:
    • status badge (active, paused, error, disconnected)
    • last sync and reconciliation timestamps
    • per-run error summaries in recent logs
  • Use run detail diagnostics for full troubleshooting without exposing secrets.

Sync run detail diagnostics

Use /settings/integrations/logs/{integration_sync_log} from the View run action in the sync logs table to inspect one run in detail.

The run detail page includes:

  • provider, sync kind, status, start/finish timestamps, and duration
  • configured apply targets at run time (baseline, explicit scenario IDs, all future scenarios flag)
  • count metrics (fetched, created, updated, deactivated, errors)
  • concise error summary plus collapsible structured JSON payloads
  • paginated affected identities captured for the run (source HRIS, source ID, email, and scenario context)

Operators can queue safe reruns from this page:

  • Re-run this sync for rerunnable non-reconciliation runs with a known affected identity
  • Re-run reconciliation for reconciliation runs

Run diagnostics are tenant-scoped and never expose stored integration credentials.

Actor identity behavior

Bamboo sync uses the following actor resolution order inside each baseline/scenario target:

  1. actor-side source_hris = bamboohr + source_hris_id
  2. compatibility fallback through IntegrationIdentityMap
  3. compatibility fallback through email

This means Bamboo email changes update the same actor when the Bamboo employee ID is stable.

Manager resolution

  • Bamboo manager relationships resolve from the manager's Bamboo employee ID, not from Orgonaut actor IDs.
  • If a manager has not been imported yet, the employee keeps a deferred Bamboo manager ID and Orgonaut retries resolution later in the same run or on a later sync.

Notifications centre + email alerts

Orgonaut now surfaces BambooHR health issues through a tenant notifications centre instead of persistent in-page banners.

Header inbox + notifications centre

  • Open Profile menu → Notifications (/notifications) to review messages.
  • When unread notifications exist, a square inbox button with a red badge appears immediately left of the profile menu in the top banner.
  • Notifications support:
    • All/Unread filtering
    • Mark read / mark unread
    • Mark all as read
    • CTA links for actionable events (for example, opening a failed sync run)

Who receives system notifications

  • System integration notifications are created for tenant owners and admins only.
  • Read state is tracked per user, per tenant.

HRIS failure and recovery events

  • On integration health transition healthy → failed, Orgonaut creates an integration.failed notification and emails tenant owners/admins.
  • Email subject uses the active provider label (for example, “BambooHR connection needs attention” or “Dynamics 365 HR connection needs attention”).
  • Messages include an actionable summary and a link to run diagnostics.
  • A cooldown (default 24h) suppresses repeated alerts for the same ongoing failure.
  • On failed → healthy, Orgonaut emits an integration.recovered informational notification.