Projection Pipeline

The projection pipeline controls how mesh objects are provisioned and updated in target connectors. It determines which objects are exported, how attributes are mapped, and what the connector receives on create and update operations.

Pipeline Overview

When a mesh object is created or its attributes change, the projection pipeline determines whether it should be exported to one or more connectors. The pipeline flows through four stages:

Key Concepts

Attribute Lifecycle

Attributes pass through several stages before they become available in scripts, rules, and the Admin UI. Understanding this pipeline is essential for configuring connectors and writing transform or precondition scripts.

Projection Rules

A Projection Rule links a mesh object type to a target connector. Without a Projection Rule, no outbound export occurs for that object type to that connector.

{
  "connectorId": "conn_ad_corp",
  "meshObjectType": "User",
  "targetObjectType": "user",
  "createIfMissing": true,
  "deleteIfUnlinked": false,
  "preconditionScript": "return attrs["employeeStatus"] == "Active";"
}

Precondition Scripts

Precondition scripts are optional C# expressions that gate whether a rule is applied. They are evaluated as C# expressions and must return a bool value.

Return Value Behavior

Script Context

Precondition scripts receive the mesh object's attributes as a IReadOnlyDictionary<string, object?> named Attributes. Use dictionary methods to read attribute values.

Behavior by Rule Type

Examples

// Flow Rule precondition: only flow if mail is not empty
Attributes.ContainsKey("mail") &&
!string.IsNullOrEmpty(Attributes["mail"]?.ToString())

// Projection Rule precondition: only provision active employees
Attributes["employeeStatus"]?.ToString() == "Active"

// Combined check: active user with an email in the right domain
Attributes["objectType"]?.ToString() == "user" &&
Attributes["employeeStatus"]?.ToString() == "Active" &&
(Attributes["mail"]?.ToString()?.EndsWith("@corp.com") ?? false)

Projection Attribute Rules

Each Projection Attribute Rule maps a single mesh attribute to a target connector attribute. Together, these rules define the full outbound attribute set for a connector.

// Projection Attribute Rules for "Corporate AD" connector
[
  { "meshAttribute": "firstName",    "targetAttribute": "givenName"          },
  { "meshAttribute": "lastName",     "targetAttribute": "sn"                 },
  { "meshAttribute": "displayName",  "targetAttribute": "displayName"        },
  { "meshAttribute": "primaryEmail", "targetAttribute": "mail",
    "transformScript": "return value?.ToString()?.ToLowerInvariant();"        },
  { "meshAttribute": "upn",          "targetAttribute": "userPrincipalName"  },
  { "meshAttribute": "samAccount",   "targetAttribute": "sAMAccountName"     },
  { "meshAttribute": "department",   "targetAttribute": "department"         },
  { "meshAttribute": "title",        "targetAttribute": "title"              },
  { "meshAttribute": "manager",      "targetAttribute": "manager",
    "transformScript": "return "CN=" + value + ",OU=Users,DC=corp,DC=com";" }
]

Outbound Flow Rules

In addition to Projection Attribute Rules, you can define Outbound Flow Rules (Attribute Flow Rules with Direction = "Outbound"). These are applied after Projection Attribute Rules and add supplementary attributes to the projected output.

// Outbound Attribute Flow Rules (Direction = "Outbound")
[
  {
    "connectorId": "conn_ad_corp",
    "msAttribute": "description",
    "meshAttribute": "jobTitle",
    "preconditionScript": "return value != null && value.ToString().Length > 0;"
  },
  {
    "connectorId": "conn_ad_corp",
    "msAttribute": "physicalDeliveryOfficeName",
    "meshAttribute": "officeLocation"
  }
]

Object Creation: Required Attributes

When CreateIfMissing = true and no MS Object exists for a mesh object in the target connector, Identity Mesh will attempt to create the object. The connector will receive all projected attributes (no delta — everything is new).

Each connector type has its own set of mandatory attributes that must be present for object creation. Your projection rules must ensure these attributes are mapped from the mesh object.

// Active Directory: Required attributes for object creation
//
// Without these, AD will reject the create (Add) operation.
//
// Projection Attribute Rules MUST map all of these:
{
  "sAMAccountName": "jsmith",           // REQUIRED - unique logon name
  "userPrincipalName": "jsmith@corp.com", // REQUIRED - UPN for sign-in
  "cn": "John Smith",                   // REQUIRED - common name (RDN)
  "displayName": "John Smith",          // REQUIRED - display name
  "givenName": "John",                  // Recommended
  "sn": "Smith"                         // Recommended
}

// Entra ID: Required attributes for object creation
{
  "displayName": "John Smith",          // REQUIRED
  "userPrincipalName": "jsmith@corp.com", // REQUIRED
  "mailNickname": "jsmith",             // REQUIRED
  "accountEnabled": true,               // REQUIRED
  "passwordProfile": { ... }            // REQUIRED for new users
}

// Okta: Required attributes for object creation
{
  "login": "jsmith@corp.com",           // REQUIRED
  "email": "jsmith@corp.com",           // REQUIRED
  "firstName": "John",                  // REQUIRED
  "lastName": "Smith"                   // REQUIRED
}

Active Directory Required Attributes

Entra ID Required Attributes

Okta Required Attributes

Create vs. Update Decision

The Export Engine determines the action for each queue item based on whether an MS Object already exists in the target connector:

