Employee sync
Employee Sync keeps your employee list in Leena AI aligned with your source system — an HRMS, a directory, or any other employee database. An accurate directory underpins access control (terminated people shouldn't stay active), the attributes used across audiences, personalization and workflows, and every downstream experience that relies on knowing who someone is.
Data arrives one of two ways: a spreadsheet you upload, or a scheduled pull from your HRIS. A bot uses one of them, not both.
A scheduled pull reads from an employee source: a code based emp sync that Forge builds for you in a conversation, or a utility app you build in Workflows Studio.

Where to find it
Open the Admin Console, then go to Bot users → Emp sync.
The page has three tabs:
- Employee data — the resulting directory. Every bot lands here, configured or not.
- Sync history — the audit log of every run, manual and automated.
- Sync setup — how employee data gets in.
AccessUser Sync is available to roles holding the employee sync capability — in most deployments, System Admin.
Choosing a sync method
| Method | How it works | Best for |
|---|---|---|
| Manual | You define field mappings, then upload an Excel or CSV file against them | One-time loads, small organizations, or ad-hoc corrections |
| Automated | A scheduled sync that reads employee data from your HRIS through an employee source | Ongoing, hands-off synchronization with your source system |
A bot uses one method. Switching from one to the other replaces the existing setup — the wizard asks you to confirm, and the replacement can't be undone.
Choosing an employee source
An automated sync reads from an employee source. There are two kinds. Both run on the same schedules, sync types and safeguards, and a bot can use both, one per sync.
| Employee source | How it's built | Good fit when |
|---|---|---|
| Code based emp sync | You tell Forge which HR system holds your employees. It writes the source, tests it on your live data, previews what would sync and sets up the schedule, in one conversation | You're setting up a new sync. Forge has ready-made setups for Workday, SAP SuccessFactors, Microsoft Entra ID and Google Sheets, and writes one from your answers for other systems |
| Workflow utility app | You build it in Workflows Studio, with an Action node to call your HRIS and a Mapper node to shape the records | You already have a utility app, or your team maintains its integrations in Workflows |
Code based sources need ForgeBuild with Forge appears in the setup wizard only when Forge is available to you. Without it, the wizard links to Workflows instead, and code based sources are listed only if the bot already syncs from one.
Field reference
Every employee record is stored under fixed keys. Other parts of Leena AI read specific keys: channels, Workflows, notifications, AI Colleagues, audiences and analytics. A value only works if it arrives under the right key, in the right format.
- Manual sync: the key is the Leena AI field name you map a column to.
- Automated sync: the key is the property name your employee source returns: the Mapper node's output for a utility app, or the record keys of a code based source, which Forge maps for you. Keys are case-sensitive, so use them exactly as written below.
Mandatory fields
| Leena AI field | Key | Type | What it's used for |
|---|---|---|---|
| Employee Id | employeeId | String | The record's identity. Also stored in lowercase as userId. Every managerId and hrId must point to a value of this field |
| Work Email | email | String | Matching people on Teams, Slack, Google Chat and web sign-in, and the Allowed domains check. Stored in lowercase |
| Display Name | displayName | String | The name shown across the Web App and channels. If firstName or lastName is missing, it's taken from the first and last word of the display name |
| Is user active | isActive | Boolean | true keeps the employee active. false marks them Terminated |
Keep each person's employeeId stable. Records are matched on it, so a changed value creates a new employee. On an authoritative sync, the old record is also terminated.
The two methods readisActivedifferently
- Manual:
true,yesor1(any case) mean active.false,noor0mean terminated.- Automated: only the boolean
trueor the string"true"mean active. Any other value marks the employee Terminated, including"Yes","Active",1or an empty string. Convert your HRIS status to a real boolean in the Mapper node. A code based source always sends a real boolean: Forge asks you which of your HR system's values mean active, and encodes exactly that.In an automated sync, a record without
isActiveis created as active. An existing record without it keeps its current status.
An automated record needs at least an employeeId or an email. Records with neither are skipped. Send all four mandatory keys anyway: the preview flags any that are missing, and downstream products expect them.
Standard fields
These fields are in the Leena AI field dropdown on every bot.
| Leena AI field | Key | Type |
|---|---|---|
| First name | firstName | String |
| Middle Name | middleName | String |
| Last Name | lastName | String |
| Job title | designation | String |
| Department | department | String |
| Location | location | String |
| Band | band | String |
| Employment | employmentStatus | String |
| Gender | gender | String |
| Currency | currency | String |
| Mobile Phone | phone | String (see Phone) |
| Start Date | doj | Date |
| Date Of Birth | dob | Date |
| Street 1 | address1 | String |
| Street 2 | address2 | String |
| City | city | String |
| State | state | String |
| Country | country | String |
Keys that need a specific format
These keys drive relationships and features elsewhere in Leena AI. Send them under these exact names, in these formats.
Manager and HR
| Key | What to send | Used by |
|---|---|---|
managerId | The manager's Employee ID, exactly as it appears in their employeeId: same case, no extra characters. Not their email or name | Workflow approvals and manager/skip-manager lookups, the Employee Directory org chart, AI Colleagues' employee directory, and Automatically identify managers |
hrId | The HR partner's Employee ID, without any prefix | Workflow HR lookups and Automatically identify HRs |
- If none of a run's
managerIdvalues match an Employee ID, the manager step is skipped for that run. Existing manager flags are left as they were. - The leading-
Ptolerance (P12345matching12345) only applies when identifying HRs. Workflows look up the HR by the exact value, so sendhrIdwithout the prefix. - Don't send
isManagerorisHr. They're calculated only by automated syncs, through the two additional settings. They can't be mapped, created as custom fields, or edited by hand. managerIdandhrIdare owned by the sync and can't be changed through Edit user data.
Phone
Send phone as a mobile number in international E.164 format: +, then the country code and number, for example +14155550123.
- It's used to match employees on WhatsApp, SMS and other phone-based channels.
- A number without
+is guessed, trying India first, then the US, then Australia. It can end up in the wrong country. - Landline and invalid numbers are dropped without an error, so the employee ends up with no phone on record.
Dates
The date keys are doj, dob and marriageDate.
- Manual: set Field type to Date and pick the format your file uses. The default is
dd/MM/yyyy. - Automated: send ISO 8601 dates,
YYYY-MM-DD.
They're used to find upcoming birthdays, work anniversaries and wedding anniversaries. The day and month are derived automatically.
Timezone, language and photo
| Key | Format | Notes |
|---|---|---|
timezone | IANA name, such as America/New_York or Europe/London | Used to deliver scheduled notifications in each recipient's local time. If it isn't sent, new employee records default to Asia/Calcutta (IST), so send it for any workforce outside India |
language | ISO 639-1 code, such as en, es, de or hi | Sets the language the assistant uses with that employee. English names like Spanish are also recognised, but codes are safer. If the value is empty, the employee's current language is kept |
imageUrl | A URL the employee's browser can load | Shown as the employee's avatar in the Web App |
Attributes for audiences and rules
Values such as location, department, designation, country, band and gender are matched as plain text. Keep them consistent across records. For example, Bangalore and Bengaluru are different values to an audience, an authorization rule, or AI Colleagues' directory search. By default, directory search matches by meaning on location, department and designation.
The following keys are copied to every bot user's profile: email, employeeId, firstName, lastName, fullName, displayName, title, designation, department, division, businessUnit, organization, band, location, country, language, gender, phone, timezone, imageUrl and isManager. From there, flows read them as user.* parameters and audiences filter on them.
Other keys, including custom fields, are stored on the employee record and shown in Employee data. Before each user sync, Employee Sync adds them to the bot's user sync fields too, so they reach bot user profiles: every field in your manual field mapping, and every key an automated sync has returned. A few keys are never sent, such as isActive and userId. If a field can't be added, for example because a bot variable or custom attribute already uses its name, Sync setup marks it Not sent to bot users and gives the reason. Rename the field, or the clashing variable, to fix it.
Phone Call verificationIf your bot verifies callers by asking for digits from their profile, the fields it checks must reach bot user profiles: either from the list above or added as user sync fields. Each value also needs at least as many digits as the check asks for. Employees missing either can't be verified on a call.
Adding these keys in a manual sync
managerId, hrId, timezone, language, imageUrl and marriageDate aren't in the dropdown. Add them with Create custom field. The key is the camelCase form of the name you type:
| Type this name | Key created |
|---|---|
| Manager ID | managerId |
| HR ID | hrId |
| Timezone | timezone |
| Language | language |
| Image URL | imageUrl |
| Marriage Date | marriageDate |
Watch the spacing. For example, Time Zone creates timeZone, which no product reads.
Example record (automated sync)
{
"employeeId": "10482",
"email": "[email protected]",
"displayName": "Priya Sharma",
"isActive": true,
"firstName": "Priya",
"lastName": "Sharma",
"designation": "Senior Analyst",
"department": "Finance",
"location": "London",
"country": "United Kingdom",
"managerId": "10017",
"hrId": "10233",
"phone": "+447700900123",
"doj": "2022-04-11",
"dob": "1994-08-23",
"timezone": "Europe/London",
"language": "en"
}Sync setup
With nothing configured, the tab offers Add sync. Once a sync is saved, the tab becomes a read-only summary of it, with Edit in the header to reopen the wizard.

The wizard has three steps, and the third one applies to both methods:
- Select sync method — Manual or Automated
- Add field mapping (manual) or Sync users (automated)
- Authorize users
Each step saves as you continue; the final step's button reads Save and sync.
Switching method replaces your employeesSwitching to manual means the employees added by your automated sync are replaced by the file you upload. Switching to automated means employees you added manually are replaced by the utility app's data on the next sync.
Neither can be undone.
Step 2 (manual) — Map fields
Match the columns in your file to Leena AI fields. Each row is one mapping.

| Configuration | Description |
|---|---|
| Leena AI field name | Select an existing Leena field, or create a new custom field from the same dropdown |
| Client field name | The column name in your file. Cannot be empty, and cannot contain . or $ |
| Field type | String, Date, Boolean, Phone number, or Array. Numeric-only input is enforced through a String validation |
| Mandatory | Whether a value must exist for every employee |
| Validation rules | Opens a side sheet of rules for that field's type |
A few things worth knowing:
- The four mandatory fields are seeded for you and can't be removed: Employee Id, Work Email, Display Name and Is user active. Their type is locked. See Field reference for keys and formats.
- Each Leena field can be mapped only once — two columns pointing at the same field is rejected on save.
- Available validations depend on the field type. Boolean fields have none, Date fields require a format, and Phone number fields support uniqueness and regex only.
- String fields support uniqueness, number-only, allowed email domains, custom values, and a regex pattern with an inline Test regex option.
- Array fields hold several values in one cell. The cell is read as comma-separated text, split, trimmed, and each element validated individually. Use it for attributes like multiple roles or locations.
Mapping fields does not load any employees — uploading a file is a separate action from the Employee data tab.
Step 2 (automated) — Sync users
Automated sync pulls employee data from your source system on a schedule, through an employee source. Each sync card picks a source, then sets the schedule and sync type.

Before you start
You need a published employee source. The Employee source dropdown groups them by kind:
- CODE BASED EMP SYNC — sources built with Forge. Only published ones are listed.
- WORKFLOW UTILITY APPS — published Employee Sync utility apps from Workflows Studio.
A bot with no code based source sees a plain list of utility apps, without the headings.
No source yet? Click Build with Forge in the Setup sync header. Forge opens full screen on a new conversation and starts setting up an employee sync for the bot. See Code based emp sync with Forge. Where Forge isn't available, the header links to Workflows instead.
To build a utility app instead, go to Workflows Studio → App Listing → Create App and set the Utility Type to Employee Sync Utility. Configure pagination to match how your HRIS API returns data (page-number or skip-token), add an Action node to call the API, use the Mapper node to transform source fields into the keys listed in Field reference, set the Response Template on the Trigger node with the data array and pagination fields, then publish. It will then appear in the dropdown. Full instructions are in User Sync Utility Apps.
Additional settings
Two settings apply to every sync on the bot. Both are off by default.
| Setting | What it does |
|---|---|
| Automatically identify managers | Employees with active direct reports are marked as managers after every sync. Needs managerId in your synced fields |
| Automatically identify HRs | Employees assigned as the HR of at least one active employee are marked as HR after every sync. Needs hrId in your synced fields |
Both are recalculated across the whole directory after each run, not just for the records that run returned. Someone stops being marked a manager or HR once no active employee points to them.
HR IDs must be Employee IDsEach employee's
hrIdis matched against Employee IDs, so return the HR's Employee ID, not their email or another identifier. Identifying HRs tolerates a leadingP(P12345matches12345), but Workflows' HR lookup doesn't, so send it without the prefix.
Configuring a sync
| Setting | What it does |
|---|---|
| Employee source | The code based source or utility app this sync runs. Each sync must use a different source. Editing a sync can switch it to another source |
| Frequency | Daily, Weekly (pick a day), or Custom (every N days, weeks, or months) |
| Time | The sync hour, in UTC, with a local time hint. Only the hour is used |
| Sync type | Add new employees adds new people and updates existing ones. Update existing employees only updates, matched by Employee ID — no one new is created, and unmatched records are skipped and counted |
| Terminate employees missing from this sync | Available with Add new employees only. Makes this sync authoritative: anyone absent from its response is marked Terminated |
Save and preview fetches sample records from the source and shows them before anything is committed. It reads up to three pages. A code based source runs as you for the preview. Review the rows, then confirm with Add sync — or go back and change the configuration.

You can configure more than one sync. Add another sync validates and collapses the open one first; an incomplete card is blocked until you finish it or use Remove sync to discard it. Saved syncs collapse into a summary showing the source name, Active/Inactive, schedule and sync type, with Edit, Deactivate and Delete in the menu.
Only one authoritative sync per botJust one sync can have "Terminate employees missing from this sync" enabled. If another sync already owns it, the checkbox is unavailable and the panel explains why.
Step 3 — Authorize users
Who can actually reach the bot. This step applies whichever sync method you chose.

| Setting | What it does |
|---|---|
| Allowed domains | Only employees with emails on these domains can access the bot. Type a domain and press enter |
| Employee authorization rules | Only employees matching these rules are authorized |
Rules are built as groups. Conditions inside a group are joined with And; groups are joined with Or. Each condition is a Key (an employee attribute, such as role), a Condition, and a Value.
Available conditions: is equal to, is not equal to, equals (ignore case), is any of, is none of, contains, does not contain, starts with, ends with. The "is any of" and "is none of" conditions accept several values.
Leave the rules empty to authorize on domains alone. A half-finished rule is rejected on save — a rule missing a key, condition or value would match nobody.
Two related policies are shown here read-only, because they're owned by General settings: Only authorize synced users and Block login from personal email domains.
Saving authorization settings does not run a sync. The rules take effect at login and on the next employee sync. To apply them to people who are already in the directory, run a sync.
The saved setup
Once saved, Sync setup shows the configuration read-only: the sync method, your field mappings or employee sources, the additional settings for automated syncs (each shown as On or Off), and the authorization settings.
For automated syncs, each source card's menu carries Sync now — the only way to run a sync on demand. It confirms first, because a sync can be triggered only once an hour per sync; if you're inside that window, the page tells you how many minutes remain.
A code based source shows View details beside its name. See View or change a code based source.
Code based emp sync with Forge
A code based emp sync is an employee source that Forge writes for you: a small piece of code that reads one page of employees from your HR system per call and returns them in Leena AI's employee format. Forge builds it, tests it on your live data, previews what would sync and applies the sync, all in one conversation. You approve every step that changes anything.
Start a conversation
Any of these opens Forge on employee sync:
- Build with Forge in the Setup sync header of the wizard's automated step. It starts a new conversation with "Set up an employee sync for this bot."
- Forge in the dashboard header, from any Emp sync tab. Ask in your own words, for example "Set up an employee sync from Workday" or "Why did last night's sync fail?"
- Edit with Forge in a source's View details side sheet, to change that source.

What Forge walks you through
- Your current setup. Forge reads the bot's sync configuration and the employee sources that already exist. If one already exists for your system, it asks whether to reuse it as is, reuse it with a different connection, or build a new one. It doesn't run or change an existing source to check it first.
- The HR system. Pick the system that holds your employees. For Workday, SAP SuccessFactors, Microsoft Entra ID and Google Sheets, Forge has a tested setup, and gives you its checklist of what to configure on the HR system's side. For any other system, it asks for the API endpoint, the auth method and how the API pages its results, then writes the source from your answers.
- The connection. Pick an existing connection for that system, or create a new one: the connection form opens beside the chat. Forge never asks for a credential in chat.
- Your answers. Forge asks, with options where it can: whether the feed is the employee list itself or extra data for people who already exist, which status values mean active, whether to sync the whole directory or only part of it, how often and at what time, and whether to terminate employees missing from the sync.
- A plan. A plan card shows the system, the connection, the source's name and its settings. Nothing is built until you approve it.
- A check and a preview. Forge saves the source unpublished, checks page one against the employee format, then previews up to three pages as a table with each record's field errors. It tells you how many people a sync would leave out and why, and flags a page that looks cut off by a page-size limit.
- The fields. Forge lists every field the source returned and asks which to bring across. Salary, bank details, national IDs, date of birth and home address come across only if you name them. Fields that aren't Leena AI fields yet become custom fields.
- Terminations. Before you turn on Terminate employees missing from this sync, Forge previews how many active employees it would terminate, and who, when the preview covered the whole feed. It suggests the safer order: save the sync with it off, check the first full run in Sync history, then turn it on.
- Publish and apply. Forge publishes the source, then applies the sync. You approve it on a card that lists its effects. If the bot syncs from manual uploads today, Forge explains that switching replaces the manual setup and waits for an explicit yes.
- First run. Forge offers to run the first sync now and reports the result from Sync history. It can then set up another sync, for another source or another group of people.

Schedule times are whole UTC hoursGive Forge the time in your own timezone and it converts it. Syncs start on the hour in UTC, so in a half-hour timezone such as IST only :30 local times exist, for example 07:30 or 08:30 IST. If you pick a time that isn't on a UTC hour, Forge offers the two nearest ones.
Systems with a ready-made setup
| System | What it reads | Set up first |
|---|---|---|
| Workday | Every worker, active and inactive, from the WQL data source allWorkers. Active status decides isActive | A Workday REST connection that signs in as an integration (an API client for integrations with a refresh token, or client credentials), and an integration user that can read allWorkers |
| SAP SuccessFactors | The OData User entity, employees by default, active and inactive, with snapshot paging | A connection using OAuth 2.0 SAML bearer (an API client), and an API user that can read User in both active and inactive statuses |
| Microsoft Entra ID | Member users from Microsoft Graph, optionally only some employee types. accountEnabled decides isActive | An app registration with the Microsoft Graph application permission User.Read.All and admin consent, using client credentials |
| Google Sheets | One tab of a spreadsheet. Who is active comes from a status column, a leaving-date column, or everyone in the sheet | A Google service account key as the connection, the Google Sheets API turned on in that project, and the sheet shared with the service account's client_email as Viewer |
For other systems, Forge asks how the API works and writes the source to the same rules.
How a code based sync runs
- It runs as the person who chose the source. Scheduled runs and Sync now run the source as the person who saved the sync with that source. Editing only the schedule or sync type doesn't change this; switching the sync to a different source does.
- Use a shared connection. A connection that holds its own credentials, such as a service account or client credentials, works unattended. A per-user connection works only while that person's sign-in is valid, and stops when it lapses or they leave.
- One page per call. Each call reads one page and returns a cursor for the next, and the sync follows the pages in order. A call can run for at most 120 seconds, and a page's output must stay under 1 MB. Forge warns you when a page gets close, so you can lower the page size.
- Only published sources run. Changing a source's code unpublishes it until it passes its check and you publish it again. A sync that reaches an unpublished or deleted source fails without reading or terminating anyone.
- Leavers stay in the feed. A source returns people who left with
isActive: falserather than leaving them out, so a terminating sync can tell "left the company" from "missing". A record without an employee ID can't be sent: it's left out and counted, and while any are left out, Terminate employees missing from this sync terminates no one.
View or change a code based source
In the wizard and on the saved setup, a code based source has View details beside it. The side sheet lets you rename the source and edit its description. Its code is shown read-only.
To change what the source fetches, click Edit with Forge. Forge edits the code, checks and previews it again, then asks you to publish it. Code changes always go through Forge so they're re-tested before a sync runs them.
Ask Forge about your sync
The same conversation handles day-to-day questions:
- Why a sync failed. Forge reads the run and reports the cause, the evidence and the next step.
- Who a run terminated. Sync history gives counts; Forge can name the people.
- Run, pause or replace a sync. Forge can run a sync now, deactivate one, take a source offline while keeping its sync, or replace one sync with another. You approve each change on a card first.
- Show a source's code, or open the Emp sync screen on the tab you need.
Employee data
The directory, and the tab every bot lands on.

Two views answer two different questions:
| View | Who it shows |
|---|---|
| Synced | Employees the sync wrote |
| Authorized | People who can actually reach the bot, and on which channels |
Within either, switch between Active and Terminated, each with a live count. Search and sort across any column to spot-check records, and use Manage columns to show or hide fields — your choices are remembered. Clicking a row opens the full employee record, including fields hidden from the table. In the Synced view, a row's menu also offers Edit user data.
Download employee data exports every employee, Active and Terminated, as an XLSX regardless of the filters currently applied.
Adding employees
Add employees offers two routes: Upload a file for a spreadsheet, or Add manually for one person.

The button is unavailable in two cases: the bot syncs automatically — in which case the sync owns the employee list — or mandatory fields aren't mapped yet. Configure those in Sync setup first.
Upload a file
Before uploading, consider downloading the template — it contains column headers matching your current client field names exactly.

Your file must be:
.xls,.xlsx, or.csv- No larger than 10 MB
- A single, non-empty file
The file is checked the moment you select it, so you don't press Save to find out whether it's valid. A verified file shows a green check; a rejected one shows what went wrong. If columns couldn't be matched to your field mappings, fix the file and upload it again.
Save then takes you to that upload's page in Sync history.
Uploading does not syncAt this point the data is staged and validated. No employee record has been created or updated yet — you complete the sync from Sync history, below.
Add manually

Enter one employee's details. On a manual bot the form follows your configured field mapping; on other bots it follows the existing record. Fields the sync owns — manager, HR ID and similar — aren't editable here. The manager and HR flags can't be changed here either; they're set by the sync.
Sync history
The audit log for every run, uploaded and automated alike. For uploads it's also where you complete the sync.

| Column | What it shows |
|---|---|
| Triggered at | When the run occurred |
| Source | Excel or API. API runs show the employee source's name |
| Status | See the reference below. Hover a failed run for the reason |
| Total employees | Records processed in the run |
| Added / Updated / Terminated | How many employees were added, updated, and terminated |
| Download data | Downloads the uploaded spreadsheet. Excel runs only |
Completing an upload
- Open the run with status Uploaded or Uploaded with errors to see its record-level detail.
- Review the records. Each row shows its parsed values, with warning icons and tooltips on any field that failed validation. Use the All / No Errors / Errors toggle to isolate problems.
- Click Save. For a run with errors, a confirmation appears first — proceeding syncs the valid records and excludes the rest. To include them, fix the source file and re-upload.
- The run moves to Sync in progress, then Successful or Synced with errors. Added, Updated and Terminated counts populate on the run, and the results appear under Employee data.
Until you click Save, the run sits in Uploaded status and nothing reaches the directory. If you re-upload a corrected file, start the sync from the newest run.
Status reference
| Status | Meaning |
|---|---|
| In progress | The uploaded file is still being processed and validated |
| Uploaded | Validated and staged — not yet synced. Open the run and click Save |
| Uploaded with errors | Staged, but some records failed validation. Save syncs the valid ones only |
| Sync in progress | The sync is running |
| Successful | Completed, all records applied |
| Synced with errors | Completed, but some records failed — open the run to inspect them |
Automated runs use only the last three, since they have no upload or staging step.
Filters and search
Narrow the list by Sync status (multi-select), Sync type (Excel or API), and Utility app (multi-select, shown when the type is API). Search, sorting and filters are held in the page URL, so a filtered view can be shared as a link.
Run details and downloads
Clicking an Excel run opens its record-level detail, where each row shows its values with warning icons and tooltips for validation errors, and the All / No Errors / Errors toggle isolates problems. For runs still in Uploaded status, this is where you click Save. The uploaded file can be downloaded from either the row or the detail page, with an extra column listing each row's errors.
Fully successful runs don't open a detail page — the sync is already complete, so use the row's Download option instead. API runs have no detail page or download; use the stats columns and the failure reason tooltip.
RetentionRow-level data behind a completed run is purged 7 days after upload, so download an error report while you still need it. Runs that were never synced are preserved.
Troubleshooting
What to check regularly
Watch Sync history to confirm runs happened at the expected UTC hour, that the status is Successful, and that the record counts line up with your HRMS. Also check that no uploads are sitting in Uploaded or Uploaded with errors — those are staged files waiting for someone to open them and click Save.
Automated sync failures
Missing identifier — records with neither an Employee ID nor an email are skipped, because they can't be matched or created. Email-only records are fine.
Pagination error — the run stopped because pagination didn't advance: either the page number or skip token repeated, or three consecutive pages returned no new employees. This is a safeguard against runaway loops. Check the utility app's pagination configuration, or ask Forge to check a code based source's paging.
Terminations on an authoritative sync — there's no percentage cap. A sync set to terminate absent employees mirrors its source, so if the source returns a partial list, everyone missing from it is terminated. Termination is skipped, and the run is marked Synced with errors, when the run returned no records, any record lacked an identifier, or no employee was marked present. Confirm your utility app returns the full population before enabling this option.
Employees terminated unexpectedly — check the isActive value your Mapper node returns. In an automated sync, anything other than the boolean true or the string "true" marks the employee Terminated. See Mandatory fields.
Sync now is refused — a sync can only be triggered once an hour. The message tells you how long is left.
Manager flags, approvals or the org chart are missing — check that managerId holds the manager's Employee ID exactly as it appears in their record, not their email or name. If no managerId in the directory matches an Employee ID, the manager step is skipped for the run and existing flags are left as they were.
HR flags aren't being set — check that Automatically identify HRs is on and that your utility app returns an HR ID for employees. If fewer than half of the HR IDs in the directory match an Employee ID — usually because the source sends the HR's email or a separate internal ID — the HR step is skipped for that run and existing HR flags are left as they were. The same happens when no active employee has an HR ID. The sync itself still completes.
Code based sync failures
Hover a failed run's status in Sync history for the reason, or ask Forge why the last sync failed.
The employee source is not published — the source was never published, or its code was changed and not published again. The run read no one and terminated no one. Publish it with Forge, then run the sync again.
The employee source no longer exists — it was deleted. Choose another source for the sync, or build one with Forge. In the wizard, a deleted source shows (deleted) after its name and the sync can't be saved until you change it. An unpublished one shows (not published).
The connection needs a sign-in — the source's connection signs in per user, and a scheduled sync can't sign anyone in. Sign in with the link on the connection, or bind a client-credentials connection to the source. Then run the sync again.
The source's code failed while fetching employees — for example, the HR system rejected a request or returned something the source didn't expect. Ask Forge why the sync failed to see the error, fix the source with Forge, then run the sync again.
The tool is no longer an employee source — choose another source for the sync, or build one with Forge.
Employee Sync could not reach the code based source — the connection between Leena AI services isn't set up on your instance. Contact Leena AI support.
Manual sync issues
Add employees is unavailable — either the bot syncs automatically, in which case the sync manages the employee list, or mandatory fields are still unmapped. Finish the mappings in Sync setup.
File rejected — check the format, the size limit of 10 MB, and that the file isn't empty or corrupt.
Columns couldn't be matched — the file's headers don't line up with your client field names. Download the template, or correct the headers, and upload again.
File uploaded but Employee data hasn't changed — the run is almost certainly still in Uploaded status. Uploading only stages data; open the run in Sync history and click Save.
Validation errors — open the run to see them per record, fix the source file or the field validations, and re-upload. Saving an "Uploaded with errors" run excludes the failing records.
Duplicate value errors on a unique field — uniqueness is checked within the uploaded file, so two rows sharing a value are both flagged even when neither conflicts with existing data.
Authorization issues
An employee is in Employee data but can't use the bot — compare the Synced and Authorized views. Synced means the sync wrote the record; Authorized means they pass the domain and rule checks. Check the rules in Sync setup, and remember they only apply to existing employees after the next sync.
Notifications arrive at the wrong local time — the employee has no timezone, or an invalid one, so their record defaulted to IST. Send an IANA timezone name. See Timezone, language and photo.
Updated 5 days ago
