---
title: "Attribute Mappings"
slug: "attribute-mappings"
description: "Some applications support more user attributes than standard things like First Name, Last Name, and email. For these applications, Clarity allows you to configure custom mappings to determine which Clarity attributes should map to which attributes on the downstream application."
updated: 2026-10-07T16:09:22Z
published: 2026-10-07T16:09:22Z
canonical: "help.claritysecurity.com/attribute-mappings"
---

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

# Attribute Mappings

Attribute Mappings control which values Clarity sends to a downstream application, such as Active Directory or Entra ID, when it creates or updates a user account. Each mapping is a rule that builds one application attribute, like `givenName`, `samaccountname` or `extensionAttribute2`, from your Identity Attributes.

Rules can do more than copy a single attribute. You can combine attributes, add fixed text, take part of a value, change case, make a value unique, and apply different rules to different groups of people, like contractors versus employees.

To open the page, go to the application and click the **Application Attributes** tab. The tab only shows for applications that support custom attribute mappings.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled(1).png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

The page has two parts:

- **Rule Sets** (left): groups of rules, and who each group applies to.
- **Attribute Mappings** (right): the rules in the selected rule set, one card per application attribute. Each card shows the friendly name, the application attribute name, and how many operations it uses. A **Unique** badge means the value is checked for duplicates.

The buttons above the list are **Import**, **Export**, **Test Mappings** and **Add Attribute**. Each is covered below.

---

## Rule Sets

A rule set is a group of attribute rules that applies to certain people. Every application has a **Default** rule set. It has no conditions and applies to everyone who doesn't match another rule set.

Add more rule sets when a group of people needs different values. For example, contractors might get a different email domain or a different `description`.

### Create a rule set

1. In the Rule Sets panel, click **+ Add Rule Set**. Only application owners and admins can add rule sets.
2. Fill in the form:
  - **Rule Set Name**: a descriptive name, like "Contractors".
  - **Conditions**: who the rule set applies to. All conditions must match.
  - **Inherits From**: optionally, a parent rule set to copy rules from (usually Default).
  - **Priority**: which rule set wins when more than one matches. Higher numbers are checked first. Default is 0.
3. Save the rule set.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 2.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

### Conditions

Each condition checks one value about the person:

- **Identity Type**, for example Employee or Contractor
- **Identity Attribute**, for example Department or Employment Type
- **Service User Attribute**, a value on the person's account in this application

Operators are **is**, **is not**, **contains**, **starts with** and **ends with**. Every condition must match for the rule set to apply.

### Priority

When a person matches more than one rule set, the one with the highest priority number wins.

| Rule Set | Condition | Priority |
| --- | --- | --- |
| Contractors | Identity Type is Contractor | 100 |
| Engineering | Department is Engineering | 50 |
| Default | (none) | 0 |

A contractor in Engineering matches both Contractors and Engineering. Contractors wins because 100 is higher than 50. Keep Default at 0 and give more specific rule sets higher numbers.

### Inheritance

A rule set that inherits from a parent gets all of the parent's attribute rules automatically. You only add the rules that need to be different. A rule you add in the child replaces the parent's rule for that attribute. Everything else keeps following the parent, so later changes to the parent carry over too.

Example: a Contractors rule set inherits from Default and only overrides `mail` and `description`. Contractors still get Default's `samaccountname`, `displayName` and `department` rules.

To undo an override in a child rule set, open the card and click **Revert to Inherited**.

---

## Attribute rules

Each card in the list is one attribute rule. Click a card to expand it, or click **Add Attribute** to create a new one. Changes on a card aren't applied until you save that card; the card shows **Unsaved changes** until you do.

### Display Name and Attribute Name

| Field | What it is | Example |
| --- | --- | --- |
| **Display Name** | A friendly name shown on this page | Employee Type |
| **Attribute Name** | The exact field name in the application | `employeeType` |

The Attribute Name must match the application's field name exactly, or the value won't be written. For Active Directory, that includes extension attributes like `extensionAttribute1`.

For applications that need a nested structure, use dot notation. In Entra ID, for example, custom extension attributes live under `onPremisesExtensionAttributes`, so you'd enter `onPremisesExtensionAttributes.extensionAttribute1`. Clarity converts dot notation to the nested structure when it sends the user.

