Provisioning Mappings and Lookups

Write-mappings, sync_mode, operators, provisioning lookups, and cross-system references.

Write mappings live on the system page's Writes tab, beside the write permissions and the processing settings, and are no longer part of onboarding. A target system goes live with writes off; Set up writes (or Change writes) walks through an access check, the operations, what the platform writes and a dry run, and saves it all at once. The Writes tab also shows the native create call for entitlements on Exchange and LDAP/Active Directory, checked against what the connector implements. See the onboarding walkthrough.

Anatomy of a write-mapping

Each ConnectorInstance.provisioning_field_mappings entry is a JSONB dictionary with these fields:

• target_field — the name of the field on the target API (e.g. userPrincipalName)
• job_type — account_create / account_modify / grant / * (all)
• operator — how the value is rendered (see below)
• sync_mode — enforce / set_once / ignore_drift / skip
• applies_to_account_types — empty = all types; a list = only for specific types
• applies_to_entitlement_types — the same, on the entitlement side: a list limits a grant or revoke mapping to specific entitlement types. A mapping that names entitlement types never matches an entitlement that has no type

Operators — ways to compute a value

1. passthrough — a direct copy: source_field: "identity.email" → the target receives the identity's email. The fastest path for 80% of mappings.

2. expression — a Jinja template: {"\"{{ identity.first_name }}.{{ identity.last_name }}@example.com\""}. Can filter or transform: {"| lower"}, {"| if_null('default')"}.

3. constant — a fixed value for every account: constant: "Member".

4. lookup — resolve a reference. A mapping that names a provisioning lookup (lookup_name) queries the target system itself, as described in the section below. A mapping that names a catalogue object (lookup_schema_id) instead finds a record in your object store and returns one of its fields.

5. account_attr — a cross-system reference: account_attr("ad-corp", "samaccountname") reads the AD account's samAccountName for the same identity. This drives the depends_on_systems dependency graph (AD must sync before Entra).

6. builtin — helpers: gen_username (3 styles + accent normalization), slug, gen_uuid.

sync_mode — what the platform does when the target diverges

• enforce — drift is written back. For attributes the platform treats as the source of truth (displayName, mail, job function).

• set_once — write on create, then the target wins. For immutable identifiers (userPrincipalName after rollout).

• ignore_drift — write on create and on modify, but do not write drift back during reconciliation. For attributes the target may legitimately change (last_signin_at, user-edited bio fields).

• skip — never write. For read-only mappings that serve display only.

Reconciliation and attribute propagation honour this setting. Drift on a set_once, ignore_drift or skip row is shown in the reconciliation breakdown but is never written back and creates no job, and a change made on the platform side is not re-written to the target for set_once or skip rows. Until 2026-10-07 only the create and modify payload respected sync_mode; drift correction and event-driven propagation wrote those rows as if they were enforce.

Provisioning lookups — cross-system reference resolution

Lookups let a mapping query the target API itself to resolve references. Example: a manager_id mapping on Entra:

• lookup.target_object_name — which object to query (users)
• lookup.filter_template — {"userPrincipalName eq '{{ value }}'"}
• lookup.returns_field — which field to return (id)
• lookup.cache_scope — per_job (default) / per_sync / per_tenant_24h
• lookup.cache_ttl_seconds — how long a cached value lives (300 by default)
• lookup.accept_stale_on_failure — on a target error: use the last cached value, or fail?

Lookups also work on connectors that run through a proxy agent: the lookup is dispatched to the agent like any other connector call. Earlier, a manager or group lookup on an agent-mode connector failed where the same connector in-process resolved it. An agent older than version 0.2.39 does not know the call and the lookup reports a failure. A write preview never reaches the target system, so a mapping that depends on a runtime lookup cannot show its value there.

ℹ Good to know

Lookups are the number-one cause of slow provisioning on large tenants. Be careful with per_job scope on large batches; a per_sync scope with a higher time-to-live (TTL) often works better; per_tenant_24h suits stable reference values such as countries or time zones.

Per-account-type targeting

applies_to_account_types filters per type. Use case: personal accounts get userPrincipalName from identity.email, while admin-privileged accounts get a-{"{first.last}"}@domain. Both mappings write to the same target_field but for different types.

Specificity: a mapping that names a type explicitly wins over a generic (empty applies_to_account_types) mapping on the same target_field.

Authority stays explicit at the write boundary

A mapping says how and whether RapidValue may write a field to this target. It does not silently establish precedence over every other source that can touch the same business fact. Combine the mapping with correlation, connector provenance and any upstream sync relationship, then verify the round trip.

See Source provenance and data authority for the shipped boundary and the universal matrix RapidValue does not currently claim.

---

Further reading:

• Account Rules
• Read/Write Parity
• Provisioning Jobs
• Reconciliation
• Source provenance and data authority