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, 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 actions resolve the authenticated Omni user to their Darwinbox employee record and operate in their name

​

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:

​

AI Assistant Actions

Darwinbox actions are grouped by module: All available actions are employee-scoped: the connector resolves the authenticated Omni user’s email to their Darwinbox employee record (company_email_id match). Identity parameters are rejected — you cannot act on behalf of another employee, and you cannot read another employee’s leave/attendance data.

​

Actions Coming Shortly (pending testing)

The following actions are fully implemented but kept switched off until they are validated: These are not exposed in the manifest and are rejected at dispatch until enabled.

​

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: Identity is derived from the authenticated Omni user’s email, matched against the Darwinbox employee directory. Identity parameters on actions are rejected.
• 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) 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 Darwinbox actions at the source level.
• Token rotation: Rotate API keys, passwords, and client secrets according to your Darwinbox security policy.

​

What’s Next