---
title: "Role-Based Access & Advanced Rule Capabilities"
slug: "role-based-access-advanced-rule-capabilities"
updated: 2026-05-20T14:27:19Z
published: 2026-05-20T14:27:19Z
canonical: "docs.axiad.com/role-based-access-advanced-rule-capabilities"
---

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

# Role-Based Access & Advanced Rule Capabilities

## What roles allow

**Important — who roles are for:** Role Management is designed for **operators**. A role grants operators the privileges to perform actions on end users and, when scoped, defines which subset of the user population each operator is allowed to manage. Roles are **not** a mechanism for assigning entitlements to end users — end users do not need a role to use the services your environment provides. End-user privileges are configured separately and can be fine-tuned independently.

Each operator role can be configured to control:

- **How** and **when** the role is granted to an operator — either statically or based on the operator's attributes.
- The **priority order** in which role assignment rules are evaluated when multiple could apply.
- The **set of users** the operator holding this role is allowed to manage — its administrative scope.

Rather than assigning operator roles one by one, rule expressions let the system evaluate role membership automatically against directory attributes. A role can be granted dynamically when an operator matches a condition, and its scope — the population of end users the operator can act on — can be expressed using runtime placeholders that resolve to each candidate user's own attributes. This enables delegated administration over a precisely defined slice of your directory (for example: "Help-Desk operators in France can manage users in France").

**What's new:** three new capabilities — *Priority*, *Role Mapping Rule*, and *Scope Rule* — bring rule-driven assignment and scoped administrative reach to every operator role.

**How this document is meant to be used:** Axiad configures operator roles in your environment on your behalf. Use this overview to understand the capabilities available and to prepare the role definitions, priorities, and rule expressions you would like Axiad to set up.

## Basic role information

Every role is described by the three attributes below. You'll want to decide a value for each before requesting role setup.

### 1. Role Name

| **Maximum length** | 40 characters |
| --- | --- |
| **Allowed characters** | Alphanumeric, hyphens, underscores, and spaces. Pattern: `[a-zA-Z0-9-_ ]+` |
| **Purpose** | The display name shown for this role throughout the application. |
| **Examples** | `Engineering Manager`, `IT-Admin`, `Support_Agent` |

### 2. Unique ID

| **Maximum length** | 45 characters |
| --- | --- |
| **Uniqueness** | Must be unique across all roles in your environment. |
| **Purpose** | Stable identifier used to reference the role in integrations and APIs. |
| **Examples** | `ROLE_ENG_MGR`, `ROLE_IT_ADMIN` |

**Fixed for the lifetime of the role:** the Unique ID cannot be modified once the role is created. Pick a value that fits your long-term naming convention before requesting role setup.

### 3. Role Description

| **Maximum length** | 450 characters |
| --- | --- |
| **Purpose** | A detailed description of the role's purpose and permissions — useful as audit and operational reference. |
| **Example** | *"This role is assigned to engineering managers who oversee development teams and have access to project management tools and team resources."* |

## Advanced rule capabilities

The capabilities below move operator roles beyond static assignment. They let you define **when** an operator should automatically receive a role, and **which users** that operator is then allowed to manage — all driven by directory attributes.

### 4. Priority New

| **Format** | Non-negative integer (0, 1, 2, …), up to 10 digits. |
| --- | --- |
| **Purpose** | Defines the evaluation order for role mapping rules. **Lower number = higher priority.** |
| **Behavior** | When multiple role mapping rules could apply to a user, the rule with the lowest priority number is evaluated first. |

**Tip:** Leave gaps in your priority numbering (10, 20, 30…) so new roles can be inserted later without renumbering existing ones.

### 5. Role Mapping Rule New

