Skip to content

Synchronisation Rules

A Synchronisation Rule defines the complete relationship between a Connected System and the metaverse. It controls which objects are in scope, how objects are matched, when new Metaverse Objects are created, and how attributes flow between systems.

Synchronisation Rules are the central configuration mechanism for identity synchronisation in JIM. Every Connected System needs at least one Synchronisation Rule to participate in synchronisation.

What a Synchronisation Rule ties together

  1. Direction
    Whether data flows inbound (a source system into the metaverse) or outbound (the metaverse out to a target system).
  2. Scoping criteria
    Which objects the rule applies to.
  3. Object Matching Rules
    How to match a Connected System Object to an existing Metaverse Object.
  4. Projection or Provisioning
    What to do when no match is found.
  5. Attribute mappings
    Which attributes to synchronise and how to transform them.

Each rule also has a name and an optional description, a free-text note for recording what the rule is for and why it exists. The description is shown on the rule's Details tab and changes to it are tracked in the configuration change history.

Direction

Each rule has a direction that determines the flow of data.

Import (inbound)

Import rules process data from a Connected System into the metaverse. They are used with source systems: systems that provide authoritative identity data (HR databases, badge systems, etc.).

An import rule:

  • Reads CSOs from the Connected System's connector space
  • Attempts to join each CSO to an existing MVO using the rule's object matching configuration
  • Projects a new MVO if no match is found and projection is enabled
  • Flows attribute values from the CSO to the MVO

Export (outbound)

Export rules push data from the metaverse to a Connected System. They are used with target systems: systems that receive provisioned identity data (LDAP directories, email systems, etc.).

An export rule:

  • Evaluates MVOs in the metaverse against the rule's scoping criteria
  • Provisions a new CSO in the target system's connector space if one does not exist (and provisioning is enabled)
  • Flows attribute values from the MVO to the CSO
  • Creates Pending Exports for any changes

When enforce state is set on an export rule, JIM additionally detects and remediates attribute drift in the Connected System: if an exported attribute is changed externally, the next sync run pulls it back to the metaverse-derived value.

Scoping criteria

Scoping criteria determine which objects the rule applies to. Only objects that match are processed.

For import rules, criteria evaluate CSO attributes:

cs["objectClass"] = "user" AND cs["employeeType"] = "FTE"

For export rules, criteria evaluate MVO attributes:

mv["Object Type"] = "Person" AND mv["Employee Status"] = "Active"

Objects that fall out of scope are disconnected from the rule. This is important for the JML lifecycle: when an employee's status changes to "Leaver", they may fall out of scope for an export rule, triggering deprovisioning.

Criteria are organised into groups with AND/OR logic and support nested groups for complex conditions. Criteria expressions use the JIM expression language.

Each criterion is evaluated case-sensitively by default. Where a data source is inconsistent about casing (for example Sales versus SALES), you can switch an individual criterion to case-insensitive matching; see Case Sensitivity.

Relative dates in scope filters

A criterion on a date/time attribute can compare against either a fixed date (Absolute) or a date worked out Relative to the moment the rule runs. Relative criteria are re-evaluated on every run, so a scope that says "terminated within the last year" keeps moving with time, with no need to edit the rule.

A relative criterion is a count, a unit (Hours, Days, Weeks, Months or Years) and a direction (Ago for the past, From now for the future). Date/time operators read in calendar wording: before, on or before, after, on or after, equals, does not equal.

  • Whole-day rounding
    Days and coarser units resolve to midnight UTC, so "30 days ago" is a clean day boundary. The Hours unit keeps exact-instant precision for finer windows.
  • Calendar-correct
    Month and year offsets respect the calendar (31 March minus one month is the last day of February).
  • Evaluated on demand
    The boundary is resolved fresh each run from the host's UTC clock; nothing is stored as a fixed date.

For example, to scope an export rule to leavers terminated between 30 and 364 days ago, use an All group with two criteria on the termination-date attribute: on or before 30 days ago and after 364 days ago.

Configure this in the Scope tab of the Synchronisation Rule editor (choose Relative when the attribute is a date), or via the PowerShell cmdlets and the REST API.

Previewing a scope change

Changing a Scoping Criterion decides which objects the rule manages at all, and what that costs is decided by a different setting sitting beside it: narrowing an import rule takes objects out of scope, and the Out-of-Scope Action then decides whether their Metaverse Object joins survive; narrowing an export rule can delete the objects that leave from the target system, per the Deprovisioning Action. Widening pulls objects in, projecting and provisioning identities nobody has counted.

The Preview Scope Impact button beside the editor's save button starts a Configuration Change Preview of the criteria as they stand on the form, evaluated against the rule's saved criteria, changing nothing. It reports each object that would move, split by what the move actually costs it:

  • Leaving scope
    A joined object whose join would break, taking whatever it contributed out of the Metaverse with it; a joined object that would keep its join and simply stop receiving Attribute Flow; and an unjoined object that stops matching and loses nothing. Where a broken join would take a Metaverse Object's last connector, the preview follows the chain and reports which identities would become eligible for deletion.
  • Entering scope
    What each object would become, answered by running the same evaluation a synchronisation would: a new Metaverse Object projected, a join to an existing one, or an object provisioned into the target Connected System.

