Synchronisation Rules¶

Synchronisation Rules define how data flows between Connected Systems and the metaverse. They control attribute mappings, scoping criteria, and object matching logic. The cmdlets on this page cover the full lifecycle of Synchronisation Rule configuration.

Synchronisation Rule CRUD¶

Create, retrieve, update, and delete Synchronisation Rules.

Get-JIMSyncRule¶

Retrieves one or more Synchronisation Rules. When called without parameters, returns all Synchronisation Rules. Use the parameter sets to filter by ID, Connected System ID, or Connected System name, and the -Direction, -ActionType and -Status filters to narrow the list further.

The filters combine with AND, and each of -Direction, -ActionType and -Status accepts several values, which combine with OR. -Name narrows whatever the other filters left, so removing it returns those results. These are the same filters offered on the Synchronisation Rules page of the JIM portal.

Syntax¶

# List all Synchronisation Rules (default), optionally with a piped Connected System
Get-JIMSyncRule [-InputObject <PSCustomObject>] [-Name <string>] [-Direction <string[]>]
    [-ActionType <string[]>] [-Status <string[]>]

# By Synchronisation Rule ID
Get-JIMSyncRule -Id <int>

# By Connected System ID
Get-JIMSyncRule -ConnectedSystemId <int> [-Name <string>] [-Direction <string[]>]
    [-ActionType <string[]>] [-Status <string[]>]

# By Connected System name
Get-JIMSyncRule -ConnectedSystemName <string> [-Name <string>] [-Direction <string[]>]
    [-ActionType <string[]>] [-Status <string[]>]

Parameters¶

Name	Type	Required	Description
`Id`	`int`	Yes (ById set)	The ID of a specific Synchronisation Rule to retrieve
`ConnectedSystemId`	`int`	No	Filter Synchronisation Rules by Connected System ID. Accepts pipeline input.
`ConnectedSystemName`	`string`	No	Filter Synchronisation Rules by Connected System name. Must be an exact match.
`InputObject`	`PSCustomObject`	No	A Connected System object from the pipeline (for example from `Get-JIMConnectedSystem`). Its `Id` filters the rules, equivalent to `-ConnectedSystemId`.
`Name`	`string`	No	Filter Synchronisation Rules by name. Supports wildcards (e.g., `"Inbound*"`).
`Direction`	`string[]`	No	Filter by direction: `Import` (inbound) or `Export` (outbound).
`ActionType`	`string[]`	No	Filter by the action the rule performs: `Projects`, `Provisions`, or `FlowOnly`.
`Status`	`string[]`	No	Filter by state: `Enabled` or `Disabled`.

ActionType values map to what a rule creates: Projects for Import rules that project new Metaverse Objects, Provisions for Export rules that provision new Connected System Objects, and FlowOnly for rules that create no objects and only flow attribute values.

Output¶

Returns one or more Synchronisation Rule objects containing the rule configuration, direction, projection/provisioning settings, and enabled state.

Examples¶

List all Synchronisation Rules

Get-JIMSyncRule

Get a specific Synchronisation Rule by ID

Get-JIMSyncRule -Id 5

Filter by name

Get-JIMSyncRule -Name "Inbound*"

Get Synchronisation Rules for a Connected System

Get-JIMSyncRule -ConnectedSystemName "Active Directory"

Find enabled outbound rules

Get-JIMSyncRule -Direction Export -Status Enabled

Find the rules that create objects

Get-JIMSyncRule -ActionType Projects, Provisions

Combine filters to audit one system

Get-JIMSyncRule -ConnectedSystemName "Active Directory" -Direction Export -Status Disabled

Pipeline from Connected System ID

$cs = Get-JIMConnectedSystem -Name "HR System"
Get-JIMSyncRule -ConnectedSystemId $cs.Id

Pipe Connected Systems straight in, and filter them

Get-JIMConnectedSystem -Name "HR*" | Get-JIMSyncRule -Direction Import -Status Enabled

New-JIMSyncRule¶

Creates a new Synchronisation Rule for a Connected System. The rule defines how objects flow between the Connected System and the metaverse.

Syntax¶

# By Connected System ID (default)
New-JIMSyncRule -Name <string> -ConnectedSystemId <int>
    -ConnectedSystemObjectTypeId <int> -MetaverseObjectTypeId <int>
    -Direction <string> [-Description <string>] [-ProjectToMetaverse]
    [-ProvisionToConnectedSystem] [-Enabled <bool>]
    [-OutboundDeprovisionAction <string>] [-ChangeReason <string>] [-PassThru]

