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.
📘

Access

User Sync is available to roles holding the employee sync capability — in most deployments, System Admin.

Choosing a sync method

MethodHow it worksBest for
ManualYou define field mappings, then upload an Excel or CSV file against themOne-time loads, small organizations, or ad-hoc corrections
AutomatedA scheduled sync that reads employee data from your HRIS through an employee sourceOngoing, 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 sourceHow it's builtGood fit when
Code based emp syncYou 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 conversationYou'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 appYou build it in Workflows Studio, with an Action node to call your HRIS and a Mapper node to shape the recordsYou already have a utility app, or your team maintains its integrations in Workflows
📘

Code based sources need Forge

Build 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 fieldKeyTypeWhat it's used for
Employee IdemployeeIdStringThe record's identity. Also stored in lowercase as userId. Every managerId and hrId must point to a value of this field
Work EmailemailStringMatching people on Teams, Slack, Google Chat and web sign-in, and the Allowed domains check. Stored in lowercase
Display NamedisplayNameStringThe 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 activeisActiveBooleantrue 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 read isActive differently

  • Manual: true, yes or 1 (any case) mean active. false, no or 0 mean terminated.
  • Automated: only the boolean true or the string "true" mean active. Any other value marks the employee Terminated, including "Yes", "Active", 1 or 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 isActive is 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 fieldKeyType
First namefirstNameString
Middle NamemiddleNameString
Last NamelastNameString
Job titledesignationString
DepartmentdepartmentString
LocationlocationString
BandbandString
EmploymentemploymentStatusString
GendergenderString
CurrencycurrencyString
Mobile PhonephoneString (see Phone)
Start DatedojDate
Date Of BirthdobDate
Street 1address1String
Street 2address2String
CitycityString
StatestateString
CountrycountryString

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

KeyWhat to sendUsed by
managerIdThe manager's Employee ID, exactly as it appears in their employeeId: same case, no extra characters. Not their email or nameWorkflow approvals and manager/skip-manager lookups, the Employee Directory org chart, AI Colleagues' employee directory, and Automatically identify managers
hrIdThe HR partner's Employee ID, without any prefixWorkflow HR lookups and Automatically identify HRs
  • If none of a run's managerId values match an Employee ID, the manager step is skipped for that run. Existing manager flags are left as they were.
  • The leading-P tolerance (P12345 matching 12345) only applies when identifying HRs. Workflows look up the HR by the exact value, so send hrId without the prefix.
  • Don't send isManager or isHr. 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.
  • managerId and hrId are 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

KeyFormatNotes
timezoneIANA name, such as America/New_York or Europe/LondonUsed 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
languageISO 639-1 code, such as en, es, de or hiSets 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
imageUrlA URL the employee's browser can loadShown 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 verification

If 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 nameKey created
Manager IDmanagerId
HR IDhrId
Timezonetimezone
Languagelanguage
Image URLimageUrl
Marriage DatemarriageDate

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:

  1. Select sync method — Manual or Automated
  2. Add field mapping (manual) or Sync users (automated)
  3. Authorize users

Each step saves as you continue; the final step's button reads Save and sync.

⚠️

Switching method replaces your employees

Switching 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.

ConfigurationDescription
Leena AI field nameSelect an existing Leena field, or create a new custom field from the same dropdown
Client field nameThe column name in your file. Cannot be empty, and cannot contain . or $
Field typeString, Date, Boolean, Phone number, or Array. Numeric-only input is enforced through a String validation
MandatoryWhether a value must exist for every employee
Validation rulesOpens 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.

SettingWhat it does
Automatically identify managersEmployees with active direct reports are marked as managers after every sync. Needs managerId in your synced fields
Automatically identify HRsEmployees 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 IDs

Each employee's hrId is matched against Employee IDs, so return the HR's Employee ID, not their email or another identifier. Identifying HRs tolerates a leading P (P12345 matches 12345), but Workflows' HR lookup doesn't, so send it without the prefix.

Configuring a sync

SettingWhat it does
Employee sourceThe 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
FrequencyDaily, Weekly (pick a day), or Custom (every N days, weeks, or months)
TimeThe sync hour, in UTC, with a local time hint. Only the hour is used
Sync typeAdd 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 syncAvailable 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 bot

Just 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.

SettingWhat it does
Allowed domainsOnly employees with emails on these domains can access the bot. Type a domain and press enter
Employee authorization rulesOnly 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. A plan. A plan card shows the system, the connection, the source's name and its settings. Nothing is built until you approve it.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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 hours

Give 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

SystemWhat it readsSet up first
WorkdayEvery worker, active and inactive, from the WQL data source allWorkers. Active status decides isActiveA 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 SuccessFactorsThe OData User entity, employees by default, active and inactive, with snapshot pagingA 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 IDMember users from Microsoft Graph, optionally only some employee types. accountEnabled decides isActiveAn app registration with the Microsoft Graph application permission User.Read.All and admin consent, using client credentials
Google SheetsOne tab of a spreadsheet. Who is active comes from a status column, a leaving-date column, or everyone in the sheetA 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: false rather 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:

ViewWho it shows
SyncedEmployees the sync wrote
AuthorizedPeople 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 sync

At 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.

ColumnWhat it shows
Triggered atWhen the run occurred
SourceExcel or API. API runs show the employee source's name
StatusSee the reference below. Hover a failed run for the reason
Total employeesRecords processed in the run
Added / Updated / TerminatedHow many employees were added, updated, and terminated
Download dataDownloads the uploaded spreadsheet. Excel runs only

Completing an upload

  1. Open the run with status Uploaded or Uploaded with errors to see its record-level detail.
  2. 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.
  3. 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.
  4. 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

StatusMeaning
In progressThe uploaded file is still being processed and validated
UploadedValidated and staged — not yet synced. Open the run and click Save
Uploaded with errorsStaged, but some records failed validation. Save syncs the valid ones only
Sync in progressThe sync is running
SuccessfulCompleted, all records applied
Synced with errorsCompleted, 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.

📘

Retention

Row-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.


Did this page help you?