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.

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.

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.

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

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.

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:

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

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.

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.

Example: first initial + last name

Goal: build samaccountname as first initial + last name in lowercase, so Mary Jones becomes 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.

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:

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

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

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

Full name with an optional middle name:

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

Employee ID padded to 8 digits:

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

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.

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

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.

Common patterns

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