Sync Rules

Sync rules are the core configuration mechanism in Connect Sync. They control which objects are in scope, how connector space objects join to metaverse objects, and how attributes flow between them. Every customization you make to Connect Sync’s behavior ultimately comes down to creating or modifying sync rules.

Rule Anatomy

Every sync rule has these components:

• Name - descriptive, usually following the pattern “In from AD - User [purpose]” or “Out to AAD - User [purpose].”
• Direction - Inbound (connector space to metaverse) or Outbound (metaverse to connector space).
• Connector - which connector (AD forest or Entra ID) this rule applies to.
• Object types - the connector space (CS) object type and metaverse (MV) object type the rule applies to.
• Link type - Join (link to existing MV object), Provision (create new MV object), or StickyJoin (provision, but do not delete MV object when the CS object goes out of scope).
• Precedence - a numeric value where lower numbers win. Determines which rule contributes an attribute value when multiple rules compete.
• Scoping filter - conditions that determine whether the rule applies to a given object.
• Join rules - conditions for matching a CS object to an existing MV object.
• Transformations - attribute flow definitions (direct copy, constant value, or expression).

Inbound vs. Outbound Rules

Inbound Rules

Inbound rules move data from a connector space into the metaverse. They run during the synchronization phase after import.

The inbound pipeline for each object:

1. Scope evaluation - the engine checks each inbound rule’s scoping filter against the staging object. Rules whose filters match are “in scope.”
2. Join/Projection - if the staging object is disjoined, the engine evaluates join rules to find an existing metaverse match. If no match is found and a rule with link type Provision is in scope, it creates (projects) a new metaverse object.
3. Attribute flow - all in-scope inbound rules contribute attribute values to the metaverse. When multiple rules want to set the same metaverse attribute, precedence determines the winner.

Outbound Rules

Outbound rules move data from the metaverse to a connector space. They run during outbound synchronization.

The outbound pipeline:

1. Scope evaluation - scoping filters on outbound rules are evaluated against metaverse attributes.
2. Provisioning - if an outbound rule is in scope and the target connector space has no corresponding object, the engine creates one. If the rule goes out of scope, the export object can be deprovisioned (deleted).
3. Attribute flow - in-scope outbound rules push metaverse attribute values into the connector space staging object, marking it for export.

Rule Evaluation Order

sequenceDiagram
    participant CS as Connector Space
    participant Scope as Scope Evaluator
    participant Join as Join Engine
    participant MV as Metaverse
    participant Out as Outbound Rules
    participant Export as Export Queue

    CS->>Scope: Staging object with pending import
    Scope->>Scope: Evaluate all inbound rules
    Scope->>Join: In-scope rules identified
    Join->>MV: Join to existing MV object or project new one
    MV->>MV: Apply inbound attribute flows by precedence
    MV->>Out: Evaluate outbound rules against MV object
    Out->>Export: Stage attribute flows in target connector space
    Export->>Export: Flag objects as pending export

Precedence is critical. The engine processes rules from highest precedence (lowest numeric value) to lowest precedence (highest numeric value). The first rule to contribute a non-NULL value to a metaverse attribute wins; lower-precedence rules for the same attribute are ignored unless the winning rule flows NULL.

Default Rules

Connect Sync ships with a large set of default (“out-of-box”) rules, typically numbered in the 100-200 precedence range. These handle standard scenarios:

• Joining AD users to Entra users by ms-DS-ConsistencyGuid
• Flowing standard attributes (displayName, mail, proxyAddresses, userPrincipalName)
• Computing cloudFiltered to exclude out-of-scope objects
• Handling password hash sync
• Managing Exchange hybrid writeback attributes

Never modify default rules directly. Connect upgrades replace them. Instead:

1. Identify the default rule you want to change.
2. Disable it (uncheck the Enabled box in the Synchronization Rules Editor).
3. Clone it by creating a new rule with the same scoping and join conditions.
4. Give the clone a higher precedence (lower number) than the original.
5. Make your changes in the clone.

This way, upgrades can replace the original rule without affecting your customization, and you can re-enable the original if you need to roll back.

Custom Sync Rule Patterns

Adding an Attribute Flow

To sync an AD attribute that is not in the default configuration:

1. Create a new inbound rule with a precedence below 100 (e.g., 50).
2. Set the scoping filter to match the object type you want.
3. Skip join rules (the default rules already handle joining).
4. Add a transformation: Direct flow, source attribute = your AD attribute, target = the metaverse attribute (you may need to add it to the metaverse schema first via directory extensions).

Filtering Objects with a Custom Rule

To exclude objects based on an attribute value:

1. Create a new inbound rule with precedence below the default rules.
2. Set a scoping filter matching the objects to exclude (e.g., extensionAttribute15 EQUAL NoSync).
3. Add a transformation: Constant, target = cloudFiltered, value = True.

See Filtering and Scoping for detailed examples.

Overriding an Attribute Value

To change how a specific attribute is computed:

1. Find the default rule that flows the attribute.
2. Create a new rule with a lower precedence number (higher priority).
3. Use the same scoping and join conditions.
4. Redefine the transformation for that attribute (expression, constant, or different source attribute).

Expression Syntax

Transformations can use expressions for complex attribute computation. The expression language supports:

• Functions: IIF(), IsNullOrEmpty(), Trim(), Left(), Right(), Mid(), Replace(), Word(), FormatDateTime(), and many more.
• Operators: String concatenation with & (ampersand).
• Special literals:
  • NULL - no value to contribute; lets lower-precedence rules contribute instead.
  • AuthoritativeNull - no value, and prevents lower-precedence rules from contributing.
  • IgnoreThisFlow - leave the target attribute unchanged (do not flow anything, but do not remove existing values either).

Example: Set displayName to “LastName, FirstName” format:

IIF(IsNullOrEmpty([givenName]),[sn],[sn]&", "&[givenName])

Connect Sync vs. Cloud Sync expressions: Connect Sync uses its own expression language with function syntax like IIF(), CBool(), CStr(). Cloud Sync uses a different expression builder with a similar but not identical function set. Rules written for one engine do not directly port to the other. See Cloud Sync expression language for the Cloud Sync equivalent.

Precedence Strategy

When planning custom rules, follow these conventions:

Keep at least 5-10 numbers between your custom rules so you have room to insert new rules between them later.

Multi-Valued Attribute Merging

When multiple inbound rules flow values to the same multi-valued attribute (like proxyAddresses), you need to set the merge type:

• Update (default) - highest precedence rule wins entirely.
• Merge - values from all in-scope rules are combined (case-sensitive dedup).
• MergeCaseInsensitive - same as Merge but case-insensitive dedup.

All rules flowing to the same attribute must use the same merge type, or you will get an error.

Troubleshooting Rule Issues

Use the Synchronization Service Manager’s Metaverse Search to find an object and inspect which rules contributed which attribute values. The Connectors tab shows join status and pending operations.