Two answers are deliberately negative rather than reassuring. Removing every criterion is called out as a warning, because it hands the rule every object of its type and is one click away from tidying up. And where another import Synchronisation Rule covers the same object type with no criteria of its own, that rule keeps every object in scope whatever this one says, so narrowing this rule disconnects nobody: the preview names that rule and counts no departures, rather than reporting a disconnection wave that would never happen.

Saving with a current preview on screen states its counts on the confirmation and records the preview against the change's Activity; edit the criteria afterwards and the preview is marked stale and contributes nothing. Automation gets the same evaluation through New-JIMConfigurationChangePreview -ScopingCriteriaGroup and the REST API's POST sync-rules/{id}/scoping-criteria/preview endpoint.

Object Matching Rules

Object Matching Rules define how a Connected System Object is matched to an existing Metaverse Object. Rules specify one or more attribute pairs to compare:

CSO Attribute MVO Attribute Description
employeeId Employee ID Match on employee identifier
mail Email Address Match on email address

JIM evaluates the matching rules in order and uses the first match found. You can configure multiple matching rules as a fallback strategy:

  1. First, try to match on employeeId (most reliable)
  2. If no match, try mail (secondary)
  3. If no match, try firstName + lastName (least reliable)

Attribute comparisons in a matching rule are case-sensitive by default. Where systems disagree on casing, you can make an individual rule case-insensitive; see Case Sensitivity.

Matching outcomes

Outcome Description
Joined Exactly one matching MVO found; the CSO is linked to it
No match No matching MVO found; projection may create one
Multiple matches More than one MVO matches; an error is raised (ambiguous join)

Simple vs advanced matching mode

Object matching can be configured at two levels:

  • Simple mode
    Configured at the Connected System level; the matching rules are shared across all Synchronisation Rules for that system. Easier to manage when matching is uniform.
  • Advanced mode
    Configured per Synchronisation Rule, so each rule can match independently. Use this when different Synchronisation Rules need different matching strategies against the same Connected System.

A Simple mode rule also names the Metaverse Object Type it searches. It has to: with no Synchronisation Rule behind it, nothing else says where to look, and a rule that does not say is skipped during synchronisation. An Advanced mode rule does not name one, because the Synchronisation Rule that owns it already does.

JIM refuses to save a rule that could never match, naming what is missing. If any rule already stored has that shape, the Matching tab says so and names it, so it can be removed and recreated.

Previewing a behaviour change

The five behaviour toggles are the settings whose consequences are hardest to picture, because none of them names a population. Disabling a rule reads like pausing it and is closer to withdrawing every value it owns. Turning Provision To Connected System on reads like granting a capability and is account creation at scale. Turning Enforce State off reads like relaxing a constraint and is a standing decision to let a target system diverge.

Preview Behaviour Impact, beside the other previews on the rule's editor, answers what your edited toggles would do without saving them:

Transition What it means
No longer creates an identity Objects that would have had a Metaverse Object projected for them and now would not. They stay in the connector space, unmanaged.
No longer creates an account Metaverse Objects that would have had an account created in the target system and now would not. Nothing existing is destroyed, which is why it goes unnoticed.
Free to drift from JIM Objects whose divergence from what JIM holds would no longer be corrected.
Identity created / Provisioned / Drift corrected The inverses, for a toggle being turned on.

Direction cannot be previewed, and cannot be changed. A saved rule's Attribute Flow mappings and Object Matching Rules are written for the direction it has: an import rule's mappings write Metaverse Attributes and its matching rules search the Metaverse, so flipped to Export every one of them would address the wrong side. The preview refuses with a blocking finding rather than answering about a configuration that cannot work. Create a rule in the direction you need instead.

Toggles that do nothing in the rule's direction are called out rather than counted as zero, because "nothing is affected" and "this setting does not apply here" are different statements and only one of them explains an empty result. Enforce State and Provision To Connected System apply to Export rules; Project To Metaverse applies to Import rules.

Automation gets the same evaluation: New-JIMConfigurationChangePreview -SyncRuleId <id> -RuleState Disabled, or POST to the rule's behaviour/preview endpoint. See Configuration Change Preview.

Previewing an Object Matching change

Matching mistakes do not fail. A rule matched too loosely joins an account to the wrong identity, and everything it contributes goes with it; a rule matched too tightly projects a second identity beside the right one. Both look like a successful synchronisation, and both are found later by a person.

The Matching tab therefore offers Preview Impact beside Add Matching Rule, and again on the Simple/Advanced switch. It answers what the proposed matching would do, without saving it.

The preview reports:

Transition What it means
Joins a different Metaverse Object The object joins one identity under the rules as they stand and would join a different one. The most dangerous outcome a matching change can produce.
Joins instead of projecting The object matches nothing today, so the next synchronisation would create a new identity for it, and under the proposal it would join an existing one. Usually what a widened rule is for.
Projects instead of joining The inverse, and a duplicate-identity risk: the object matches today and would match nothing, so a second identity would be created beside the one it should have joined.
Matches more than one Metaverse Object The proposal is ambiguous for this object, so its next synchronisation refuses it rather than joining it to anything.

