> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attribute mapping

> Map fields from a connected directory source to Iru Identity profile attributes, and transform values using IQL expressions before they reach user profiles.

When Iru reads users from a connected source, it needs to know which incoming
field fills which Iru profile attribute, and sometimes how to reshape the value
along the way. You describe that with an **attribute mapping**: for each Iru
profile attribute, you write an **expression** that produces its value from the
source's fields.

> [!NOTE]
>
> **Where attribute mapping applies.** You write attribute mappings when you
> **connect a source system** (the [Workday](https://docs.iru.com/en/identity/directory/hris-workday.md)
> and [BambooHR](https://docs.iru.com/en/identity/directory/hris-bamboohr.md) connectors, which expose
> their own fields for you to map. It does **not** apply to
> [CSV import](https://docs.iru.com/en/identity/directory/importing-users.md): a CSV uses a fixed set of
> predefined columns, so there are no expressions to write.

> [!NOTE]
>
> Mapping expressions are written in **IQL**, the same expression language Iru
> uses for [application claim and attribute
> mapping](https://docs.iru.com/en/identity/getting-started/iql-expressions.md), Auto Group rules, and
> list filters. Here you'll map a connected **source system's** fields into
> your directory's [profile attributes](https://docs.iru.com/en/identity/directory/schema.md);
> see [IQL expressions](https://docs.iru.com/en/identity/getting-started/iql-expressions.md) for the full
> syntax.

## How a mapping works

Each row in a mapping pairs one **target** (an Iru profile attribute) with an
**expression** that draws from the **source** fields.

```mermaid actions={false} theme={null}
flowchart LR
  subgraph source["Source fields"]
    a["first_name"]
    b["email_work"]
  end
  expr["IQL expression"] --> target["Iru profile attribute"]
  a --> expr
  b --> expr
```

**1. Discover the source fields**

Iru reads the set of fields your source makes available. Those field names
become the **identifiers** you can reference in expressions. See
[Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync) for how
discovery fits into setup.

**2. Write an expression per attribute**

For each Iru attribute you want to fill, write an IQL expression. A valid
field name can stand alone. Any other name is looked up on `__source`.
Longer expressions combine or transform those values.

**3. Iru validates it**

Expressions are checked as you type and again when you save, so mistakes (an
unknown field, a type error) surface before they ever reach a sync.

**4. It runs on every sync**

When the sync runs, Iru evaluates each expression against the incoming row and
writes the result to the attribute.

> [!TIP]
>
> Choose one stable, unique source field for the identifier that ties a source
> record to an Iru user, so each sync resolves to exactly one user.

## Writing expressions

Expressions reference your source's fields and can transform them: upper/lower
casing, splitting, concatenation, picking a list item, and so on. The full
reference (objects, functions, operators, and examples) is on the
[IQL expressions](https://docs.iru.com/en/identity/getting-started/iql-expressions.md) page, since the same
language powers both directory mapping and application mapping.

A field name can stand alone when it is a valid IQL identifier. It starts with
an ASCII letter or an underscore, and the rest is ASCII letters, numbers, and
underscores. A name such as `prénom` falls outside that set, so it is read from
`__source`.

```
// Use a field as-is
work_email

// Combine fields into a display name
first_name + " " + last_name

// The local part of an email, before the @
work_email.split("@")[0]
```

When the name has a space, hyphen, colon, or other symbol, or when it is an IQL
keyword such as `in`, `null`, `true`, or `if`, look it up by its exact name on
`__source`. `__source` is a map of every field from the source. A dot between
valid names reaches a nested value, as in `name.givenName`. A field name that
includes a dot is still one key: `__source["name.givenName"]`. Written bare,
`Email - Work` is subtraction, and `in` is the membership operator.

```
__source["Email - Work"]
__source["Email - Work"].lowerAscii()
```

The mapping editor rewrites these fields to `__source["…"]` when you pick or
type them. A valid name stays bare. You can still write `__source["…"]` for a
valid name. If the name contains `"` or `\`, put a backslash before each one
inside the brackets, as in `__source["Title \"Legal\""]`. The editor adds that
escape when it rewrites the field. See
[Transform values with IQL](https://docs.iru.com/en/identity/directory/directory-sync#transform-values-with-iql)
for how this works on the Mapping tab.

## Blank mapped values

A blank or null mapped value clears the existing value of that custom attribute.
The sync continues.

For a **Boolean**, **Date**, **Integer**, or **Decimal** custom attribute, a
blank or null mapped value does not fail the sync. When you transform a text
field that can be blank, such as splitting an email, guard the value on the
[Mapping tab](https://docs.iru.com/en/identity/directory/directory-sync#transform-values-with-iql).

## Where to go next

> [card] [IQL expressions](https://docs.iru.com/en/identity/getting-started/iql-expressions.md)
>
> The full IQL reference: objects, functions, operators, and examples.

> [card] [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync)
>
> Connect an HR system and set up the mappings these expressions power.

> [card] [Profile attributes](https://docs.iru.com/en/identity/directory/schema.md)
>
> The targets your expressions write into.

> [card] [Auto Groups](https://docs.iru.com/en/identity/directory/auto-groups.md)
>
> Another place attributes drive automation in your directory.

### Related Articles

> [card] [Connect Workday](https://docs.iru.com/en/identity/directory/hris-workday.md)
>
> Connect Workday to Iru Identity so it reads workers from a custom report and keeps your Iru directory in sync as people are hired, transferred, or terminated.

> [card] [Connect BambooHR](https://docs.iru.com/en/identity/directory/hris-bamboohr.md)
>
> Connect BambooHR to Iru Identity so it reads the standard employee directory and keeps your Iru directory in sync as workers join, change, or leave.

> [card] [Importing users](https://docs.iru.com/en/identity/directory/importing-users.md)
>
> Bulk-create and update Iru Identity users from a CSV file, with required columns, validation rules, re-upload behavior, and when to use HR sync instead.

> [card] [Iru Query Language](https://docs.iru.com/en/identity/getting-started/iql-expressions.md)
>
> Iru Query Language (IQL) is Iru's expression language for shaping mapped values: fields, operators, string functions, conditionals, and null-safe helpers.


## Related topics

- [Application mapping](https://docs.iru.com/en/identity/applications/application-mapping.md)
- [Active Directory Strong Certificate Mapping Configuration](https://docs.iru.com/en/endpoint/integrations/certificate-services/active-directory-certificate-services/active-directory-certificate-services-ad-cs-strong-mapping-configuration.md)
- [SCIM Directory Integration with Microsoft Entra ID](https://docs.iru.com/en/endpoint/integrations/scim/scim-directory-integration-with-microsoft-entra-id.md)
