Keep your directory current by connecting an HRIS or directory solution for automatic sync, or import users from a file.
Keep your
directory 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:
Connect a source system
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.
Import a file (manual)
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.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 an
administrator account for that system. Depending on the provider, you either
enter integration credentials in Iru or authorize Iru in the provider’s own
consent window. The connection only reads users from the source; it never
writes back to it.
Connected sources are listed under Directory, on the Sync tab.
Connect: enter credentials in Iru (Workday) or authorize Iru in your provider
(BambooHR) so it can read your user data.
Configure (some providers only): tell Iru where your data lives.
Map the source’s fields to Iru fields.
Enable: turn on syncing and choose how often it runs.
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.
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.
In Directory → Sync, select Connect Source and pick your provider:
Workday or BambooHR.
Connect Source lists the source systems you can connect.
2
Connect to your provider
Give the connection a display name (and optional description), then give
Iru read access to your provider. How you do that depends on the provider:
Workday: enter the instance host, Workday tenant, Integration System User,
and password in Iru.
BambooHR: enter your company domain in Iru, then authorize in a
BambooHR window. Sign in to BambooHR and select Allow Access on the
Share access with Iru Identity screen. Your BambooHR credentials go to
BambooHR, not to Iru, and there is no API key to enter. Finish authorizing
within 15 minutes, or return to Iru and start the connection again.
Workday connection: Integration System User credentials entered in Iru.
Use a dedicated admin / integration account where you can, so the connection
keeps working regardless of any one user’s status.
3
Configure where your data lives (some providers)
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 below.
4
Map your data to Iru
Iru reads the fields your provider makes available and lays them out for you to
match. See Map your data below.
5
Finish and enable
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.
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.
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 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.
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 and
IQL expressions for the full syntax.
IQL reads a field name as code. A bare name works when it is a valid IQL
identifier: it starts with an ASCII letter or underscore, and every later
character is an ASCII letter, number, or underscore. first_name qualifies, so
you write it as it is. A dot joins valid names to reach a nested value, as in
name.givenName. A field whose own name contains a dot is one key, so you look
it up as __source["name.givenName"].Some source systems send names that fall outside that rule:
Names with spaces, hyphens, colons, or other symbols, such as Email - Work or
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
Names that are also IQL keywords, such as in, null, true, or if
Written bare, Email - Work reads as Email minus Work, and in reads as the
membership operator. To read the field, look it up by its exact name in __source, a
map of every field from the source:
__source["Email - Work"]
When you pick or type one of these fields in the mapping editor, Iru rewrites it
to __source["…"]. You can use that form for any field, and it works inside a
longer expression like any other value:
__source["Email - Work"].lowerAscii()
If a field name contains a double quote (") or a backslash (\), put a
backslash in front of each one inside the brackets. A field named Title "Legal"
is written __source["Title \"Legal\""]. The editor adds those backslashes when
it rewrites the field.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)
When you transform a text field that can be blank, guard the value so the expression still runs. Wrap it with optional.ofNonZeroValue(...).orValue("") before you transform it. For example, derive a username only when an email exists:
optional.ofNonZeroValue(email).orValue("").split("@")[0]A blank or null mapped value for a Boolean, Date, Integer, or Decimal custom attribute does not fail the sync. It clears the existing value. See Blank mapped values.
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
Choosing how often Iru syncs the connection.
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.
Each connection chooses whether a newly created user gets an email invitation.
On the connection’s Configuration tab, under Invites, set Invites for
new users:
Don’t send creates the user and leaves the invitation for you to send
later. See Inviting users.
Send emails an invite to each user this connection creates.
Send does not invite every record the sync touches:
Re-authenticate: submit fresh credentials, or approve access with your
provider again, when the connection expires or is rejected, 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.
Choose whether new users are invited: set Invites for new users to
Send or Don’t send.
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.
A connection's detail page: status, connection health, and Re-authenticate.
Connection status and re-authentication
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 is authorized to read from the source.
Needs re-authentication
The credentials or the provider authorization are missing, expired, revoked, 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 enter current credentials or
approve access with the provider again. Your attribute mapping is not affected.
BambooHR: sign in to BambooHR again in the window Iru opens, then select
Allow Access.
Workday: re-enter the Integration user and password.
Re-authenticating Workday with current Integration System User credentials.
Sync errors
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 expired or revoked provider authorization, an
unreachable instance, a missing report, or a rejected API call. Fix the
connection (often with Re-authenticate or by correcting the report or
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.
A failed sync on the Activity tab, with the full error detail. Here, a record was rejected because a required attribute was missing.