One thing decides how to read every one of those counts: Object Matching Rules are evaluated only for objects that are not already joined. An account with a Metaverse Object keeps it, whatever you change here, so the impact covers the unjoined population alone. The preview says so before it says anything else.

Automation gets the same evaluation, over the whole matching configuration rather than one rule at a time: New-JIMConfigurationChangePreview -ConnectedSystemId <id> -MatchingRule <rules>, or POST to the Connected System's matching-rules/preview endpoint. Add -ObjectMatchingRuleMode to preview the Simple/Advanced switch. See Configuration Change Preview.

Projection and provisioning

These determine what happens when no match is found.

Projection applies to import rules. If projection is enabled, JIM creates a new MVO of the specified object type and links the CSO to it. This is how new identities enter the metaverse for the first time. If projection is not enabled, the CSO remains disconnected.

Provisioning applies to export rules. If provisioning is enabled, JIM creates a new CSO in the target system's connector space (and ultimately the target system itself, when the export Run Profile flushes Pending Exports). If provisioning is not enabled, the rule only updates objects that already exist in the target.

Deprovisioning Action

Provisioning's counterpart: each export rule's Deprovisioning Action determines what happens to the object in the Connected System when its Metaverse Object leaves the rule's scope or is deleted (for example, when a leaver's identity is removed by a deletion rule):

  • Disconnect (default): JIM breaks the join and leaves the object in place in the Connected System. Nothing is exported.
  • Delete: JIM queues a delete so the object is removed from the Connected System on the next export run.

The action applies regardless of how the object came to be joined: it makes no difference whether JIM provisioned it or matched (joined) a pre-existing object. If several export rules cover the same object with different actions, Delete wins.

Configure the action in the export section of the Synchronisation Rule editor. To review the deprovisioning behaviour of every export rule for an object type in one place, use the Downstream Deprovisioning panel on the Metaverse Object Type page (Admin, Schema, then the object type), where the action can also be changed inline.

Seeing what a run has deprovisioned

Every delete queued by a Deprovisioning Action is reported on the Activity of the run that staged it, so you can see exactly which accounts are about to be removed before the next export runs. Each queued delete appears on the deleted identity's execution item as a Pending Export outcome nested beneath the MVO Deleted outcome that caused it, naming the Connected System the account is being removed from, and is counted in the Activity's Pending Exports total. A leaver's execution item therefore reads as the whole chain: disconnected, Connected System Object deleted, identity deleted, then one Pending Export per downstream account being deprovisioned. Open the outcome to see the Pending Export's detail.