Delete Semantics (changed in this release)

Until this release the DeleteIfUnlinked flag on a Projection Rule was stored but never acted on. It now does real work: when a rule's precondition stops holding for a mesh object that already exists in the target connector, the engine exports a Delete for that object. An object whose precondition still holds is never touched by the flag, and an object that was never exported is skipped, not deleted.

Safety rails

Delta Computation

Identity Mesh only sends changed attributes to minimize connector load and avoid unnecessary writes. The delta is computed by comparing the new projected output against the snapshot saved after the object's last successful export.

// Delta computation example
//
// Last exported snapshot (saved after the previous successful export):
//   { "givenName": "John", "sn": "Smith", "department": "Engineering" }
//
// New projected output:
//   { "givenName": "John", "sn": "Smith", "department": "Product", "title": "PM" }
//
// Computed delta (only changed/new attributes sent to connector):
//   { "department": "Product", "title": "PM" }
//
// On CREATE (no snapshot exists), ALL projected attributes are sent.

Export Queue

Export operations are processed asynchronously from the export queue, which you can inspect on the Export Queue page in the Admin UI. Items are dequeued in batches, sorted by priority (descending) then creation time (ascending).

// Export Queue Item
{
  "exportQueueId": 42,
  "meshObjectId": "a1b2c3d4-...",
  "connectorId": null,
  "reason": "Create",
  "priority": 0,
  "status": "Pending",
  "retryCount": 0,
  "maxRetries": 3
}

Queue Reasons

Per-Export Timeout

IdentityMesh:Export:PerExportTimeoutSeconds (default 120; 0 disables) bounds connector initialisation plus the export call for a single queue item. A timed-out item fails with a message naming which phase ran out, and is retried like any other failure. Raise it for slow targets.

Retry Behavior

Failed exports are automatically retried with exponential backoff. The item is locked for 2^retryCount minutes before the next attempt.

Projection Templates

A projection template is a saved, connector-agnostic snapshot of a Projection Rule and its Projection Attribute Rules. It captures the shape of a working export — CreateIfMissing, DeleteIfUnlinked, the precondition, the target container, and the full attribute rule set — without binding it to any one connector. Apply a template to another connector or object type to reproduce that export configuration without rebuilding it by hand.

Templates are managed through the /api/projection-templates endpoints (list, save-as-template, apply, delete). Listing requires rules.read; save, apply, and delete require rules.write. There is no dedicated Admin UI page for projection templates — they are managed through the API.

Sync Rule Templates

A sync rule template is the inbound counterpart of a projection template: a saved, connector-agnostic snapshot of a connector's Join Rules and its inbound and outbound Attribute Flow Rules. A template carries an optional connector-type hint (for example Entra or Okta) so that matching templates sort first when you pick one, but the hint is advisory — any template can be applied to any connector.

Two templates ship with every install and upgrade. Entra ID users and groups creates, for User and for Group, join rules onPremisesSecurityIdentifier → objectSid and onPremisesSamAccountName → sAMAccountName followed by an anchor join rule id → anchorValue, plus inbound flows id → anchorValue and displayName → displayName for both types, member → member for Group, and an ungated onPremisesSyncEnabled → onPremisesSyncEnabled for both types. Every flow except the last carries the precondition Not(ms("onPremisesSyncEnabled")). Okta users and groups anchors both types on id only, with no preconditions, and its group display-name flow is name → displayName, because Okta groups carry their name in profile.name. Together these are exactly the rules the Entra ID and Okta connectors need before an imported group's member list resolves into mesh membership relationships.

The Entra template is written for hybrid tenants. A user or group that Entra Connect synchronises from Active Directory (onPremisesSyncEnabled is true) already exists in the mesh through the AD connector, and its cloud id can never match that object. The SID join links the synced object to its AD-mastered mesh object instead, and the SAM-name join is a fallback for estates that do not flow objectSid (the SID is forest-unique; a SAM name is unique only within a domain, so the exact key is tried first), and the precondition keeps the cloud side from anchoring, renaming, or re-membering anything Entra Connect owns: a synced object that does not join is not projected either, so no duplicate person is created. Cloud-only objects return no value for the flag, and Not of an absent value is true, so they anchor and flow exactly as before. Synced objects still import and still link to the person, so attributes that live only in the cloud can still be written back to them. If your AD connector flows the SID or the SAM account name into a mesh attribute with a different name, edit the applied join rule's mesh attribute to match.

Applying a template is additive and idempotent: rules that already exist on the connector (same attributes, object type, and direction, compared case-insensitively) are skipped rather than duplicated, and the result reports how many join rules and flow rules were created and how many were skipped. Applying the same template twice therefore creates nothing the second time.

In the Admin UI, open the Rules page and expand a connector. From Template on the Join Rules or Flow Rules tab opens the template picker and applies the chosen template to that connector; Save as Template above the tabs snapshots the connector's current join and flow rules as a new template, with the connector's type recorded as the hint.

The API exposes GET /api/sync-rule-templates to list them, POST /api/connectors/{id}/sync-rule-templates/{templateId}/apply to apply one, POST /api/connectors/{id}/sync-rule-templates/save-as-template to save the connector's rules as a new template, and DELETE /api/sync-rule-templates/{templateId} to remove one. Listing requires rules.read; apply, save, and delete require rules.write.

Best Practices