| **Maximum length** | 1,000 characters |
| --- | --- |
| **Validation** | Rule expression syntax is validated server-side; invalid expressions are rejected. |
| **Purpose** | An expression that determines whether a user should automatically be assigned this role, based on their attributes. |
| **Supports** | Logical operators `AND`, `OR`; comparison operators `equals` / `=`, `contains`; variable references using the reserved `{user.…}` subject (see [Rule expression syntax](/docs/role-based-access-advanced-rule-capabilities#rule-syntax)), including the special `.group` attribute and nested attributes via dot notation. |
| **Evaluation** | Re-evaluated whenever the referenced user attributes change. A failing expression is logged but does not block user operations. |

**Examples**

```plaintext
{user.givenDisplayName} = "testUser"

({user.givenDisplayName} Equals "testUser" OR {user.country} equals "USA")

{user.givenDisplayName} contains "testUser"

// Complex expression combining AND with OR — parentheses make the grouping explicit:
(({user.givenDisplayName} Equals "testUser") OR ({user.country} equals "India"))
  AND
(({user.country} equals "USA") OR ("Argentina" equals {user.country}))
```

### 6. Scope Rule New

| **Maximum length** | 1,000 characters |
| --- | --- |
| **Validation** | Rule expression syntax is validated server-side; invalid expressions are rejected. |
| **Purpose** | An expression that defines which **users** an operator holding this role is allowed to manage. The scope rule selects the population of users that fall under this operator's administrative reach. |
| **Supports** | Variable references using the reserved `{users.…}` subject for the candidate user and `{operator.…}` for the logged-in operator (see [Rule expression syntax](/docs/role-based-access-advanced-rule-capabilities#rule-syntax)), including the special `.group` attribute. Combine with static string literals and logical operators. |
| **Behavior** | Variables are resolved at runtime against actual user attribute values. The scope is enforced whenever the operator performs an action on a user — only users matching the expression are visible and manageable. |

**Examples**

```plaintext
{users.givenDisplayName} = "testUser" OR {users.givenDisplayName} = "testing"

{users.group} = "Default Group_LOCAL"

"testUser@gmail.com" = {users.user_email}
  AND
{users.givenDisplayName} equals "testUser"
```

## Rule expression syntax

Both Role Mapping Rules and Scope Rules share the same expression grammar. Knowing the small set of conventions below is enough to write any rule you will ever need.

### Variables — the curly-bracket convention

Every reference to a user attribute is written between curly brackets, in the form `{subject.attribute}`. The brackets tell the rule engine that the value is to be resolved at runtime against directory data, not treated as a literal string. Anything outside curly brackets is a literal (typically a string in double quotes, or a logical operator).

### Reserved keywords

Three keywords are reserved by the rule engine and must be used exactly as shown:

| `user` | Used in **Role Mapping Rules**. Refers to the user being evaluated for role assignment — i.e., the user whose attributes the engine is testing to decide whether this role should be granted to them. *Example:* `{user.country} = "USA"` |
| --- | --- |
| `users` | Used in **Scope Rules**. Refers to any candidate user the operator might act on — the population that the rule filters to determine which users fall within the operator's administrative scope. *Example:* `{users.group} = "Default Group_LOCAL"` |
| `operator` | Refers to the logged-in user (the operator) executing an action. Use this keyword in scope rules to express dynamic scopes that follow the operator's own attributes — for example, allowing an operator to manage only users in the same country, group, or department as themselves. *Example:* `{users.country} = {operator.country}` |

### Special attribute: `.group`

Alongside the standard directory attributes (such as `givenDisplayName`, `country`, `user_email`), the engine exposes a special `.group` attribute on both `user` and `users`. It resolves automatically to the group(s) the user is a member of, based on the membership information Conductor already maintains — you do not have to import, sync, or hardcode group lists into the rule.

```plaintext
// Grant this role to any user who belongs to the Engineering group:
{user.group} = "Engineering"

// Operator can manage users who share their group membership:
{users.group} = {operator.group}

// Scope to a specific local group already known to Conductor:
{users.group} = "Default Group_LOCAL"
```

### Operators, literals, and grouping

- **Logical operators:** `AND`, `OR`
- **Comparison operators:** `equals` (also written `=`), `contains`
- **Literals:** string values are written in double quotes (e.g. `"USA"`). Values inside `{ }` are **not** literals — they are variable references.
- **Nested attributes:** dot notation is supported (e.g. `{user.profile.country}`).
- **Grouping with parentheses:** when an expression mixes `AND` and `OR`, you **must** use parentheses to make the evaluation order explicit. Ambiguous expressions are rejected.

**Best practice:** always group `OR` conditions inside parentheses before combining them with `AND`. The validator will reject ambiguous expressions, and explicit grouping makes intent clear to anyone reviewing the rule later.

## Lifecycle & system behavior

A few system-level guarantees are worth knowing as you design your roles:

### Atomic role removal with cascading cleanup

When a role is removed from your environment, the system performs the following in a single atomic transaction:

1. The role itself is removed.
2. Every **Role Mapping Rule** associated with the role is deleted.
3. Every **Scope Rule** associated with the role is deleted.
4. The priorities of all remaining roles are automatically re-adjusted to close the gap left by the removed role.

This guarantees there are no orphaned rules and that your priority sequence stays contiguous — no manual cleanup or renumbering is required.

### Rule evaluation safety

Role Mapping Rules are re-evaluated whenever the user attributes they reference change. If an expression fails to evaluate for any reason, the failure is logged but does not block user operations — meaning a faulty rule cannot lock users out of the system.

### Immutable identifiers

Once a role exists, its **Role Name** and **Unique ID** cannot be modified. Other attributes — priority, description, and the rule expressions — can be updated at any time.

## Preparing rules for Axiad

Because Axiad configures operator roles in your environment on your behalf, the most efficient way to onboard or change them is to provide a complete specification per role. For each operator role you'd like created or updated, prepare the following:

1. **Role Name** — the human-readable display name (max 40 characters, alphanumeric / hyphen / underscore / space).
2. **Unique ID** — the stable machine identifier (max 45 characters, must be unique). Remember this cannot be changed later.
3. **Role Description** — a clear explanation of what the role is for (max 450 characters).
4. **Priority** — a non-negative integer if this role should participate in rule-driven assignment. Lower number = higher priority. Consider leaving gaps between values to allow future inserts.
5. **Role Mapping Rule** — the expression that automatically grants this role when a user matches. Max 1,000 characters. Define the rule that determines membership for this role.
6. **Scope Rule** *(optional, for operator roles)* — the expression defining which users an operator holding this role is allowed to manage. Max 1,000 characters.

**Practical tip:** when writing rule expressions, always use parentheses to make logical grouping explicit, double-quote string literals, and reference user attributes using the placeholder syntax shown in the examples above. Sanity-check your expressions against a few representative users before sending them to Axiad — it will make the configuration cycle faster.

**Change management:** updates to rule expressions take effect once Axiad applies them in your environment and the system re-evaluates affected users. Plan rule changes that broaden or narrow operator scope with appropriate communication to your administrators.