> ## Documentation Index
> Fetch the complete documentation index at: https://iru-kbee-63-enhance-rts-documentation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Directory Sync
> Keep your directory current by connecting an HRIS or directory solution for automatic sync, or import users from a file.
Keep your
[directory](/en/identity/directory/directory-overview) populated and up to date
from the system that's the source of truth for who's in your organization. There
are two ways to do it:
Link a **live source** (an **HRIS** such as **Workday** or **BambooHR**, or
another **directory solution**) and Iru pulls users from it and syncs on a
schedule, creating, updating, and removing users on its own. More providers are
on the way.
No direct connector for your system? Export your users to a **CSV** (from a
legacy HR system, a **Student Information System (SIS)**, or anything you can
produce a file from) and upload it. Re-upload an updated export whenever your
list changes to keep users current.
When you connect a live source, updates flow into Iru on their own, so when
someone is hired, changes roles, or leaves, your directory follows with no manual
work. The rest of this guide covers connecting a source system; for the manual
route, see [CSV import](/en/identity/directory/importing-users).
Today you can connect the HR systems **Workday** and **BambooHR**, with more
providers (including other directory solutions) on the way. Setup is the same
guided flow for each; only a couple of steps differ by provider.
Connecting a source system needs administrator access to your Iru tenant and
administrator credentials for that system. The connection only **reads** users
from the source; it never writes back to it.
## How it works at a glance
1. **Choose** your provider.
2. **Connect:** enter credentials so Iru can read your user data.
3. **Configure** (some providers only): tell Iru where your data lives.
4. **Map** the source's fields to Iru fields.
5. **Enable:** turn on syncing and choose how often it runs.
```mermaid theme={null}
flowchart LR
connect["Connect
+ credentials"] --> discover["Iru reads
available fields"]
discover --> map["Map fields
source → Iru"]
map --> enable["Enable"]
enable --> sync["Scheduled or
on-demand sync"]
sync -->|"create / update / remove"| dir["Directory"]
sync -->|"problems"| errors["Sync errors to review"]
```
Once a connection is enabled, Iru syncs on the **interval** you set, from every
**30 minutes** up to once per **week**, or **manual only** if you prefer to run
syncs yourself with **Sync now**.
## Ideas that apply to every connection
* **Your source system leads.** Once connected, it's the authority on user data;
Iru reflects what it sends.
* **Every user needs a stable ID.** You pick one field that uniquely and
permanently identifies each user, so Iru always updates the right record.
* **You decide how fields line up.** Iru doesn't guess. You map each source field
to the matching Iru field, and can transform values with **IQL** when they don't
line up one-to-one.
## Set it up
In **Directory → Sync**, select **Connect Source** and pick your provider:
**Workday** or **BambooHR**.
Give the connection a **display name** (and optional **description**), then enter the
credentials Iru needs for that provider. Iru submits them in the setup form;
there is no separate provider consent window.
* **Workday:** instance host, Workday tenant, Integration System User, and
password.
* **BambooHR:** company domain and API key.
See the [provider guides](#choose-your-provider) for the exact fields.
Use a dedicated admin / integration account where you can, so the connection
keeps working regardless of any one user's status.
Some providers need you to point Iru at the right data source. **Workday** asks
for the **report name** that exposes the worker fields you want; the Integration
System User from the previous step is what runs that report. **BambooHR** reads
its standard employee directory, so it skips this step. See the
[provider guides](#choose-your-provider) below.
Iru reads the fields your provider makes available and lays them out for you to
match. See [Map your data](#map-your-data) below.
Save your mappings to finish setup. A new connection starts **disabled**, so
nothing syncs until you've reviewed it, then **Enable** it to run the first
import. Set the **sync interval** on the connection's Configuration tab, or leave
it on **Manual only** and use **Sync now** when you want an update.
## Map your data
Mapping is where most of the setup happens: connecting your source's fields to the matching
fields in Iru.
### Set a unique identifier
Choose the field that uniquely identifies each user, often an **employee ID** or
similar stable identifier. Iru relies on one stable value per user to update the
*right* record on every sync, even when names or emails change.
Pick something that never changes for a user. **Once you save the connection,
the unique identifier can't be changed.** Changing it would break Iru's ability
to recognize the users it has already imported.
### Match fields to Iru
For each Iru attribute, pick the source field that should fill it. Four attributes
are **required** and always mapped:
* **Email**
* **First name**
* **Last name**
* **Username**
Any attribute you've marked required in your
[schema](/en/identity/directory/schema) is required here too. Everything
else is optional, but mapping it brings over the full picture of each user:
title, department, manager, location, and more.
### Transform values with IQL
Most fields are a simple pick-and-go. When the value you want needs to be *built*
from a field rather than copied as-is, write a short **IQL** expression instead. As
you type, Iru suggests the available fields and checks your expression, so you
catch a typo or a missing field *before* you save, not during a sync. See
[Attribute mapping](/en/identity/directory/attribute-mapping) and
[IQL expressions](/en/identity/getting-started/iql-expressions) for the full syntax.
Common examples (use your provider's own field names):
* **Build a username from an email** (everything before the `@`):
`email.split("@")[0]`
* **Combine two fields** into one value:
`firstName + " " + lastName`
* **Prefer one field, fall back to another** when the first is blank:
`optional.ofNonZeroValue(workEmail).orValue(homeEmail)`
If a field is sometimes blank, guard against it so the sync doesn't trip on empty
records. Wrap the value with `optional.ofNonZeroValue(...).orValue("")` before
transforming it. For example, only deriving a username when an email exists:
`optional.ofNonZeroValue(email).orValue("").split("@")[0]`
## Choose your provider
The flow is the same for each; these guides cover the steps that differ.
Read workers from a Workday report. Includes the report and integration-user
step.
Read from BambooHR's standard employee directory. No report to configure.
| Step | Workday | BambooHR |
| -------------------------------------------- | ------- | -------------------- |
| Connect with credentials | Yes | Yes |
| Configure a report | Yes | No (standard fields) |
| Map fields (unique ID, required fields, IQL) | Yes | Yes |
| Enable and sync on a schedule | Yes | Yes |
## What happens on each sync
Once enabled, Iru syncs on the interval you choose and reconciles your directory
with the source system:
| Change at the source | What Iru does |
| --------------------------- | ----------------------------------------- |
| A new user appears | Creates a matching user in your directory |
| A user's details change | Updates the user's profile attributes |
| A user is no longer present | Removes the user from your directory |
As profiles arrive and change, [Auto Groups](/en/identity/directory/auto-groups)
update their membership automatically, so access follows users without manual
work.
## Sync schedule and on-demand sync
On a connection's **Configuration** tab, set **Sync frequency** with the
**Interval** control. Choose how often Iru pulls the latest directory, or set it to
**Manual only** and sync on demand.
Available intervals:
* Manual only (no automatic sync)
* Every 30 minutes
* Every hour
* Every 2 hours
* Every 4 hours
* Every 8 hours
* Every 12 hours
* Every day
* Every 2 days
* Every week
On the **Sync** tab, use **Sync now** to start a run immediately, and **Refresh** to
reload the list of sync runs. Each run reads everyone from your directory source and
adds or updates them in Iru. Select a run to see what it did and anything it could
not sync. A failed run tries again at the next scheduled sync.
## Manage the connection over time
From a connection's detail page you can:
* **Re-authenticate:** submit fresh credentials when they expire or change,
without touching your mappings.
* **Edit your configuration or mappings:** adjust what's imported as your needs
evolve.
* **Set the sync interval** or run **Sync now**.
* **Force attribute sync** (Workday): re-read the latest available fields from
your report without waiting.
* **Review activity, effective users, and sync errors:** see what's flowing in
and spot anything that needs attention.
* **Enable or disable** the connection, or remove it.
On the **Directory → Sync** list, each connection shows whether it is
**Enabled** or **Disabled**, plus a connection-health value:
| Health | What it means |
| --------------------------- | --------------------------------------------------------------------------------------- |
| **Connected** | Iru can authenticate to the source with the credentials on file. |
| **Needs re-authentication** | Credentials are missing, expired, or rejected. Re-authenticate before sync can succeed. |
| **Not connected** | The connection is not ready to authenticate (for example, setup was left incomplete). |
On the connection's **Configuration** tab, **Connection details** shows the same
health for that provider. Use **Re-authenticate** to submit current credentials.
Your attribute mapping is not affected.
* **BambooHR:** re-enter the company domain and API key.
* **Workday:** re-enter the Integration user and password.
Sync problems show up in two stages. Knowing which stage failed tells you where
to look first.
* **Pull-stage errors** happen when Iru cannot read from the source: bad or
expired credentials, an unreachable instance, a missing report, or a rejected
API call. Fix the connection (often with **Re-authenticate** or by correcting
the report / domain settings), then run sync again.
* **Apply-stage (sync) errors** happen after Iru has the records but cannot
create or update a particular user in your directory. Iru records a **sync
error** you can review: when it occurred, the affected user, the action Iru
attempted, an error code, and a message. If many records fail with the same
error, the cause is usually a mapping: a required attribute left unmapped, or a
unique identifier that isn't actually unique. Fix the mapping, then let the
next sync run.
## Related
The Workday-specific setup, including the report step.
The BambooHR-specific setup.
The IQL you use to shape incoming values.
The attributes your source fields map into.