Darwinbox

The Darwinbox connector syncs the employee directory into Omni’s people directory and exposes tightly scoped, interactive HR workflow actions.

​

Overview

​

What We Sync

Each module maps to a Darwinbox API endpoint that must be enabled for your API credential — enable the endpoints for the modules you want to use:

​

What We Deliberately Do NOT Sync

The connector is designed around a curated approved field set that excludes sensitive and confidential data:

• Compensation, payroll, payslips, and tax documents
• Personal/financial fields (e.g. personal email, bank details)
• Employee documents (offer/appointment/experience letters)
• HR policy documents, announcements, and learning content (no read APIs exposed)
• Appraisal, goal, and performance data

Unknown fields returned by Darwinbox are silently ignored, so nothing outside the approved set is ever indexed.

​

How It Works

1. You provide your Darwinbox base URL, tenant credentials, and dataset key
2. The connector syncs the employee directory, org masters, job levels, employee-scoped org masters, positions, holidays, and ATS jobs, storing a checkpoint for resumable syncs
3. Employees become searchable person records in Omni; org-master, position, holiday, and ATS data becomes searchable documents
4. Interactive self-service and manager actions resolve the authenticated Omni user to their Darwinbox employee record and operate within the permitted audience

​

Prerequisites

Before setting up the Darwinbox connector, ensure you have:

• Darwinbox API access for your tenant
• Base URL for your Darwinbox instance, such as https://acme.darwinbox.in
• Dataset key for the APIs Omni should call
• One supported credential set:
  • Basic auth username, password, and API key
  • OAuth2 client credentials
  • Legacy dynamic-token credentials with an authorization code or refresh token
• Omni deployment with the Darwinbox connector service running (profile: darwinbox)

​

Setup

​

Step 1: Connect in Omni

1. Navigate to Settings → Integrations
2. Find Darwinbox and click Connect
3. Enter your Darwinbox base URL
4. Choose an authentication mode:
   • Basic auth + API key: API username, password, API key, and dataset key
   • OAuth2 client credentials: Client ID, client secret, optional API key, and dataset key
   • Legacy dynamic token: Client ID, client secret, grant type, authorization code or refresh token, optional API key, and dataset key
5. Choose participant handling for actions:
   • All users (default) — any authenticated Omni user may invoke actions
   • Allowlist — restrict actions to specific participant emails
6. The connector starts in read-only mode. Enable write mode only after configuring participant and action authorizations.
7. Click Connect
8. Click Sync to start the initial sync

​

Managing the Integration

​

Viewing Sync Status

Navigate to Settings → Integrations to view sync status, indexed counts, and errors. Click Settings on the source for sync history and source configuration.

​

Sync Modes

​

Search Operators

The connector registers source-specific operators that work in Search and Chat once the source is running: To look employees up by name, email, title, or direct manager, ask the assistant in chat — it queries the people directory with its search_people tool rather than an inline document operator.

​

AI Assistant Actions

Darwinbox actions are grouped by module: Self-service actions resolve the authenticated Omni user’s email to their Darwinbox employee record (company_email_id match), and identity parameters are rejected. Manager actions first verify that the caller has direct reports; approval and rejection actions can target only those direct reports. The source must not be read-only for write actions, and writes require confirmation in interactive chat.

​

Actions Not Currently Exposed

The following registered actions remain disabled. They are not included in the connector manifest and are rejected at dispatch:

​

Removing the Integration

1. Navigate to Settings → Integrations
2. Click Settings against the Darwinbox source
3. Click Delete Permanently
4. Revoke or rotate the Darwinbox API credentials if needed

​

Troubleshooting

​

Security Considerations

• Read-only mode: The connector is read-only by default. While enabled, no write operation (e.g. apply/revoke leave) can change data in Darwinbox. Disable read-only only after configuring participant and action authorizations.
• Participants: By default every authenticated Omni user can invoke actions. An allowlist (opt-in) restricts actions to specific participant emails.
• Identity cannot be spoofed: Self-service identity is derived from the authenticated Omni user’s email, matched against the Darwinbox employee directory, and identity parameters are rejected. Manager actions accept a target employee only after verifying that the employee directly reports to the caller.
• Field allowlisting: A fixed approved field set (name, employee ID, company email, department, designation, office location, manager, employee type, cost center, work country, grade, band, confirmation status, employment dates, phone, and top department) is the maximum the connector ever writes. Compensation, personal, financial, and other sensitive fields are excluded.
• Credential security: Darwinbox credentials are encrypted at rest. Use a dedicated integration account with access only to the required API endpoints.
• Write confirmation: All write operations require explicit user confirmation in the AI assistant.
• Kill switch: Administrators can disable the Darwinbox source to remove its actions from the assistant.
• Token rotation: Rotate API keys, passwords, and client secrets according to your Darwinbox security policy.

​

What’s Next