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 via Roslyn (C# scripting) 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:

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 last exported snapshot stored in IM_ExportedAttributeSnapshots.

// Delta computation example
//
// Last exported snapshot (stored in IM_ExportedAttributeSnapshots):
//   { "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 via the IM_ExportQueue table. 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

Retry Behavior

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

Best Practices