This applies wherever the deletion happens: during a Synchronisation Run Profile (when the Metaverse Object Type's deletion rule has no grace period, so the identity is deleted inline), and in the background Scheduled Identity Deletion batch that deletes identities once their grace period expires.

Previewing a destructive toggle change

Two of a Synchronisation Rule's settings can turn a routine scope exit into something you cannot take back: the Deprovisioning Action above, and an import rule's Out-of-Scope Action (whether objects that leave import scope keep their Metaverse Object join or are disconnected). Both are single dropdowns, and before this preview existed the first sign of what one meant was the synchronisation run that acted on it.

The Preview Deprovisioning Impact button beside the editor's save button starts a Configuration Change Preview of the toggles as they stand on the form, evaluated against the rule's saved configuration, changing nothing. It answers two different questions and keeps them apart:

  • What the next synchronisation would do differently. Objects the rule already has something to act on: a joined object whose Metaverse Object is already outside an export rule's scope would be deleted from the target system rather than disconnected (or the reverse), and a joined object outside import scope, or already marked obsolete, would be disconnected rather than keep its join (or the reverse). Where those disconnections would take a Metaverse Object's last connector, the preview follows the chain and reports which identities would become eligible for deletion.
  • What changes for every object the rule manages. Flipping an export rule's action to Delete deletes nothing today, but it changes what every future scope exit means for every managed object. The preview states that exposure as its own count ("scope-exit action changes"), so "3,400 objects in this system move from Disconnect to Delete" reads at a glance without overstating what the save itself does.

Where several import rules cover the same object type, the Out-of-Scope Action that applies is taken from the first applicable rule. If that is not the rule you are editing, the preview says so by name and counts nothing, because your change would do nothing while that rule exists.

Saving with a current preview on screen states its counts on the confirmation and records the preview against the change's Activity; edit either toggle afterwards and the preview is marked stale and contributes nothing. Automation gets the same evaluation through New-JIMConfigurationChangePreview -SyncRuleId and the REST API's POST sync-rules/{id}/destructive-toggles/preview endpoint.

Initial password

An account a Synchronisation Rule has just provisioned has no password, and in most directories cannot be signed in to or even enabled without one. The Initial Password tab of an export Synchronisation Rule tells JIM to set one on every account that rule creates.

For how the password channel works as a whole (policy discovery and its limits, where a password comes from, and the security rules that hold across every surface) see Passwords.

It is off until you turn it on, on every rule: JIM setting passwords on accounts nobody asked it to is not a sensible default.

It also depends on the rule provisioning. Only a newly created account has never had a password, so the tab appears only on an export rule with Provision ... to the Connected System? switched on, which is a setting on the Details tab. Switching that off removes the tab and switches the initial password off with it, rather than leaving a setting that reads as configured and can never run; any accounts parked waiting on those settings stop waiting. Switching provisioning back on brings the tab back with its settings intact, switched off.

The setting lives on the Synchronisation Rule rather than on the Connected System because rules are how JIM distinguishes populations. A rule provisioning contractors and a rule provisioning permanent staff into the same directory can reasonably want different password rules.

What you configure

  • Password Settings
    Where the password comes from. Either the policy JIM discovered on the Connected System itself (the default, so the generated password satisfies the target's own rules without you restating them), or settings you write here, or one password you choose for every account. The first two generate a different password per account: choosing your own settings starts from the discovered policy rather than from nothing, switching between the two never discards what you configured, and the generator produces random characters, words, or a pronounceable password, telling you the minimum length and character classes the result is guaranteed to carry.
  • After the password is set
    Whether the account holder must choose a new password at their next sign-in (the default), whether it ages normally, or whether it never expires. Only the behaviours the Connector can actually apply are offered.
  • Enable the account once the password is set
    On by default. A provisioned account nobody can sign in to is rarely what was wanted, and directories that refuse to enable an account without a policy-compliant password need the enable to follow the password rather than accompany the create.

No generated password is ever stored, in JIM's database, its logs, its Activities, its API responses or anywhere else. Each is generated at the moment it is delivered, handed to the Connector, and dropped.

Nobody receives a generated password, including you. Its job is to get the account into a working state, since most directories will not enable an account or let it be used until it holds a password that meets their rules. When the person actually needs to sign in, set their password then with the set-password action on the Connected System Object and hand them the value; requiring a change at their next sign-in then does what you would expect. See Passwords.

One password for every account

The third Password Settings option sets one password you choose on every account the rule provisions, so you can tell a new starter what it is. This option is not recommended, and the portal says so beside it: every account the rule provisions shares that password until each person changes it, so anybody who learns of this can sign in as any new starter who has not.

Leave After the password is set on Require a change at the next sign-in. It is what ends each account's share of the password; any other choice leaves every account the rule provisions on it until somebody changes it by hand.

This is the only password JIM stores. It is stored encrypted and cannot be shown to you again: the portal fields are blank whenever you open them, no REST response or cmdlet returns it, and configuration change history records a keyed hash rather than the value. It is protected at rest exactly as a Connected System's credentials are. Leaving those fields blank keeps the stored password, so changing another setting is safe.

What JIM will tell you is that a password is set and when it last changed, on the panel and through Get-JIMSyncRuleInitialPassword (staticPasswordSet and staticPasswordSetAt). Change it whenever somebody who knew it leaves; that date is the only thing that can date a shared password:

$password = Read-Host -AsSecureString "New shared initial password"
Set-JIMSyncRuleInitialPassword -Id 5 -StaticPassword $password -ChangeReason "Rotated after a leaver (CHG0043)"

A password the Connected System would refuse is rejected when you set it, rather than parking every account the rule provisions. A rule set to this option with no password stored is refused too, for the same reason.

What happens after provisioning

Setting the password is a separate step from creating the account, and deliberately cannot fail the export that created it. The account exists; reporting its export as failed would have JIM retry the create.

The password is therefore delivered in its own pass at the end of every export run, over everything the Connected System still owes rather than only what this run created. An ordinary export run is consequently the retry vehicle: a directory brought back online, or a right granted to JIM's service account, is picked up by the next run that was going to happen anyway, with no separate Run Profile to schedule.

Each account ends up in one of these states, all of them reported on the export's Activity:

State Meaning What clears it
Delivered The password was set. Nothing; the account no longer owes one and JIM keeps no record beyond the Activity.
Retrying Something JIM cannot control got in the way: the directory was unreachable, or the account was not visible yet (after a create, usually replication catching up). The next export run over that Connected System.
Parked The target refused the password itself, for not satisfying the rules in force for that account. Retrying would produce another password refused for the same reason, so JIM stops. You. See below.
Expired A week passed without success. JIM stops trying and records the fact rather than quietly forgetting the account. Nothing automatic; the account needs a password set by other means.

The target's own words are kept verbatim on a parked account, because why a directory refuses a password is a property of that directory's policy and the single most useful thing to be shown.

Clearing parked accounts

Parking is not a one-way door. Saving a change to the Synchronisation Rule's initial password settings releases every account parked against that rule, and they are attempted again on that Connected System's next export run. Nothing needs to be regenerated or invalidated in the meantime: a generated password is produced afresh at delivery, and setting a new shared password is itself the change that releases the work.

Saving an unrelated part of the same rule releases nothing. Those accounts were refused on settings the target has already given its answer on, so retrying them unchanged would fail identically and inflate an attempt count that is supposed to mean "distinct configurations tried".

The typical loop is therefore: read what the target said on the parked account, correct the generator settings (most often length or the character classes), save, and let the next export run deliver.

Where JIM tells you

You do not have to go looking. Parked and expired accounts are reported in three places:

  • The Synchronisation Rules and Connected Systems lists
    An amber chip counts the accounts parked against a rule, and a red one counts those that expired. They stay separate because they ask for different things: parked work is fixed by correcting the settings and saving, expired work cannot be fixed that way at all. A rule or system with nothing outstanding shows no chip, so the lists stay quiet until something needs you.
  • The rule's Passwords tab itself
    The tab carries the parked count as a badge, so you see it without opening the tab, and the tab shows the accounts grouped by what the target said, biggest group first, with the target's own words unaltered and how long each fault has been there. Correct the settings and it confirms, before you save, how many accounts saving will release; it stays quiet for an edit that would not change what is delivered.
  • Automation
    Get-JIMSyncRuleInitialPassword and the Synchronisation Rule's initial password endpoint report parkedAccountCount, expiredAccountCount and the same grouped reasons. Get-JIMConnectedSystem -Id <id> carries the two counts for a whole Connected System.

Attribute mappings

Attribute mappings define which attributes to synchronise and how to transform them. Each mapping maps a source attribute (or expression) to a target attribute.

Direct mappings

A direct mapping copies the attribute value as-is, with no transformation:

Source Target
givenName First Name
sn Last Name

Expression mappings

An expression mapping applies a transformation using the JIM expression language:

Source Target
Lower(cs["givenName"]) + "." + Lower(cs["sn"]) + "@company.com" Email Address
mv["First Name"] + " " + mv["Last Name"] displayName
IIF(Eq(mv["Employee Status"], "Active"), 512, 514) userAccountControl

Missing Input Behaviour

An expression whose input has no value on the object does not fail; it evaluates and produces a structurally broken value (jane.@company.com, CN=,OU=Users,...) that nothing downstream can tell from a good one. Missing Input Behaviour, set beside the expression on each expression source, decides what JIM does instead:

Behaviour Effect
Evaluate anyway (default) Runs the expression regardless; correct where the expression guards the absence itself with IIF() or Coalesce().
Contribute no value Skips the mapping without reporting anything; the outcome is resolved by Attribute Priority.
Fail this mapping Skips the mapping and records an Expression Missing Input error; the object's other attributes still flow.
Fail the object Nothing flows for the object at all, and it is recorded as an Expression Missing Input error. For identity-critical values such as a Distinguished Name.

JIM derives the inputs from the mv["..."] and cs["..."] accessors in the expression; you do not list them. An absent attribute, a null and an empty string all count as no value. See Missing Input Behaviour for the full guidance.

Changing a mapping after it is created

A mapping's settings, meaning how it behaves rather than what it reads and writes, can be changed at any time: Missing Input Behaviour and the expression itself, "Null is a value" and inbound value processing on an import mapping, Initial Export Only on an export mapping, and whether the mapping is enabled at all. Use the portal, PATCH /sync-rules/{id}/mappings/{mappingId}, or Set-JIMSyncRuleMapping.

Disabling a single mapping

Every Attribute Flow mapping can be disabled individually, without touching the rest of its Synchronisation Rule. A disabled mapping is skipped by synchronisation in both directions: it contributes nothing inbound (and drops out of the attribute's Attribute Priority contention), flows nothing on export, at provisioning as much as on updates, and Drift Correction leaves its target attribute alone. Each run whose rules carry disabled mappings notes how many it skipped in the service log.

Disabling one mapping is the smallest safe response to a single source attribute that has been removed or redefined at the Connected System; disabling the whole rule stops every flow it carries. Where JIM disables a mapping, or a whole Synchronisation Rule, on your behalf (the schema refresh decision), it records why: the reason is shown on the Attribute Flow tab for a mapping, and beside the Enabled switch for a rule, and saving the item enabled clears it. Re-enabling is always a manual choice.

What a mapping targets, and whether its source is an attribute or an expression, is not editable. Retargeting revalidates against attribute types and plurality, and for an import mapping it reopens the mapping's place in the Attribute Priority order, so it is a delete and a create rather than an edit. That is deliberate: the priority position is lost either way, and an interface that hid it would lose it silently.

Multi-source mappings

A multi-source mapping combines several source attributes into one target. This is the concept-level pattern; in practice, you typically express multi-source flows through expression mappings that reference each contributing attribute.

Multi-valued attributes

Mappings support both single-valued and multi-valued attributes. A Multi-Valued attribute holds a list of values (group memberships, email aliases, and so on); a Single-Valued attribute holds at most one. How a mapping behaves depends on the plurality of the source and the target:

Source Target Behaviour
Single-Valued Single-Valued ✅ The value flows normally.
Multi-Valued Multi-Valued ✅ Every value flows.
Single-Valued Multi-Valued ✅ The value flows as a single-item list.
Multi-Valued Single-Valued ⚠️ See below.

Multi-Valued to Single-Valued. A Single-Valued target can hold only one value, so this mapping is only meaningful when the object actually has one value:

  • If the object has one value, it flows (import) or is exported normally.
  • If the object has more than one value, JIM does not pick one arbitrarily. An arbitrary choice would be non-deterministic (a Connected System does not guarantee value order) and, on export, could never be reconciled on the next import. Instead, JIM flows nothing for that attribute and records an error against the object; the object's other attributes still synchronise. The error appears as a Multi-Valued to Single-Valued item in the run's Activity.

The Attribute Flow editor warns you at configuration time when a mapping is Multi-Valued to Single-Valued, and the mapping is flagged in the Attribute Flow list, so you can decide before running whether it is what you intend.

To flow a chosen value deterministically instead of erroring, either target a Multi-Valued attribute, or use an Expression mapping to select one value (for example Join()/Split() or an index into the list). Reference attributes on import are exempt from this rule; they are resolved separately.

Standard Mapping hints

Choosing which Metaverse Attribute a Connected System attribute belongs to is guesswork when the schema is unfamiliar, and the answer is usually already recorded: every built-in Metaverse Attribute documents its counterparts in the SCIM 2.0 and LDAP/Active Directory vocabularies as Standard Mappings. The Attribute Flow editor shows them while you work:

  • The counterpart name sits beside each attribute in the picker, so First Name reads as givenName on an LDAP system, and name.givenName on a SCIM one. Where a mapping carries a note (userAccountControl needs a transform, SCIM emails is multi-valued), hovering the counterpart shows it.
  • The correspondence for the attribute you picked is stated in full. Choose givenName as an import source and the editor says so: "In LDAP/AD, givenName corresponds to the Metaverse Attribute First Name", marks that attribute Suggested in the picker, and offers a one-click Use First Name button. Export works the same way in reverse, naming the Connected System attribute the standard says should receive the value.
  • More than one attribute can correspond to a name. LDAP mail fits both the single-valued Email and the multi-valued Emails; both are offered, and JIM does not choose for you.
  • A correspondence you cannot act on is explained rather than hidden. Where the standard names an attribute this mapping cannot target, the editor says which and why: the types differ (accountExpires arrives as text where Account Expires is a date, so an Expression source is needed to convert it), another Attribute Flow already targets it, or the Connected System reports it read-only. The mapping's note is shown alongside, which is usually where the conversion is described.

Which vocabulary applies comes from the Connector: the LDAP Connector declares LDAP/AD, so an LDAP system's editor shows LDAP counterparts and nothing else. Where a Connector declares no vocabulary (the File Connector, for example, since a delimited file's column names are whatever the file carries), the editor matches attribute names against every standard instead and labels whichever one answered.

The hints are advisory, always. Nothing is filtered, disabled, or chosen for you: every attribute stays selectable, and an attribute with no counterpart simply shows nothing, which is not an error. Standard Mappings are never consulted during synchronisation; what flows is exactly what your Attribute Flows say. Custom attributes behave identically once you record Standard Mappings against them, and JIM does not distinguish a mapping it seeded from one you authored.

Value processing (inbound)

Source text is often dirty: stray padding, inconsistent casing, or a "value" that is really just spaces. For import mappings that target a text Metaverse attribute, you can clean and normalise the imported value before it flows to the Metaverse, configured per mapping in the Attribute Flow editor. Value processing applies to direct and expression mappings alike, and only to text attributes; it does not appear for export mappings or non-text targets.

Four controls are available:

  • Treat whitespace as no value
    A whitespace-only or empty value is treated as no value: it does not flow, and clears any existing Metaverse value. This is on by default, so a stray space no longer masquerades as a real value. Switch it off where whitespace is genuinely meaningful.
  • Trim leading and trailing whitespace
    Removes surrounding whitespace, so ··John·· becomes John (each · represents a space).
  • Collapse internal whitespace
    Reduces runs of consecutive whitespace inside the value to a single space, so multiple spaces or tabs between words collapse to one. For example, John···Smith becomes John Smith (each · represents a space).
  • Case normalisation
    Converts the value to Upper, Lower, or Title case, or leaves it unchanged (None). Useful for folding usernames or email addresses to a consistent case.

The transforms run in a fixed order: trim, then collapse, then case normalisation, then the whitespace-as-no-value decision. Because the whitespace decision runs last, a value that trims down to nothing is correctly treated as no value. Value processing is normalisation; it runs before Attribute Priority resolves which rule's value wins.

When Treat whitespace as no value is switched off and a whitespace-only value is therefore stored, the portal flags it with a (whitespace) indicator rather than rendering a misleading blank cell, so administrators can tell a real-but-invisible value apart from an absent one.

Initial Export Only (outbound)

Some attributes should be set once when JIM creates an object, then left alone: an initial password or API token, a one-time setup value, or any attribute the target system should own after provisioning. For export mappings, enabling Initial Export Only on a mapping does exactly that:

  • The attribute flows only when JIM provisions the object into the Connected System (the create export), and JIM retries until the initial export is confirmed.
  • Once the object is provisioned, the attribute becomes unmanaged on that Connected System Object: later Metaverse changes are not exported for it, and Drift Correction (enforce state) leaves it alone, so the value can be changed freely in the Connected System.
  • Objects that join to pre-existing objects in the Connected System never receive the value; the external system already owns it.
  • Import mappings for the same attribute are unaffected, so the externally-owned value can still flow back into the metaverse if you map it inbound.

Configure it per mapping in the Attribute Flow editor (the option appears for export Synchronisation Rules only), via New-JIMSyncRuleMapping -InitialExportOnly in PowerShell, or via the REST API. The Connector Space object page marks affected attributes with an Unmanaged indicator once the object is past provisioning.

Two behaviours to be aware of:

  • The setting is honoured live: enabling it on an existing rule stops future exports of that attribute to already-provisioned objects, and disabling it resumes normal management (the next synchronisation and Drift Correction re-assert the Metaverse value).
  • If several export mappings target the same attribute for an object type, the attribute only becomes unmanaged when every such mapping is Initial Export Only; a single normally-managed mapping keeps it managed.

Initial Export Only is your choice about an attribute the Connected System would happily let JIM keep writing. Where the Connected System itself only accepts a value at creation, JIM applies the same create-once behaviour on its own, without the setting: see Attribute writability.

Previewing an Attribute Flow change

Changing a mapping rewrites an attribute on every object the rule manages, on the next synchronisation, and nothing on the editor says what the values become. An Expression edit that malforms one case in a thousand (ada.@corp.local for a person with no surname) is invisible until it has flowed.

The Preview Attribute Flow Impact button beside the editor's save button starts a Configuration Change Preview of the mappings as they stand on the form, evaluated against the rule's saved mappings, changing nothing. It reports, per object and per attribute:

  • The value the object would end up with
    Stated as an old-to-new pair, so a domain cutover reads as ada@old.example becoming ada@new.example rather than as a count. JIM groups identical pairs together and recognises the shape of the change (a changed domain, a changed container, a casing change, an added or removed prefix or suffix), so a thousand identical rewrites read as one line with a count beside it.
  • Values that would be withdrawn
    Where a mapping would stop producing a value for an object, the attribute is left blank rather than rewritten, and that is counted separately.
  • Objects the mapping could not be evaluated for
    An Expression that throws, or one whose Missing Input Behaviour fails the mapping because a required attribute has no value on that object. These are the handful of objects a cutover would otherwise leave without an address, and they are reported as their own outcome rather than as no change.

The evaluation is the synchronisation engine's own, run twice per object (once against the saved configuration and once against the proposal) and compared, so Attribute Priority, Missing Input Behaviour and Expression evaluation are answered by the engine rather than approximated.

Both directions state a true before-and-after. An import mapping's old value is what the identity holds in the metaverse today; an export mapping's is what the object holds in the target Connected System today, including where the saved configuration would write nothing because the target is already correct, which is exactly the case a domain cutover is.

Three answers are deliberately negative rather than reassuring:

  • A proposed mapping that would lose Attribute Priority to another contributing rule is called out: a synchronisation would evaluate it and then write nothing, so reporting the values it produces would describe a write that never happens.
  • Removing a mapping outright changes no value. Inbound Attribute Flow contributes what its mappings produce, so a mapping that no longer exists leaves the values it last wrote in place; they stay as they are and stop being maintained. The preview says so rather than reporting a withdrawal.
  • The preview covers this Connected System only. Where another Connected System's rule also writes the attribute, that rule takes its turn on its own next synchronisation, so what it would write instead is named rather than guessed at.

Saving with a current preview on screen states its counts on the confirmation and records the preview against the change's Activity; edit the mappings afterwards and the preview is marked stale and contributes nothing. Automation gets the same evaluation through New-JIMConfigurationChangePreview -AttributeFlowMapping and the REST API's POST sync-rules/{id}/mappings/preview endpoint.

Attribute Priority

When more than one import rule maps to the same Metaverse Object attribute, Attribute Priority decides which contributor wins, so the result never depends on the order your synchronisations happen to run in. It is an inbound concern: it governs how values flow from Connected Systems into the metaverse, and does not change how the metaverse is exported back out.

Priority is held per attribute, per contributing rule, not as a single level on the whole Synchronisation Rule. The same Connected System can therefore rank first for one attribute and second for another, and a single system can even contribute through several differently-scoped rules at different priorities.

How a winner is chosen

For a given Metaverse attribute, JIM evaluates every contributing import rule in priority order (1 is highest):

  • The first contributor with a value wins.
    Lower-priority contributors are not consulted.
  • A rule with no opinion is skipped.
    If a rule does not apply to the object (it is disabled, no object from its Connected System is joined, or the joined object is out of the rule's scope), it is passed over and the next priority is considered.
  • If nobody contributes, the attribute is left unset.

For example, an identity drawing data from two source systems:

  • HR system provides First Name and Last Name (priority 1: authoritative)
  • Badge system also provides First Name (priority 2: secondary)

The HR system's First Name wins because its contribution ranks higher; the badge system only fills in where HR has no opinion.

Null is a value

By default, if the highest-priority source has no value for an attribute, JIM falls through to the next source. That is usually right, but not always: when the authoritative source deliberately clears a value, you want the clear to propagate, not to be back-filled from a stale secondary copy that still holds the old value.

Enabling Null is a value on a contributor changes that. If the contributor is connected and in scope but supplies no value, JIM stops there and asserts "no value": the attribute is cleared downstream, and lower-priority sources are not consulted. This is distinct from a rule simply having no opinion; a rule that does not apply to the object is still skipped regardless of this setting.

Typical uses are a manager or department cleared at the authoritative source that must propagate as a clear, and a primary-system migration where the new system is authoritative for the people it knows about (including their blanks). It is deliberately powerful: a misbehaving priority-1 import (an empty file, a truncated delta) becomes a mass-clearing event rather than a harmless no-op, so treat Null is a value as an authoritative, considered choice.

Configuring priority

Attribute Priority is configured per (Metaverse Object Type, attribute), not on the Synchronisation Rule editor. Open the Metaverse Object Type (Administration → Schema → Object Types), select the Attributes tab, and expand the contributors list for any attribute that has more than one contributor. From there you drag contributors to reorder them and toggle Null is a value per contributor. A newly added import mapping joins at the lowest priority, so a new source never silently takes over an attribute until you promote it explicitly. The same configuration is available via the PowerShell cmdlets and the REST API.

Full detail: Attribute Priority covers re-election when a winning source disconnects or withdraws, multi-valued attribute semantics, per-value provenance, and how to see resolution decisions in Synchronisation Activities.

Common workflows

Setting up an import rule:

  1. Create a Synchronisation Rule with direction Import, choosing the source object type in the Connected System and the target Metaverse Object Type
  2. Add attribute mappings to flow values from CSO attributes onto the corresponding MVO attributes
  3. Configure Object Matching Rules so incoming objects join to the right MVOs
  4. Decide whether to project new MVOs when no match exists, and enable that on the rule

Setting up an export rule with scoping:

  1. Create a Synchronisation Rule with direction Export, with provisioning enabled if you want JIM to create objects in the target system
  2. Add attribute mappings to flow values from MVO attributes onto CSO attributes
  3. Add scoping criteria so only the relevant MVOs are exported (for example, only person objects whose department is IT)
  4. Configure Object Matching Rules for the export direction
  5. Decide whether to enforce state, i.e. detect and correct drift in the target system

Example: a complete import rule

A complete import rule for an HR system might look like:

Component Configuration
Name HR Import - Employees
Direction Import
Connected System HR Database
Scoping Eq(cs["employeeType"], "FTE")
Object Matching Rule 1 Match cs["employeeId"] to mv["Employee ID"]
Projection Create MVO of type Person
Attribute mappings cs["givenName"] to mv["First Name"] (direct)
cs["sn"] to mv["Last Name"] (direct)
cs["department"] to mv["Department"] (direct)
cs["employeeId"] to mv["Employee ID"] (direct)
Capitalise(cs["givenName"]) + " " + Capitalise(cs["sn"]) to mv["Display Name"] (expression)

This rule imports full-time employees from the HR system, joins them to existing Metaverse Objects by employee ID, creates new Metaverse Objects for new starters, and flows their attributes into the metaverse.

Finding a Synchronisation Rule

Once a deployment has more than a handful of rules, the Synchronisation Rules list carries filters above the table so you can narrow it to the rules you care about:

Filter Narrows to
Connected System Rules belonging to the systems you pick. Only systems that actually have rules are offered.
Direction Inbound (Import) or Outbound (Export) rules.
Action Projects (Import rules that create Metaverse Objects), Provisions (Export rules that create Connected System Objects), or Flow Only (rules that create nothing and only flow attribute values).
Status Enabled or Disabled rules.

Each filter accepts several values, and the filters combine: picking two Connected Systems and the Outbound direction shows the outbound rules of either system. Leaving a filter empty means "all".

The search box in the table's toolbar narrows whatever the filters left, matching on the rule name. It filters as you type, so there is nothing to press. Clearing the search box returns the filtered list rather than the full one, so you can keep a filter in place while searching within it.

The same filters are available to automation: see Get-JIMSyncRule's -Direction, -ActionType and -Status parameters, and the matching query parameters on the Synchronisation Rules list endpoint in the REST API.

Confirming a change before you save it

Saving a Synchronisation Rule can be harmless or far-reaching, and the two sit side by side on the same page: renaming a rule is beside the Deprovisioning Action that decides whether leavers' accounts are deleted. JIM judges each save by the properties that actually changed:

  • Cosmetic changes (name, description) save straight away with no prompt.
  • Changes that affect synchronisation (scope, mappings, Object Matching Rules, direction, enabling or disabling the rule) show a confirmation listing exactly what is changing, from which value to which, and remind you that a Full Synchronisation is what puts it into effect.
  • Destructive changes (Deprovisioning Action, Inbound Out-of-Scope Action) additionally state, in plain terms, what the change will do: which objects will be deleted rather than disconnected, or disconnected rather than left joined.

The same rules apply across every configuration surface; see Configuration changes for the full picture, including when JIM stays silent.

Manage Synchronisation Rules

See also