Skip to main content

Provisioning Rules

In plain English

Provisioning Rules decide how a brand-new account's username, email, UPN, and display name are generated — as a formula you define per source (Workday, a DataSheet, …), not hardcoded logic.

Admin console: /admin/provisioning-rules (permissions PROVISIONING_RULE:READ / PROVISIONING_RULE:MANAGE).

This is SailPoint transform/rule parity for account-generation: instead of a fixed firstname.lastname convention baked into the product, an admin states the format as data, per identity source.

Canonical fields​

A rule targets one of four canonical fields — independent of which directory technology receives the account:

Canonical fieldAD native attributeLDAP native attribute
usernamesAMAccountName (hard-capped at 20 chars, AD's limit)uid
emailmailmail
userPrincipalNameuserPrincipalName(not applicable)
displayNamedisplayNamedisplayName

The writer applies this binding — a rule never targets a native attribute directly, so the same rule set works whether the identity provisions to Active Directory or generic LDAP.

Expression language​

A rule's expression is +-joined terms — a "quoted literal" or a $token, optionally piped through functions:

$firstName:clean:lower + "." + $lastName:clean:lower     → "john.smith"
$sAMAccountName + "@" + $mailDomain                       → "john.smith@example.com"

Functions (applied left to right): lower, upper, trim, initial (first character), clean (letters and digits only), first3. An unknown function name passes the value through unchanged rather than eating data.

If any referenced token resolves blank or missing, the whole expression is voided to null for that rule — never a half-formed .smith or @example.com — and generation falls back to the next rule in the resolution chain (below).

note

This is deliberately a smaller language than the computed outbound attribute expressions used for directory-write mapping — no case(...) lookup, no optional(...) group. It exists to state a username/email format as data, not to become a general expression language on a path that creates accounts.

Tokens available​

  • Identity-schema tokens: firstName, lastName, displayName, preferredName, middleName, username, company, department, jobTitle, employeeId, city, stateProvince, postalCode, country, costCenter, location, primaryEmail.
  • Context tokens: mailDomain, and any field an earlier rule already produced — a username rule can run first, then email = $username + "@" + $mailDomain references its output.
  • Discovered tokens: the editor also samples real accounts for that source and offers their metadata keys, so a source-specific field earns a place in the picker without a code change.

Rules are keyed by source​

Rules are scoped to a source key — the identity's originating system (workday, datasheet, an AD/SCIM connector, …), normalized from its identitySource (WORKDAY:<uuid> → workday). Resolution order for a given identity:

  1. That source's own stored rule set.
  2. The shared default rule set (source key *) — for organizations that don't need per-source variation.
  3. The built-in fallback — a single username rule ($firstName:clean:lower + "." + $lastName:clean:lower, unique); email/userPrincipalName fall back to the identity's own email address in the writer so a real address is never clobbered.

Load defaults in the editor offers the full recommended template — username plus composed email/userPrincipalName ($username + "@" + $mailDomain) and displayName ($firstName + " " + $lastName).

Uniqueness​

Mark a rule Unique (unique = true, as the built-in username rule is) to have generation append an incrementing numeric suffix (john.smith1, john.smith2, …) until a non-colliding candidate is found, trimming the base value to respect any length cap so the suffix always fits. The broker emits a candidate value; the writer/agent performs the final uniqueness check against the live directory at write time (AD's 20-character sAMAccountName cap is enforced there regardless of any rule-level maxLength).

Example​

A username rule of $firstName:clean:lower + "." + $lastName:clean:lower plus an email rule of $username + "@" + $mailDomain turns Jane O'Brien (mailDomain example.com) into username jane.obrien and email jane.obrien@example.com — clean strips the apostrophe, lower normalizes case, and the email rule reuses the username rule's own output.

  • Directory Integrations — the related (larger) expression language used for outbound attribute mapping once the account already exists.
  • HR Sources — the source systems a rule set is keyed against.