# By Connected System name
New-JIMSyncRule -Name <string> -ConnectedSystemName <string>
    -ConnectedSystemObjectTypeId <int> -MetaverseObjectTypeId <int>
    -Direction <string> [-Description <string>] [-ProjectToMetaverse]
    [-ProvisionToConnectedSystem] [-Enabled <bool>]
    [-OutboundDeprovisionAction <string>] [-ChangeReason <string>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`Name`	`string`	Yes (Position 0)		Display name for the Synchronisation Rule
`ConnectedSystemId`	`int`	Yes (ById set)		The ID of the Connected System this rule belongs to
`ConnectedSystemName`	`string`	Yes (ByName set)		The name of the Connected System this rule belongs to
`ConnectedSystemObjectTypeId`	`int`	Yes		The object type ID on the Connected System side
`MetaverseObjectTypeId`	`int`	Yes		The object type ID on the metaverse side
`Direction`	`string`	Yes		Data flow direction. Valid values: `Import`, `Export`
`Description`	`string`	No		Optional description of what the Synchronisation Rule is for. Maximum 1000 characters.
`ProjectToMetaverse`	`switch`	No	`$false`	When set, import rules will project new Metaverse Objects. Only applicable when Direction is `Import`.
`ProvisionToConnectedSystem`	`switch`	No	`$false`	When set, export rules will provision new Connected System Objects. Only applicable when Direction is `Export`.
`Enabled`	`bool`	No	`$true`	Whether the Synchronisation Rule is active
`OutboundDeprovisionAction`	`string`	No	`Disconnect`	Export rules: action when an MVO falls out of the rule's scope or is deleted. `Disconnect` leaves the CSO untouched in the target system; `Delete` queues a delete so the CSO is removed from the target
`ChangeReason`	`string`	No		Optional reason ("commit message") recorded with this change and shown in the configuration change history. Maximum 2000 characters.
`PassThru`	`switch`	No	`$false`	Returns the created Synchronisation Rule object

Output¶

With -PassThru, returns the created Synchronisation Rule object. Without it, returns nothing.

ShouldProcess impact level: Medium.

Examples¶

Create an import Synchronisation Rule with projection

New-JIMSyncRule -Name "AD User Import" `
    -Description "Imports user accounts from Active Directory and projects new joiners into the Metaverse" `
    -ConnectedSystemId 1 `
    -ConnectedSystemObjectTypeId 3 `
    -MetaverseObjectTypeId 1 `
    -Direction Import `
    -ProjectToMetaverse `
    -PassThru

Create an export Synchronisation Rule by Connected System name

New-JIMSyncRule -Name "AD User Export" `
    -ConnectedSystemName "Active Directory" `
    -ConnectedSystemObjectTypeId 3 `
    -MetaverseObjectTypeId 1 `
    -Direction Export `
    -ProvisionToConnectedSystem

Create an export Synchronisation Rule that deletes leavers from the target system

New-JIMSyncRule -Name "AD User Export" `
    -ConnectedSystemId 2 `
    -ConnectedSystemObjectTypeId 3 `
    -MetaverseObjectTypeId 1 `
    -Direction Export `
    -ProvisionToConnectedSystem `
    -OutboundDeprovisionAction Delete

Create a disabled Synchronisation Rule

New-JIMSyncRule -Name "HR Import (Draft)" `
    -ConnectedSystemId 2 `
    -ConnectedSystemObjectTypeId 5 `
    -MetaverseObjectTypeId 1 `
    -Direction Import `
    -Enabled $false

Set-JIMSyncRule¶

Modifies an existing Synchronisation Rule. Supports renaming, toggling enabled state, and changing projection/provisioning settings.

Syntax¶

# By ID (default)
Set-JIMSyncRule -Id <int> [-Name <string>] [-Description <string>]
    [-ProjectToMetaverse <bool>] [-ProvisionToConnectedSystem <bool>]
    [-InboundOutOfScopeAction <string>] [-OutboundDeprovisionAction <string>]
    [-EnforceState <bool>] [-ChangeReason <string>] [-PreviewActivityId <guid>] [-PassThru]

# Enable shortcut
Set-JIMSyncRule -Id <int> -Enable [-ChangeReason <string>] [-PassThru]

# Disable shortcut
Set-JIMSyncRule -Id <int> -Disable [-ChangeReason <string>] [-PassThru]

# By input object
Set-JIMSyncRule -InputObject <PSCustomObject> [-Name <string>] [-Description <string>]
    [-ProjectToMetaverse <bool>] [-ProvisionToConnectedSystem <bool>]
    [-InboundOutOfScopeAction <string>] [-OutboundDeprovisionAction <string>]
    [-EnforceState <bool>] [-ChangeReason <string>] [-PreviewActivityId <guid>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`Id`	`int`	Yes (ById, Enable, Disable sets)		The ID of the Synchronisation Rule to modify. Accepts pipeline input.
`InputObject`	`PSCustomObject`	Yes (ByInputObject set)		A Synchronisation Rule object from `Get-JIMSyncRule`. Accepts pipeline input.
`Name`	`string`	No		New display name for the Synchronisation Rule
`Description`	`string`	No		New description of what the Synchronisation Rule is for. Pass `$null` (or an empty string) to clear it. Maximum 1000 characters.
`Enable`	`switch`	Yes (Enable set)		Enables the Synchronisation Rule
`Disable`	`switch`	Yes (Disable set)		Disables the Synchronisation Rule
`ProjectToMetaverse`	`bool`	No		Controls whether the rule projects new Metaverse Objects
`ProvisionToConnectedSystem`	`bool`	No		Controls whether the rule provisions new Connected System Objects
`InboundOutOfScopeAction`	`string`	No		Import rules: action when a CSO falls out of the rule's scope. `Disconnect` breaks the CSO to MVO join; `RemainJoined` keeps the join and stops further Attribute Flow
`OutboundDeprovisionAction`	`string`	No		Export rules: action when an MVO falls out of the rule's scope or is deleted. `Disconnect` leaves the CSO untouched in the target system; `Delete` queues a delete so the CSO is removed from the target
`EnforceState`	`bool`	No		Enables drift detection: re-asserts the rule's expected attribute values when the target system has drifted from them
`ChangeReason`	`string`	No		Optional reason ("commit message") recorded with this change and shown in the configuration change history. Maximum 2000 characters.
`PreviewActivityId`	`guid`	No		The Configuration Change Preview this change was made after reading, as returned by `New-JIMConfigurationChangePreview -SyncRuleId`. Recorded on the change's Activity so "previewed, then applied" is auditable.
`PassThru`	`switch`	No	`$false`	Returns the updated Synchronisation Rule object

Output¶

With -PassThru, returns the updated Synchronisation Rule object. Without it, returns nothing.

ShouldProcess impact level: Medium.

Examples¶

Rename a Synchronisation Rule

Set-JIMSyncRule -Id 5 -Name "AD User Import (Production)"

Set or update a Synchronisation Rule's description

Set-JIMSyncRule -Id 5 -Description "Imports production user accounts from Active Directory"

Clear a Synchronisation Rule's description

Set-JIMSyncRule -Id 5 -Description $null

Enable a Synchronisation Rule

Set-JIMSyncRule -Id 5 -Enable

Disable a Synchronisation Rule

Set-JIMSyncRule -Id 5 -Disable

Pipeline: disable all Synchronisation Rules for a Connected System

Get-JIMSyncRule -ConnectedSystemName "HR System" | Set-JIMSyncRule -Disable

Enable projection on an existing import rule

Set-JIMSyncRule -Id 5 -ProjectToMetaverse $true -PassThru

Preview, then set, the Deprovisioning Action on an export rule

$preview = New-JIMConfigurationChangePreview -SyncRuleId 5 -OutboundDeprovisionAction Delete -Wait
Set-JIMSyncRule -Id 5 -OutboundDeprovisionAction Delete -EnforceState $true -PreviewActivityId $preview.ActivityId

Disable a rule and record why (shown in the change history)

Set-JIMSyncRule -Id 12 -Disable -ChangeReason "Pausing during HR cutover (CHG0098)"

Remove-JIMSyncRule¶

Deletes a Synchronisation Rule and all associated configuration, including attribute mappings, scoping criteria, and matching rules.

Syntax¶

# By ID (default)
Remove-JIMSyncRule -Id <int> [-Force] [-ChangeReason <string>] [-PassThru]

# By input object
Remove-JIMSyncRule -InputObject <PSCustomObject> [-Force] [-ChangeReason <string>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`Id`	`int`	Yes (ById set)		The ID of the Synchronisation Rule to delete. Accepts pipeline input.
`InputObject`	`PSCustomObject`	Yes (ByInputObject set)		A Synchronisation Rule object from `Get-JIMSyncRule`. Accepts pipeline input.
`Force`	`switch`	No	`$false`	Suppresses the confirmation prompt
`ChangeReason`	`string`	No		Optional reason ("commit message") recorded with the deletion and shown in the configuration change history. Maximum 2000 characters.
`PassThru`	`switch`	No	`$false`	Returns the deleted Synchronisation Rule object before removal

Output¶

With -PassThru, returns the Synchronisation Rule object that was deleted. Without it, returns nothing.

ShouldProcess impact level: High. Prompts for confirmation unless -Force is specified.

Examples¶

Delete a Synchronisation Rule with confirmation

Remove-JIMSyncRule -Id 5

Force delete without confirmation

Remove-JIMSyncRule -Id 5 -Force

Pipeline: remove all disabled Synchronisation Rules for a Connected System

Get-JIMSyncRule -ConnectedSystemName "Legacy HR" |
    Where-Object { -not $_.Enabled } |
    Remove-JIMSyncRule -Force

Attribute Mappings¶

Configure how attributes flow between Connected System Objects and Metaverse Objects within a Synchronisation Rule. Mappings can use direct attribute-to-Attribute Flows or expression-based transformations.

Get-JIMSyncRuleMapping¶

Retrieves Attribute Flow mappings for a Synchronisation Rule. Returns all mappings for the rule, or a specific mapping by ID.

Syntax¶

# All mappings for a Synchronisation Rule
Get-JIMSyncRuleMapping -SyncRuleId <int>

# Specific mapping
Get-JIMSyncRuleMapping -SyncRuleId <int> -MappingId <int>

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input. Alias: `Id`.
`MappingId`	`int`	No		The ID of a specific mapping to retrieve

Output¶

Returns one or more mapping objects representing Attribute Flow Rules. Each mapping includes the source attribute(s) or expression, the target attribute, and the flow direction.

Examples¶

List all mappings for a Synchronisation Rule

Get-JIMSyncRuleMapping -SyncRuleId 5

Get a specific mapping

Get-JIMSyncRuleMapping -SyncRuleId 5 -MappingId 12

Pipeline from Get-JIMSyncRule

Get-JIMSyncRule -Id 5 | Get-JIMSyncRuleMapping

New-JIMSyncRuleMapping¶

Creates a new Attribute Flow mapping on a Synchronisation Rule. Mappings can be direct Attribute Flows (one or more source attributes to a target) or expression-based transformations.

Syntax¶

# Import: direct Attribute Flow (CS -> MV)
New-JIMSyncRuleMapping -SyncRuleId <int>
    -SourceConnectedSystemAttributeId <int[]>
    -TargetMetaverseAttributeId <int>

# Import: expression-based flow (CS -> MV)
New-JIMSyncRuleMapping -SyncRuleId <int>
    -Expression <string>
    -TargetMetaverseAttributeId <int>

# Export: direct Attribute Flow (MV -> CS)
New-JIMSyncRuleMapping -SyncRuleId <int>
    -SourceMetaverseAttributeId <int[]>
    -TargetConnectedSystemAttributeId <int>

# Export: expression-based flow (MV -> CS)
New-JIMSyncRuleMapping -SyncRuleId <int>
    -Expression <string>
    -TargetConnectedSystemAttributeId <int>

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input. Alias: `Id`.
`TargetMetaverseAttributeId`	`int`	Yes (Import sets)		The metaverse attribute to write to (import direction)
`TargetConnectedSystemAttributeId`	`int`	Yes (Export sets)		The Connected System attribute to write to (export direction)
`SourceConnectedSystemAttributeId`	`int[]`	Yes (ImportAttribute set)		One or more Connected System attribute IDs to read from
`SourceMetaverseAttributeId`	`int[]`	Yes (ExportAttribute set)		One or more metaverse attribute IDs to read from
`Expression`	`string`	Yes (ImportExpression, ExportExpression sets)		A DynamicExpresso expression. Use `mv["Name"]` for metaverse attributes and `cs["Name"]` for Connected System attributes.
`MissingInputBehaviour`	`string`	No (ImportExpression, ExportExpression sets)	`EvaluateAnyway`	What to do when an attribute the expression reads has no value on the object: `EvaluateAnyway`, `ContributeNoValue`, `FailMapping` or `FailObject`. See Missing Input Behaviour.

Output¶

Returns the created mapping object.

ShouldProcess impact level: Medium.

Notes¶

When multiple source attributes are provided, they are automatically ordered by position (0, 1, 2, and so on).
Expressions use DynamicExpresso syntax with mv["AttributeName"] and cs["AttributeName"] accessors.
MissingInputBehaviour applies to expression mappings only; a direct Attribute Flow has no inputs to be missing. Omit it to leave the mapping on EvaluateAnyway, which is how every mapping created before this parameter existed behaves.

Examples¶

Direct import: map CS 'givenName' to MV 'firstName'

New-JIMSyncRuleMapping -SyncRuleId 5 `
    -SourceConnectedSystemAttributeId 10 `
    -TargetMetaverseAttributeId 3

Expression import: concatenate CS attributes into MV 'displayName'

New-JIMSyncRuleMapping -SyncRuleId 5 `
    -Expression 'cs["givenName"] + " " + cs["sn"]' `
    -TargetMetaverseAttributeId 7

Expression export: refuse to build a Distinguished Name from a missing value

New-JIMSyncRuleMapping -SyncRuleId 8 `
    -Expression '"CN=" + EscapeDN(mv["Display Name"]) + ",OU=Users,DC=company,DC=local"' `
    -TargetConnectedSystemAttributeId 30 `
    -MissingInputBehaviour FailObject

Direct export: map MV 'email' to CS 'mail'

New-JIMSyncRuleMapping -SyncRuleId 8 `
    -SourceMetaverseAttributeId 15 `
    -TargetConnectedSystemAttributeId 22

Multiple source attributes for import

New-JIMSyncRuleMapping -SyncRuleId 5 `
    -SourceConnectedSystemAttributeId 10, 11 `
    -TargetMetaverseAttributeId 7

Set-JIMSyncRuleMapping¶

Changes the settings on an existing Attribute Flow, leaving what it reads and writes alone. Only the parameters you supply are changed.

Syntax¶

# By IDs
Set-JIMSyncRuleMapping -SyncRuleId <int>
    -MappingId <int>
    [-Expression <string>]
    [-MissingInputBehaviour <string>]
    [-NullIsValue <bool>]
    [-InboundValueProcessing <string>]
    [-CaseNormalisation <string>]
    [-InitialExportOnly <bool>]
    [-Enabled <bool>]
    [-PassThru]

# From the pipeline
Get-JIMSyncRuleMapping -SyncRuleId <int> | Set-JIMSyncRuleMapping -SyncRuleId <int> [-MissingInputBehaviour <string>]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule the mapping belongs to
`MappingId`	`int`	Yes (ById set)		The ID of the mapping to update. Accepts pipeline input by property name. Alias: `Id`
`InputObject`	`PSCustomObject`	Yes (ByInputObject set)		A mapping object from the pipeline
`Expression`	`string`	No		Replaces the mapping's expression. Expression mappings only
`MissingInputBehaviour`	`string`	No		`EvaluateAnyway`, `ContributeNoValue`, `FailMapping` or `FailObject`. Expression mappings only. See Missing Input Behaviour
`NullIsValue`	`bool`	No		Whether a contribution of no value is authoritative. Import mappings only
`InboundValueProcessing`	`string`	No		Comma-separated flag names, e.g. `'TreatWhitespaceAsNoValue, TrimWhitespace'`. Import mappings only
`CaseNormalisation`	`string`	No		`None`, `Upper`, `Lower` or `Title`. Import mappings only
`InitialExportOnly`	`bool`	No		Whether the mapping flows only during the initial provisioning export. Export mappings only
`Enabled`	`bool`	No		Enables or disables the mapping. A disabled mapping is skipped by synchronisation in both directions; re-enabling clears any recorded disabled reason. Import and export mappings alike
`PassThru`	`switch`	No	`$false`	Returns the updated mapping

Output¶

Nothing by default; the updated mapping when -PassThru is supplied.

ShouldProcess impact level: Medium.

Notes¶

What a mapping targets, and whether its source is an attribute or an expression, cannot be changed here. Those revalidate against attribute types and plurality, and for an import mapping they reopen its place in the Attribute Priority order, so they remain a Remove-JIMSyncRuleMapping followed by a New-JIMSyncRuleMapping.
A setting that does not apply to the mapping is refused rather than ignored: -NullIsValue on an export mapping, -InitialExportOnly on an import mapping, or any expression setting on a direct Attribute Flow all return an error.
A call naming no setting is refused too, rather than reported as a successful update.
Attribute Priority is ordered through its own endpoint and is not settable here.

Examples¶

Refuse to export a Distinguished Name built around a missing value

Set-JIMSyncRuleMapping -SyncRuleId 2 -MappingId 15 -MissingInputBehaviour FailObject

Rewrite an import mapping's expression

Set-JIMSyncRuleMapping -SyncRuleId 1 -MappingId 8 -Expression 'Lower(cs["mail"])' -PassThru

Disable one Attribute Flow without touching the Synchronisation Rule

Set-JIMSyncRuleMapping -SyncRuleId 1 -MappingId 8 -Enabled $false

Report every expression mapping on a Rule that meets a missing input

Get-JIMSyncRuleMapping -SyncRuleId 1 |
    Where-Object { $_.sourceType -eq 'ExpressionMapping' } |
    Set-JIMSyncRuleMapping -SyncRuleId 1 -MissingInputBehaviour FailMapping

Remove-JIMSyncRuleMapping¶

Deletes an Attribute Flow mapping from a Synchronisation Rule.

Syntax¶

# By IDs
Remove-JIMSyncRuleMapping -SyncRuleId <int> -MappingId <int> [-Force]

# By input object
Remove-JIMSyncRuleMapping -SyncRuleId <int> -InputObject <PSCustomObject> [-Force]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule
`MappingId`	`int`	Yes (by ID)		The ID of the mapping to delete. Accepts pipeline input. Alias: `Id`.
`InputObject`	`PSCustomObject`	Yes (by object)		A mapping object from `Get-JIMSyncRuleMapping`. Accepts pipeline input.
`Force`	`switch`	No	`$false`	Suppresses the confirmation prompt

Output¶

None.

ShouldProcess impact level: High. Prompts for confirmation unless -Force is specified.

Examples¶

Delete a specific mapping

Remove-JIMSyncRuleMapping -SyncRuleId 5 -MappingId 12

Force delete without confirmation

Remove-JIMSyncRuleMapping -SyncRuleId 5 -MappingId 12 -Force

Pipeline: remove all mappings for a Synchronisation Rule

Get-JIMSyncRuleMapping -SyncRuleId 5 |
    Remove-JIMSyncRuleMapping -SyncRuleId 5 -Force

Scoping Criteria¶

Scoping criteria control which objects a Synchronisation Rule processes. Criteria are organised into groups that evaluate as All (AND) or Any (OR), and groups can be nested for complex logic.

Get-JIMScopingCriteria¶

Retrieves scoping criteria groups and their nested criteria for a Synchronisation Rule.

Syntax¶

# All groups for a Synchronisation Rule
Get-JIMScopingCriteria -SyncRuleId <int>

# Specific group
Get-JIMScopingCriteria -SyncRuleId <int> -GroupId <int>

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input. Alias: `Id`.
`GroupId`	`int`	No		The ID of a specific scoping criteria group to retrieve

Output¶

Returns one or more scoping criteria group objects. Each group contains its type (All or Any), position, and nested criteria or child groups.

Examples¶

List all scoping criteria for a Synchronisation Rule

Get-JIMScopingCriteria -SyncRuleId 5

Get a specific group

Get-JIMScopingCriteria -SyncRuleId 5 -GroupId 2

Pipeline from Get-JIMSyncRule

Get-JIMSyncRule -Id 5 | Get-JIMScopingCriteria

New-JIMScopingCriteriaGroup¶

Creates a new scoping criteria group on a Synchronisation Rule. Groups evaluate their contents using either All (AND) or Any (OR) logic. Groups can be nested within other groups to build complex scoping expressions.

Syntax¶

New-JIMScopingCriteriaGroup -SyncRuleId <int>
    [-ParentGroupId <int>] [-Type <string>] [-Position <int>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input.
`ParentGroupId`	`int`	No		The ID of a parent group to nest this group within
`Type`	`string`	No	`All`	Evaluation logic for the group. Valid values: `All` (AND), `Any` (OR).
`Position`	`int`	No	`0`	Display order position within the parent context
`PassThru`	`switch`	No	`$false`	Returns the created group object

Output¶

With -PassThru, returns the created scoping criteria group object. Without it, returns nothing.

ShouldProcess impact level: Medium.

Examples¶

Create a top-level AND group

New-JIMScopingCriteriaGroup -SyncRuleId 5 -Type All -PassThru

Create a nested OR group inside an existing group

New-JIMScopingCriteriaGroup -SyncRuleId 5 -ParentGroupId 2 -Type Any

Create an AND group at a specific position

New-JIMScopingCriteriaGroup -SyncRuleId 5 -Type All -Position 1

Set-JIMScopingCriteriaGroup¶

Modifies an existing scoping criteria group; for example, changing the evaluation type or position.

Syntax¶

Set-JIMScopingCriteriaGroup -SyncRuleId <int> -GroupId <int>
    [-Type <string>] [-Position <int>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input.
`GroupId`	`int`	Yes		The ID of the group to modify. Accepts pipeline input. Alias: `Id`.
`Type`	`string`	No		Evaluation logic. Valid values: `All` (AND), `Any` (OR).
`Position`	`int`	No		Display order position
`PassThru`	`switch`	No	`$false`	Returns the updated group object

Output¶

With -PassThru, returns the updated scoping criteria group object. Without it, returns nothing.

ShouldProcess impact level: Medium.

Examples¶

Change a group from AND to OR

Set-JIMScopingCriteriaGroup -SyncRuleId 5 -GroupId 2 -Type Any

Reorder a group

Set-JIMScopingCriteriaGroup -SyncRuleId 5 -GroupId 2 -Position 3

Remove-JIMScopingCriteriaGroup¶

Deletes a scoping criteria group and all of its nested criteria and child groups.

Syntax¶

Remove-JIMScopingCriteriaGroup -SyncRuleId <int> -GroupId <int>

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input.
`GroupId`	`int`	Yes		The ID of the group to delete. Accepts pipeline input. Alias: `Id`.

Output¶

None.

ShouldProcess impact level: High. Prompts for confirmation.

Notes¶

Deleting a group also deletes all nested criteria and child groups within it. This operation is not reversible.

Examples¶

Delete a scoping criteria group

Remove-JIMScopingCriteriaGroup -SyncRuleId 5 -GroupId 2

New-JIMScopingCriterion¶

Adds an individual scoping criterion to a group. Each criterion compares an attribute value against a specified constant. Import rules use Connected System attributes; export rules use metaverse attributes.

Syntax¶

# By metaverse attribute ID
New-JIMScopingCriterion -SyncRuleId <int> -GroupId <int>
    -MetaverseAttributeId <int> -ComparisonType <string>
    [-StringValue <string>] [-IntValue <int>] [-LongValue <long>] [-DecimalValue <decimal>] [-DateTimeValue <datetime>]
    [-BoolValue <bool>] [-GuidValue <guid>] [-CaseSensitive <bool>]
    [-ValueMode <string>] [-RelativeCount <int>] [-RelativeUnit <string>] [-RelativeDirection <string>] [-PassThru]

# By metaverse attribute name
New-JIMScopingCriterion -SyncRuleId <int> -GroupId <int>
    -MetaverseAttributeName <string> -ComparisonType <string>
    [-StringValue <string>] [-IntValue <int>] [-LongValue <long>] [-DecimalValue <decimal>] [-DateTimeValue <datetime>]
    [-BoolValue <bool>] [-GuidValue <guid>] [-CaseSensitive <bool>]
    [-ValueMode <string>] [-RelativeCount <int>] [-RelativeUnit <string>] [-RelativeDirection <string>] [-PassThru]

# By Connected System attribute ID
New-JIMScopingCriterion -SyncRuleId <int> -GroupId <int>
    -ConnectedSystemAttributeId <int> -ComparisonType <string>
    [-StringValue <string>] [-IntValue <int>] [-LongValue <long>] [-DecimalValue <decimal>] [-DateTimeValue <datetime>]
    [-BoolValue <bool>] [-GuidValue <guid>] [-CaseSensitive <bool>]
    [-ValueMode <string>] [-RelativeCount <int>] [-RelativeUnit <string>] [-RelativeDirection <string>] [-PassThru]

# By Connected System attribute name
New-JIMScopingCriterion -SyncRuleId <int> -GroupId <int>
    -ConnectedSystemAttributeName <string> -ComparisonType <string>
    [-StringValue <string>] [-IntValue <int>] [-LongValue <long>] [-DecimalValue <decimal>] [-DateTimeValue <datetime>]
    [-BoolValue <bool>] [-GuidValue <guid>] [-CaseSensitive <bool>]
    [-ValueMode <string>] [-RelativeCount <int>] [-RelativeUnit <string>] [-RelativeDirection <string>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule
`GroupId`	`int`	Yes		The ID of the scoping criteria group to add this criterion to
`MetaverseAttributeId`	`int`	Yes (ByMvId set)		The metaverse attribute ID to evaluate (export rules only)
`MetaverseAttributeName`	`string`	Yes (ByMvName set)		The metaverse attribute name to evaluate; auto-resolves to ID (export rules only)
`ConnectedSystemAttributeId`	`int`	Yes (ByCsId set)		The Connected System attribute ID to evaluate (import rules only)
`ConnectedSystemAttributeName`	`string`	Yes (ByCsName set)		The Connected System attribute name to evaluate; auto-resolves to ID (import rules only)
`ComparisonType`	`string`	Yes		The comparison operator. Valid values: `Equals`, `NotEquals`, `StartsWith`, `NotStartsWith`, `EndsWith`, `NotEndsWith`, `Contains`, `NotContains`, `LessThan`, `LessThanOrEquals`, `GreaterThan`, `GreaterThanOrEquals`.
`StringValue`	`string`	No		String value to compare against
`IntValue`	`int`	No		Integer value to compare against (`Number` attributes)
`LongValue`	`long`	No		64-bit integer value to compare against (`LongNumber` attributes)
`DecimalValue`	`decimal`	No		Decimal value to compare against (`Decimal` attributes)
`DateTimeValue`	`datetime`	No		Date/time value to compare against (ISO 8601 format)
`BoolValue`	`bool`	No		Boolean value to compare against
`GuidValue`	`guid`	No		GUID value to compare against
`CaseSensitive`	`bool`	No	`$false`	If `$true`, string comparisons are case-sensitive. Only meaningful with `StringValue`.
`ValueMode`	`string`	No	`Absolute`	For Date/Time attributes: `Absolute` (use `DateTimeValue`) or `Relative` (compare against a date relative to now).
`RelativeCount`	`int`	No		Relative offset count, zero or positive (with `ValueMode Relative`).
`RelativeUnit`	`string`	No		Relative offset unit: `Hours`, `Days`, `Weeks`, `Months`, `Years` (with `ValueMode Relative`).
`RelativeDirection`	`string`	No		Relative offset direction: `Ago` or `FromNow` (with `ValueMode Relative`).
`PassThru`	`switch`	No	`$false`	Returns the created criterion object

Output¶

With -PassThru, returns the created scoping criterion object. Without it, returns nothing.

ShouldProcess impact level: Medium.

Notes¶

Export rules only support metaverse attributes. Import rules only support Connected System attributes.
Exactly one comparison value parameter should be provided; the correct parameter depends on the attribute's data type.
For a Date/Time attribute, set -ValueMode Relative with -RelativeCount/-RelativeUnit/-RelativeDirection to compare against a date resolved relative to now (re-evaluated each run); this is mutually exclusive with -DateTimeValue. See relative dates.

Examples¶

Import scope: only process users where objectClass equals 'user'

New-JIMScopingCriterion -SyncRuleId 5 -GroupId 2 `
    -ConnectedSystemAttributeName "objectClass" `
    -ComparisonType Equals `
    -StringValue "user"

Import scope: employee ID greater than 1000

New-JIMScopingCriterion -SyncRuleId 5 -GroupId 2 `
    -ConnectedSystemAttributeId 14 `
    -ComparisonType GreaterThan `
    -IntValue 1000

Export scope: only export active metaverse persons

New-JIMScopingCriterion -SyncRuleId 8 -GroupId 3 `
    -MetaverseAttributeName "accountEnabled" `
    -ComparisonType Equals `
    -BoolValue $true

Import scope: department starts with 'Engineering'

New-JIMScopingCriterion -SyncRuleId 5 -GroupId 2 `
    -ConnectedSystemAttributeName "department" `
    -ComparisonType StartsWith `
    -StringValue "Engineering"

Export scope: modified after a specific date

New-JIMScopingCriterion -SyncRuleId 8 -GroupId 3 `
    -MetaverseAttributeId 20 `
    -ComparisonType GreaterThanOrEquals `
    -DateTimeValue "2025-01-01T00:00:00Z"

Export scope: terminated within the last year (relative date)

New-JIMScopingCriterion -SyncRuleId 8 -GroupId 3 `
    -MetaverseAttributeName "Employee End Date" `
    -ComparisonType GreaterThanOrEquals `
    -ValueMode Relative -RelativeCount 364 -RelativeUnit Days -RelativeDirection Ago

Set-JIMScopingCriterion¶

Updates an existing scoping criterion (a full replacement of its attribute, operator and value). Takes the same parameters as New-JIMScopingCriterion plus -CriterionId, including the relative-date parameters for Date/Time attributes.

Syntax¶

Set-JIMScopingCriterion -SyncRuleId <int> -GroupId <int> -CriterionId <int>
    (-MetaverseAttributeId <int> | -MetaverseAttributeName <string> | -ConnectedSystemAttributeId <int> | -ConnectedSystemAttributeName <string>)
    -ComparisonType <string>
    [-StringValue <string>] [-IntValue <int>] [-LongValue <long>] [-DecimalValue <decimal>] [-DateTimeValue <datetime>]
    [-BoolValue <bool>] [-GuidValue <guid>] [-CaseSensitive <bool>]
    [-ValueMode <string>] [-RelativeCount <int>] [-RelativeUnit <string>] [-RelativeDirection <string>]
    [-PassThru]

Examples¶

Change a criterion to a relative date (on or before 7 days from now)

Set-JIMScopingCriterion -SyncRuleId 8 -GroupId 3 -CriterionId 12 `
    -MetaverseAttributeName "AccountExpiry" `
    -ComparisonType LessThanOrEquals `
    -ValueMode Relative -RelativeCount 7 -RelativeUnit Days -RelativeDirection FromNow

ShouldProcess impact level: Medium.

Remove-JIMScopingCriterion¶

Deletes a single scoping criterion from a group.

Syntax¶

Remove-JIMScopingCriterion -SyncRuleId <int> -GroupId <int> -CriterionId <int>

Parameters¶

Name	Type	Required	Description
`SyncRuleId`	`int`	Yes	The ID of the Synchronisation Rule
`GroupId`	`int`	Yes	The ID of the scoping criteria group
`CriterionId`	`int`	Yes	The ID of the criterion to delete. Alias: `Id`.

Output¶

None.

ShouldProcess impact level: High. Prompts for confirmation.

Examples¶

Delete a scoping criterion

Remove-JIMScopingCriterion -SyncRuleId 5 -GroupId 2 -CriterionId 7

Object Matching Rules¶

Matching rules determine how JIM links Connected System Objects to Metaverse Objects during synchronisation. JIM supports two matching modes:

Per-object-type (simple): matching rules are defined at the Connected System level and apply to all Synchronisation Rules for a given object type. This is the default mode.
Per-Synchronisation-Rule (advanced): each Synchronisation Rule has its own independent matching rules, allowing different Synchronisation Rules to use different join criteria.

Use Switch-JIMMatchingMode to change between modes. The current mode determines which set of cmdlets to use.

Switch-JIMMatchingMode¶

Switches a Connected System between per-object-type (simple) and per-Synchronisation-Rule (advanced) matching modes. Existing matching rules are migrated automatically during the switch.

Syntax¶

Switch-JIMMatchingMode -ConnectedSystemId <int> -Mode <string> [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes		The ID of the Connected System. Accepts pipeline input.
`Mode`	`string`	Yes		Target matching mode. Valid values: `ConnectedSystem` (simple, per-object-type), `SyncRule` (advanced, per-Synchronisation-Rule).
`PassThru`	`switch`	No	`$false`	Returns the updated Connected System Object

Output¶

With -PassThru, returns the Connected System Object reflecting the new mode. Without it, returns nothing.

ShouldProcess impact level: High. Prompts for confirmation.

Notes¶

ConnectedSystem mode defines matching rules at the object type level; all Synchronisation Rules for that object type share the same matching configuration.
SyncRule mode defines matching rules on each Synchronisation Rule independently, providing fine-grained control.
When switching modes, existing rules are migrated automatically. Review the migrated rules after switching to confirm they are correct.

Examples¶

Switch to advanced per-Synchronisation-Rule matching

Switch-JIMMatchingMode -ConnectedSystemId 1 -Mode SyncRule

Switch back to simple per-object-type matching

Switch-JIMMatchingMode -ConnectedSystemId 1 -Mode ConnectedSystem

Per-Object-Type Matching Rules¶

These cmdlets manage matching rules in simple (per-object-type) mode, where rules are defined at the Connected System level.

Get-JIMMatchingRule¶

Retrieves matching rules for a Connected System.

Syntax¶

# By object type
Get-JIMMatchingRule -ConnectedSystemId <int> -ObjectTypeId <int>

# By rule ID
Get-JIMMatchingRule -ConnectedSystemId <int> -Id <int>

Parameters¶

Name	Type	Required	Description
`ConnectedSystemId`	`int`	Yes	The ID of the Connected System. Accepts pipeline input.
`ObjectTypeId`	`int`	Yes (ByObjectType set)	The object type ID to retrieve matching rules for
`Id`	`int`	Yes (ById set)	The ID of a specific matching rule to retrieve

Output¶

Returns one or more matching rule objects containing source/target attribute mappings, order, and case sensitivity settings.

Examples¶

List matching rules for a Connected System Object Type

Get-JIMMatchingRule -ConnectedSystemId 1 -ObjectTypeId 3

Get a specific matching rule

Get-JIMMatchingRule -ConnectedSystemId 1 -Id 5

New-JIMMatchingRule¶

Creates a new matching rule for a Connected System Object Type. The source is a Connected System attribute, matched against the rule's target metaverse attribute.

Syntax¶

New-JIMMatchingRule -ConnectedSystemId <int> -ObjectTypeId <int>
    -MetaverseObjectTypeId <int> -SourceAttributeId <int>
    -TargetMetaverseAttributeId <int> [-Order <int>]
    [-CaseSensitive <bool>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes		The ID of the Connected System
`ObjectTypeId`	`int`	Yes		The Connected System Object Type ID
`MetaverseObjectTypeId`	`int`	Yes		The Metaverse Object Type ID to match against
`SourceAttributeId`	`int`	Yes		The Connected System attribute ID to use as the match source
`TargetMetaverseAttributeId`	`int`	Yes		The metaverse attribute ID to match against
`Order`	`int`	No		Evaluation order; lower numbers are evaluated first
`CaseSensitive`	`bool`	No	`$false`	Whether the match comparison is case-sensitive
`PassThru`	`switch`	No	`$false`	Returns the created matching rule object

Examples¶

Match CS employeeId to MV employeeId

New-JIMMatchingRule -ConnectedSystemId 1 -ObjectTypeId 3 `
    -MetaverseObjectTypeId 1 `
    -SourceAttributeId 10 `
    -TargetMetaverseAttributeId 5 `
    -PassThru

Case-sensitive match on email

New-JIMMatchingRule -ConnectedSystemId 1 -ObjectTypeId 3 `
    -MetaverseObjectTypeId 1 `
    -SourceAttributeId 12 `
    -TargetMetaverseAttributeId 8 `
    -CaseSensitive $true

Set-JIMMatchingRule¶

Modifies an existing per-object-type matching rule. Setting a source attribute replaces all existing source attributes on the rule.

Syntax¶

Set-JIMMatchingRule -ConnectedSystemId <int> -Id <int>
    [-Order <int>] [-MetaverseObjectTypeId <int>]
    [-TargetMetaverseAttributeId <int>] [-SourceAttributeId <int>]
    [-CaseSensitive <bool>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes		The ID of the Connected System
`Id`	`int`	Yes		The ID of the matching rule to modify
`Order`	`int`	No		New evaluation order
`MetaverseObjectTypeId`	`int`	No		New Metaverse Object Type ID
`TargetMetaverseAttributeId`	`int`	No		New target metaverse attribute ID
`SourceAttributeId`	`int`	No		New Connected System source attribute ID
`CaseSensitive`	`bool`	No		Whether the match comparison is case-sensitive
`PassThru`	`switch`	No	`$false`	Returns the updated matching rule object

Notes¶

Setting SourceAttributeId replaces all existing source attributes on the rule.

Examples¶

Change the evaluation order

Set-JIMMatchingRule -ConnectedSystemId 1 -Id 5 -Order 2

Enable case-sensitive matching

Set-JIMMatchingRule -ConnectedSystemId 1 -Id 5 -CaseSensitive $true

Remove-JIMMatchingRule¶

Deletes a per-object-type matching rule.

Syntax¶

Remove-JIMMatchingRule -ConnectedSystemId <int> -Id <int> [-Force]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes		The ID of the Connected System
`Id`	`int`	Yes		The ID of the matching rule to delete
`Force`	`switch`	No	`$false`	Suppresses the confirmation prompt

Output¶

None.

ShouldProcess impact level: High. Prompts for confirmation unless -Force is specified.

Examples¶

Delete a matching rule

Remove-JIMMatchingRule -ConnectedSystemId 1 -Id 5

Force delete without confirmation

Remove-JIMMatchingRule -ConnectedSystemId 1 -Id 5 -Force

Per-Synchronisation-Rule Matching Rules¶

These cmdlets manage matching rules in advanced (per-Synchronisation-Rule) mode, where each Synchronisation Rule defines its own matching configuration independently.

Get-JIMSyncRuleMatchingRule¶

Retrieves matching rules for a specific Synchronisation Rule.

Syntax¶

# All matching rules for a Synchronisation Rule
Get-JIMSyncRuleMatchingRule -SyncRuleId <int>

# Specific matching rule
Get-JIMSyncRuleMatchingRule -SyncRuleId <int> -Id <int>

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule. Accepts pipeline input.
`Id`	`int`	No		The ID of a specific matching rule to retrieve

Output¶

Returns one or more matching rule objects.

Examples¶

List matching rules for a Synchronisation Rule

Get-JIMSyncRuleMatchingRule -SyncRuleId 5

Get a specific matching rule

Get-JIMSyncRuleMatchingRule -SyncRuleId 5 -Id 3

New-JIMSyncRuleMatchingRule¶

Creates a new matching rule on a specific Synchronisation Rule. The Metaverse Object Type is derived automatically from the Synchronisation Rule configuration.

Syntax¶

New-JIMSyncRuleMatchingRule -SyncRuleId <int>
    -SourceAttributeId <int> -TargetMetaverseAttributeId <int>
    [-Order <int>] [-CaseSensitive <bool>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule
`SourceAttributeId`	`int`	Yes		The Connected System attribute ID to use as the match source
`TargetMetaverseAttributeId`	`int`	Yes		The metaverse attribute ID to match against
`Order`	`int`	No		Evaluation order; lower numbers are evaluated first
`CaseSensitive`	`bool`	No	`$false`	Whether the match comparison is case-sensitive
`PassThru`	`switch`	No	`$false`	Returns the created matching rule object

Notes¶

The Metaverse Object Type is derived from the Synchronisation Rule, so you do not need to specify it explicitly.

Examples¶

Match CS employeeId to MV employeeId on a Synchronisation Rule

New-JIMSyncRuleMatchingRule -SyncRuleId 5 `
    -SourceAttributeId 10 `
    -TargetMetaverseAttributeId 5 `
    -PassThru

Case-sensitive email match

New-JIMSyncRuleMatchingRule -SyncRuleId 5 `
    -SourceAttributeId 12 `
    -TargetMetaverseAttributeId 8 `
    -CaseSensitive $true

Set-JIMSyncRuleMatchingRule¶

Modifies an existing per-Synchronisation-Rule matching rule.

Syntax¶

Set-JIMSyncRuleMatchingRule -SyncRuleId <int> -Id <int>
    [-Order <int>] [-TargetMetaverseAttributeId <int>]
    [-SourceAttributeId <int>]
    [-CaseSensitive <bool>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule
`Id`	`int`	Yes		The ID of the matching rule to modify
`Order`	`int`	No		New evaluation order
`TargetMetaverseAttributeId`	`int`	No		New target metaverse attribute ID
`SourceAttributeId`	`int`	No		New Connected System source attribute ID
`CaseSensitive`	`bool`	No		Whether the match comparison is case-sensitive
`PassThru`	`switch`	No	`$false`	Returns the updated matching rule object

Examples¶

Change evaluation order

Set-JIMSyncRuleMatchingRule -SyncRuleId 5 -Id 3 -Order 1

Update target attribute and enable case sensitivity

Set-JIMSyncRuleMatchingRule -SyncRuleId 5 -Id 3 `
    -TargetMetaverseAttributeId 9 `
    -CaseSensitive $true

Remove-JIMSyncRuleMatchingRule¶

Deletes a per-Synchronisation-Rule matching rule.

Syntax¶

Remove-JIMSyncRuleMatchingRule -SyncRuleId <int> -Id <int> [-Force]

Parameters¶

Name	Type	Required	Default	Description
`SyncRuleId`	`int`	Yes		The ID of the Synchronisation Rule
`Id`	`int`	Yes		The ID of the matching rule to delete
`Force`	`switch`	No	`$false`	Suppresses the confirmation prompt

Output¶

None.

ShouldProcess impact level: High. Prompts for confirmation unless -Force is specified.

Examples¶

Delete a Synchronisation Rule matching rule

Remove-JIMSyncRuleMatchingRule -SyncRuleId 5 -Id 3

Force delete without confirmation

Remove-JIMSyncRuleMatchingRule -SyncRuleId 5 -Id 3 -Force

Initial Password¶

Get-JIMSyncRuleInitialPassword¶

Gets whether JIM sets an initial password on the accounts a Synchronisation Rule provisions, how it generates one, and which accounts are waiting on a person.

No password value is ever returned. A generated password is produced at the moment it is set and stored nowhere; where the rule uses one password for every account, that password is stored encrypted and is write-only, so all that comes back is that one is set and when it last changed.

Syntax¶

Get-JIMSyncRuleInitialPassword -Id <int>
Get-JIMSyncRule -Id <int> | Get-JIMSyncRuleInitialPassword

Output¶

Property	Type	Description
`enabled`	`bool`	Whether JIM sets an initial password on accounts this rule provisions
`source`	`string`	`Discovered` (follow the Connected System's policy), `Custom`, or `Static` (one password for every account)
`customPolicy`	`object`	The generator settings used when `source` is `Custom`
`expiryBehaviour`	`string`	What happens to the password once it is set
`enableAccount`	`bool`	Whether the account is enabled once the password is set
`staticPasswordSet`	`bool`	Whether one password is stored for every account this rule provisions
`staticPasswordSetAt`	`datetime`	When that password last changed, or null where none is set
`parkedAccountCount`	`int`	Accounts waiting on a change to these settings
`expiredAccountCount`	`int`	Accounts never given an initial password within its time to live
`parkedReasons`	`array`	One entry per distinct refusal, biggest group first

Each entry in parkedReasons carries targetMessage (what the target said, unaltered), failureReason, accountCount and firstSeenAt.

The two counts are never summed. Correcting these settings and saving releases the parked accounts, and does nothing at all for the expired ones; those need a password set by other means.

Examples¶

See what a target objected to

(Get-JIMSyncRuleInitialPassword -Id 5).parkedReasons |
    Format-Table accountCount, targetMessage -AutoSize

Find every rule with initial password work waiting

Get-JIMSyncRule -All | ForEach-Object {
    $p = Get-JIMSyncRuleInitialPassword -Id $_.id
    if ($p.parkedAccountCount -or $p.expiredAccountCount) {
        [PSCustomObject]@{ Rule = $_.name; Parked = $p.parkedAccountCount; Expired = $p.expiredAccountCount }
    }
}

Find shared initial passwords nobody has changed for 90 days

Get-JIMSyncRule -All | ForEach-Object {
    $p = Get-JIMSyncRuleInitialPassword -Id $_.id
    if ($p.staticPasswordSet -and $p.staticPasswordSetAt -lt (Get-Date).AddDays(-90)) {
        [PSCustomObject]@{ Rule = $_.name; LastChanged = $p.staticPasswordSetAt }
    }
}

Set-JIMSyncRuleInitialPassword¶

Replaces the configuration above. Saving a change that alters what would be delivered releases every account parked against the rule, and they are attempted again on the Connected System's next export run; saving a change that would deliver the same password in the same way releases nothing.

Only what you supply changes, with one exception: the generator settings travel as a set, so supplying any one of them sends the whole policy.

One password for every account¶

-Source Static with -StaticPassword 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: every account the rule provisions shares that password until each person changes it. See Passwords before using it.

-StaticPassword takes a SecureString, so the password does not sit in your session's command history in clear text. It is write-only: JIM encrypts it and never returns it. Omit it to leave the stored password as it is, which is what makes changing another setting safe.

Set one password for every account this rule provisions

$password = Read-Host -AsSecureString "Initial password for every new account"
Set-JIMSyncRuleInitialPassword -Id 5 -Enable -Source Static -StaticPassword $password

Rotate the shared password after a leaver

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