![image.png](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image%28418%29.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

### Inherit From Rule (optional)

Copies the setup of an existing rule from **another application**. Use it when several applications need the same value built the same way, like a display name used in both Active Directory and Entra ID. This is different from rule set inheritance, which works within one application.

### Use existing Username Rules

Turn this on to build the value from your global Username Rules (Settings → Username/Identifiers) instead of operations on this card. It's typically used for `samaccountname`. Values built this way are always checked for uniqueness.

When it's on, you can also turn on **Strip Special Characters**. This removes characters such as apostrophes and accents from the generated username before the uniqueness check, so O'Brien becomes obrien.

### Force Uniqueness

Makes sure the value isn't already used by someone else. If it is, Clarity changes it using the incrementer you choose:

| Incrementer | What happens on a collision | Example |
| --- | --- | --- |
| **Numeric (1, 2, 3...)** | Adds a number | jsmith, jsmith_1, jsmith_2 |
| **Alphabetic (a, b, c...)** | Adds a letter | jsmith, jsmitha, jsmithb |
| **Widen Substring** | Takes one more character from a part of the value you choose, then rebuilds the whole value. Falls back to numbers only when that attribute runs out. | mjones, majones, marjones |
| **Sliding Window** | Builds an 8-character username from last name + first name, using more of the first name on each collision. Pads short names to 8. | smithr, smithro, smithrob |
| **Sliding Window Minimal** | Same as Sliding Window, but doesn't pad short names. Never longer than 8 characters. | doej stays doej |

For **Widen Substring**, mark exactly one Substring operation with **Widen on collision**. Give it a source attribute and a starting length (see Guided mode below).

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled(2).png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

**Do not check external application** controls where Clarity looks for duplicates:

- **Off** (default): checks usernames, emails and user identifiers on the application. Use this for usernames, email addresses and UPNs.
- **On**: only checks this application's existing accounts in Clarity. Use this for values that aren't usernames or emails, like an employee number.

### Include in Update Commands

Decides whether the rule is also sent when an existing account is updated.

- **On**: the value is sent when the account is created and every time it's updated. Use this for values that should stay in sync, like title, department and display name.
- **Off**: the value is only sent when the account is created. Use this for values that should never change afterward, like `samaccountname` and `userPrincipalName`, or values people may edit by hand later, like a phone number.

When this is on, Clarity sends the value on every update even if it's blank, so a blank value clears the field in the application.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 3.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

### Configuration mode

Each rule is built one of two ways:

- **Guided** (recommended): add operations step by step.
- **Advanced**: write a formula. This is useful for logic with many conditions.

---

## Guided mode

Operations build the value **from top to bottom**. Click **+ Add Operation** to add one.

| Operation | What it does | Example |
| --- | --- | --- |
| **Input** | Adds the value of an identity or service user attribute | First Name |
| **Text** | Adds fixed text | `@company.com` |
| **Concatenate** | Adds several attributes at once | First Name + Last Name |
| **Substring** | Takes part of a value (start and length) | First character of First Name |
| **Regex** | Finds and replaces text with a pattern | Remove digits |
| **Transform** | Changes the whole result so far: Lowercase, Uppercase, Capitalize, Trim or Remove Special Characters | Lowercase |

### Example: first initial + last name

Goal: build `samaccountname` as first initial + last name in lowercase, so Mary Jones becomes `mjones`.

| Step | Operation | Setting | Result so far |
| --- | --- | --- | --- |
| 1 | Substring | Source: First Name, Start 0, Length 1 | M |
| 2 | Input | Last Name | MJones |
| 3 | Transform | Lowercase | mjones |

To grow the first name on a collision (mjones, majones, marjones), turn on Force Uniqueness, choose **Widen Substring**, and check **Widen on collision** on step 1.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 7.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

### Example: fixed value

For a value that's the same for everyone, like an office location, use a single **Text** operation, for example "Sacramento". To send a different value for some people, add an override (see Override Rules below) or a separate rule set.

---

## Advanced mode

Advanced mode lets you write a formula with MySQL-style functions. It runs in a secure, isolated environment.

### Referencing values

- `{identity.attribute}`: an identity attribute, for example `{identity.department}`
- `{attribute}`: shorthand for an identity attribute, for example `{first_name}`
- `{serviceuser.attribute}`: an attribute on the person's account in this application

### Functions

**Text:** `CONCAT`, `CONCAT_WS`, `LOWER`, `UPPER`, `TRIM`, `LEFT`, `RIGHT`, `SUBSTRING`, `REPLACE`, `LPAD`, `RPAD`, `LENGTH`

**Conditions:** `IF`, `IFNULL`, `COALESCE`, `CASE ... WHEN ... THEN ... ELSE ... END`

### Examples

Email address:

```plaintext
CONCAT(LOWER({first_name}), '.', LOWER({last_name}), '@company.com')
```

Map one value to another (for example, a description based on employment type):

```plaintext
CASE {employment_type}
  WHEN 'Civil Service Employee' THEN 'Civil Service'
  ELSE 'Vendor Resource'
END
```

Full name with an optional middle name:

```plaintext
CONCAT_WS(' ', {first_name}, IFNULL({middle_name}, ''), {last_name})
```

Employee ID padded to 8 digits:

```plaintext
LPAD({employee_id}, 8, '0')
```

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 5(2).png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

---

## Override Rules

Override Rules handle exceptions inside a single attribute rule. When an override's conditions match, its operations **replace** the card's default operations. Otherwise the default operations run.

Use an override when only one attribute differs for a group of people. Use a separate rule set when several attributes differ.

Override conditions use the same types as rule sets, plus a **matches (regex)** operator.

1. Expand the card and open **Override Rules**.
2. Click **+ Add Override**.
3. Add the condition, for example Identity Attribute *Employment Type* equals *Agency Staff*.
4. Under **Then use instead**, add the operations for that case.
5. Save the card.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 6.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

---

## Test Mappings

Test your rules against a real person before relying on them.

1. Click **Test Mappings**.
2. Search for and select an identity.
3. Review the results:
  - **Applied Rule Set**: which rule set this person matched
  - **Calculated Outputs**: the value each rule produces, with a Unique badge where uniqueness applies
  - **Source Attributes Used**: the identity values the rules read

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 7(1).png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

Things to check:

- Values look right for a few different people, including one from each rule set
- Names with hyphens, apostrophes, spaces or accents come out the way you expect
- A person whose username is already taken gets the expected unique value
- Overrides trigger for the right people
- Inherited rules show the expected values

---

## Import and Export

Reuse a working rule set in another application or environment instead of rebuilding it.

### Export a rule set

1. Select the rule set.
2. Click **Export**. A `.json` file with the rule set and all its rules downloads.

### Import a rule set

1. Select the rule set you want to replace.
2. Click **Import** and choose an exported `.json` file.
3. Review the rules loaded into the page. Nothing is saved yet.
4. Click **Save imported rules** to apply them, or **Discard** to cancel.

**Saving an import replaces all of the selected rule set's rules.** It doesn't merge with them. Export the current rule set first if you might want it back.

If the file refers to something that doesn't exist here, like a parent rule set or another application, the import is blocked and a list shows each missing item. Create the missing item or edit the file, then import again.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/Untitled 8.png?sv=2026-02-06&spr=https&st=2026-10-27T11%3A12%3A43Z&se=2026-10-27T12%3A12%3A43Z&sr=c&sp=r&sig=DkDQOLdZ0VTaw5u1939rtmmGjVx8Dyaa4oDYUFPhZSg%3D)

---

## Common patterns

| Attribute | Setup | Include in Update Commands |
| --- | --- | --- |
| `samaccountname` | Use existing Username Rules (or Substring + Input + Lowercase with Widen Substring) | Off |
| `userPrincipalName` / `mail` | Username + Text `@company.com`, Force Uniqueness on | Off |
| `displayName` | Input First Name + Text " " + Input Last Name | On |
| `title`, `department` | Input of the matching identity attribute | On |
| Office, address, company | Text | Off, or On to keep it enforced |

---

## Troubleshooting

### An attribute isn't being sent

- Check that the Attribute Name matches the application's field name exactly.
- Check that the person matches the rule set you expect (use Test Mappings).
- For updates to existing accounts, check that Include in Update Commands is on.

### The wrong rule set is being used

- Higher priority wins. Check the numbers on every rule set the person matches.
- All conditions must match. Check each one against the person's values.

### The value is wrong

- Operations run top to bottom. Check their order.
- Transform changes the whole result so far, not just the last step.
- Check whether an override is replacing the default operations for this person.

### A field was cleared in the application

- Rules with Include in Update Commands on send blank values too. Turn it off for fields that are filled in by hand after the account is created.

---

## Glossary

| Term | Meaning |
| --- | --- |
| Rule Set | A group of attribute rules, with optional conditions and a priority |
| Attribute Rule | The setup that builds one application attribute |
| Operation | One step in building a value in Guided mode |
| Override | A condition inside a rule that swaps in different operations |
| Inheritance | Reusing rules from a parent rule set, or from a rule in another application |
| Priority | Which rule set wins when several match; higher is checked first |
| Incrementer | How a value is changed to make it unique |

## Related

- [Username Rules](/username-rules.md)
- [Release Notes April 28, 2026](/release-notes-april-28-2026.md)
- [Role or Entitlement Change Validation Checklist](/mover-validation-checklist.md)