Run Profiles¶

Run Profile cmdlets manage and execute synchronisation Run Profiles on Connected Systems. A Run Profile defines a specific operation type (import, synchronisation, or export) that can be executed against a Connected System. Use these cmdlets to list, create, modify, remove, and trigger Run Profiles.

Get-JIMRunProfile¶

Retrieves one or more Run Profiles for a Connected System, identified either by Connected System ID or Connected System name, with an optional name filter.

Syntax¶

# By Connected System ID (default)
Get-JIMRunProfile -ConnectedSystemId <int> [-Name <string>]

# By Connected System name
Get-JIMRunProfile -ConnectedSystemName <string> [-Name <string>]

Parameters¶

Name	Type	Required	Description
`ConnectedSystemId`	`int`	Yes (ById set)	ID of the Connected System. Alias: `Id`. Accepts pipeline input by property name.
`ConnectedSystemName`	`string`	Yes (ByName set)	Name of the Connected System. Must be an exact match.
`Name`	`string`	No	Filter Run Profiles by name. Supports wildcards (e.g., `"Full*"`).

Output¶

Returns one or more PSCustomObject instances representing Run Profiles, each containing Id, Name, ConnectedSystemId, RunType, PageSize, PartitionName, FilePath, VerifyImportContentHashes, and Safeguards (an object with MaxCreates, MaxUpdates, MaxDeletes, MaxDetectedDeletions and MaxDetectedDeletionsPercent; each is $null when that limit is not set). See Run Profiles > Safeguards.

Examples¶

List all Run Profiles for a Connected System

Get-JIMRunProfile -ConnectedSystemId 1

Filter by name

Get-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import"

Filter by name with wildcards

Get-JIMRunProfile -ConnectedSystemName "HR System" -Name "Delta*"

Pipeline from Get-JIMConnectedSystem

Get-JIMConnectedSystem -Name "Active Directory" | Get-JIMRunProfile

New-JIMRunProfile¶

Creates a new Run Profile on a Connected System. Supports ShouldProcess; use -WhatIf or -Confirm to preview or confirm the operation.

Syntax¶

# By Connected System ID (default)
New-JIMRunProfile -ConnectedSystemId <int> -Name <string> -RunType <string> [-PageSize <int>] [-PartitionId <int>] [-FilePath <string>] [-VerifyImportContentHashes] [-MaxCreates <int>] [-MaxUpdates <int>] [-MaxDeletes <int>] [-MaxDetectedDeletions <int>] [-MaxDetectedDeletionsPercent <int>] [-PassThru] [-WhatIf] [-Confirm]

# By Connected System name
New-JIMRunProfile -ConnectedSystemName <string> -Name <string> -RunType <string> [-PageSize <int>] [-PartitionId <int>] [-FilePath <string>] [-VerifyImportContentHashes] [-MaxCreates <int>] [-MaxUpdates <int>] [-MaxDeletes <int>] [-MaxDetectedDeletions <int>] [-MaxDetectedDeletionsPercent <int>] [-PassThru] [-WhatIf] [-Confirm]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes (ById set)		ID of the Connected System to create the Run Profile on. Alias: `Id`. Accepts pipeline input by property name.
`ConnectedSystemName`	`string`	Yes (ByName set)		Name of the Connected System to create the Run Profile on.
`Name`	`string`	Yes (Position 0)		Display name for the new Run Profile.
`RunType`	`string`	Yes		Operation type. Valid values: `FullImport`, `DeltaImport`, `FullSynchronisation`, `DeltaSynchronisation`, `Export`.
`PageSize`	`int`	No	`100`	How many items to process in one batch.
`PartitionId`	`int`	No		Optional partition to scope this Run Profile to. If omitted, the Run Profile applies to the default partition.
`FilePath`	`string`	No		Optional file path for file-based connectors.
`VerifyImportContentHashes`	`switch`	No	`$false`	Enables Verification Mode. Only valid when `-RunType` is `FullImport`; the API rejects it otherwise. Runs the honest attribute diff on every object instead of skipping unchanged objects by content hash.
`MaxCreates`	`int` (nullable)	No	No limit	Run Profile Safeguards: the most creates that may be pending for a single Export run to attempt any of them. If more are pending than this when the run starts, none are attempted; `0` refuses creates outright. Only valid when `-RunType` is `Export`. See Run Profiles > Safeguards.
`MaxUpdates`	`int` (nullable)	No	No limit	Run Profile Safeguards: the most updates that may be pending for a single Export run to attempt any of them. Same rules as `-MaxCreates`.
`MaxDeletes`	`int` (nullable)	No	No limit	Run Profile Safeguards: the most deletes that may be pending for a single Export run to attempt any of them. Same rules as `-MaxCreates`.
`MaxDetectedDeletions`	`int` (nullable)	No	No limit	Run Profile Safeguards: the most Connected System Objects a single Full Import run may newly mark as deleted. If more would be newly marked than this, none are marked; `0` refuses to mark anything as deleted. Only valid when `-RunType` is `FullImport`. See Run Profiles > Safeguards.
`MaxDetectedDeletionsPercent`	`int` (nullable)	No	No limit	Run Profile Safeguards: the most Connected System Objects a single Full Import run may newly mark as deleted, as a share (0 to 100) of the Connected System Objects in the run's scope when it starts. Same rules as `-MaxDetectedDeletions`.
`PassThru`	`switch`	No	`$false`	Returns the created Run Profile object to the pipeline.

Output¶

By default, no output. When -PassThru is specified, returns the created Run Profile object.

Examples¶

Create a full import Run Profile

New-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import" -RunType FullImport

Create a Run Profile by Connected System name

New-JIMRunProfile -ConnectedSystemName "Active Directory" -Name "Delta Synchronisation" -RunType DeltaSynchronisation

Create and capture the result

$rp = New-JIMRunProfile -ConnectedSystemId 1 -Name "Export" -RunType Export -PassThru
$rp.Id

Create a Run Profile with a custom page size

New-JIMRunProfile -ConnectedSystemId 1 -Name "Delta Import" -RunType DeltaImport -PageSize 500 -PassThru

Create a partition-scoped Run Profile

New-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import (UK)" -RunType FullImport -PartitionId 3

Create a Run Profile for a file-based connector

Get-JIMConnectedSystem -Name "CSV*" | ForEach-Object {
    New-JIMRunProfile -ConnectedSystemId $_.Id -Name "Full Import" -RunType FullImport -FilePath "C:\Data\import.csv"
}

Create a Full Import Run Profile with Verification Mode enabled

New-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import (Verified)" -RunType FullImport -VerifyImportContentHashes

Preview with WhatIf

New-JIMRunProfile -ConnectedSystemId 1 -Name "Delta Import" -RunType DeltaImport -WhatIf

Create an Export Run Profile with a delete limit

New-JIMRunProfile -ConnectedSystemId 1 -Name "Export" -RunType Export -MaxDeletes 100

Create a Full Import Run Profile with a deletion detection share limit

New-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import" -RunType FullImport -MaxDetectedDeletionsPercent 10

Set-JIMRunProfile¶

Modifies an existing Run Profile. Supports ShouldProcess; use -WhatIf or -Confirm to preview or confirm the operation.

Syntax¶

# By Connected System ID (default)
Set-JIMRunProfile -ConnectedSystemId <int> -RunProfileId <int> [-Name <string>] [-PageSize <int>] [-PartitionId <int>] [-FilePath <string>] [-VerifyImportContentHashes <bool>] [-MaxCreates <int>] [-MaxUpdates <int>] [-MaxDeletes <int>] [-MaxDetectedDeletions <int>] [-MaxDetectedDeletionsPercent <int>] [-PassThru] [-WhatIf] [-Confirm]

# By Connected System name
Set-JIMRunProfile -ConnectedSystemName <string> -RunProfileId <int> [-Name <string>] [-PageSize <int>] [-PartitionId <int>] [-FilePath <string>] [-VerifyImportContentHashes <bool>] [-MaxCreates <int>] [-MaxUpdates <int>] [-MaxDeletes <int>] [-MaxDetectedDeletions <int>] [-MaxDetectedDeletionsPercent <int>] [-PassThru] [-WhatIf] [-Confirm]

# By input object
Set-JIMRunProfile -InputObject <PSCustomObject> [-Name <string>] [-PageSize <int>] [-PartitionId <int>] [-FilePath <string>] [-VerifyImportContentHashes <bool>] [-MaxCreates <int>] [-MaxUpdates <int>] [-MaxDeletes <int>] [-MaxDetectedDeletions <int>] [-MaxDetectedDeletionsPercent <int>] [-PassThru] [-WhatIf] [-Confirm]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes (ById set)		ID of the Connected System the Run Profile belongs to.
`ConnectedSystemName`	`string`	Yes (ByName set)		Name of the Connected System the Run Profile belongs to. Must be an exact match.
`RunProfileId`	`int`	Yes (ById, ByName sets)		ID of the Run Profile to update.
`InputObject`	`PSCustomObject`	Yes (ByInputObject set)		A Run Profile object, typically from `Get-JIMRunProfile`. Accepts pipeline input.
`Name`	`string`	No		New display name for the Run Profile.
`PageSize`	`int`	No		New page size for the Run Profile. Omit to leave unchanged.
`PartitionId`	`int`	No		New partition ID to scope the Run Profile to.
`FilePath`	`string`	No		New file path for file-based connectors. Omit to leave unchanged.
`VerifyImportContentHashes`	`bool`	No		Enables or disables Verification Mode. Pass `$true` to enable, `$false` to disable; omit to leave unchanged. Only valid on a Full Import Run Profile; the API rejects `$true` otherwise.
`MaxCreates`	`int` (nullable)	No		Run Profile Safeguards: sets the most creates that may be pending for a single Export run to attempt any of them; if more are pending, the run attempts none of them. Pass a number to set it, `0` to refuse creates outright, or `$null` to clear the limit; omit the parameter to leave it unchanged. Only valid on an Export Run Profile. Setting any one of `-MaxCreates`, `-MaxUpdates`, `-MaxDeletes`, `-MaxDetectedDeletions` or `-MaxDetectedDeletionsPercent` preserves the other four exactly. See Run Profiles > Safeguards.
`MaxUpdates`	`int` (nullable)	No		Run Profile Safeguards: sets the most updates that may be pending for a single Export run to attempt any of them. Same rules as `-MaxCreates`.
`MaxDeletes`	`int` (nullable)	No		Run Profile Safeguards: sets the most deletes that may be pending for a single Export run to attempt any of them. Same rules as `-MaxCreates`.
`MaxDetectedDeletions`	`int` (nullable)	No		Run Profile Safeguards: sets the most Connected System Objects a single Full Import run may newly mark as deleted; if more would be newly marked, none are marked. Pass a number to set it, `0` to refuse to mark anything as deleted, or `$null` to clear the limit; omit the parameter to leave it unchanged. Only valid on a Full Import Run Profile. See Run Profiles > Safeguards.
`MaxDetectedDeletionsPercent`	`int` (nullable)	No		Run Profile Safeguards: sets the most Connected System Objects a single Full Import run may newly mark as deleted, as a share (0 to 100) of the Connected System Objects in the run's scope when it starts. Same rules as `-MaxDetectedDeletions`.
`PassThru`	`switch`	No	`$false`	Returns the updated Run Profile object to the pipeline.

Output¶

By default, no output. When -PassThru is specified, returns the updated Run Profile object.

Examples¶

Rename a Run Profile

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Name "Full Import (Production)"

Update by Connected System name

Set-JIMRunProfile -ConnectedSystemName "Contoso AD" -RunProfileId 1 -PageSize 500

Update via pipeline

Get-JIMRunProfile -ConnectedSystemId 1 -Name "Full Import" | Set-JIMRunProfile -Name "Full Import (Renamed)" -PassThru

Change partition assignment

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -PartitionId 5

Update a file-based connector's Run Profile

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 7 -FilePath "C:\Data\import-v2.csv"

Enable Verification Mode temporarily

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -VerifyImportContentHashes $true

Disable Verification Mode again

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -VerifyImportContentHashes $false

Preview changes with WhatIf

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Name "New Name" -WhatIf

Set a delete limit on an Export Run Profile

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 12 -MaxDeletes 100

Clear a limit, leaving the other two unchanged

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 12 -MaxDeletes $null

Set a deletion detection share limit on a Full Import Run Profile

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 7 -MaxDetectedDeletionsPercent 10

Clear both deletion detection limits

Set-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 7 -MaxDetectedDeletions $null -MaxDetectedDeletionsPercent $null

Remove-JIMRunProfile¶

Deletes a Run Profile. This is a destructive operation with high impact; by default, PowerShell will prompt for confirmation. Use -Force to suppress the confirmation prompt. Supports ShouldProcess.

Syntax¶

# By Connected System ID (default)
Remove-JIMRunProfile -ConnectedSystemId <int> -RunProfileId <int> [-Force] [-PassThru] [-WhatIf] [-Confirm]

# By Connected System name
Remove-JIMRunProfile -ConnectedSystemName <string> -RunProfileId <int> [-Force] [-PassThru] [-WhatIf] [-Confirm]

# By input object
Remove-JIMRunProfile -InputObject <PSCustomObject> [-Force] [-PassThru] [-WhatIf] [-Confirm]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes (ById set)		ID of the Connected System the Run Profile belongs to.
`ConnectedSystemName`	`string`	Yes (ByName set)		Name of the Connected System the Run Profile belongs to. Must be an exact match.
`RunProfileId`	`int`	Yes (ById, ByName sets)		ID of the Run Profile to delete.
`InputObject`	`PSCustomObject`	Yes (ByInputObject set)		A Run Profile object, typically from `Get-JIMRunProfile`. Accepts pipeline input.
`Force`	`switch`	No	`$false`	Suppresses the confirmation prompt.
`PassThru`	`switch`	No	`$false`	Returns the deleted Run Profile object to the pipeline.

Output¶

By default, no output. When -PassThru is specified, returns the Run Profile object that was deleted.

Examples¶

Delete a Run Profile by ID

Remove-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42

Delete without confirmation

Remove-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Force

Delete using Connected System name

Remove-JIMRunProfile -ConnectedSystemName "Contoso AD" -RunProfileId 42 -Force

Delete via pipeline

Get-JIMRunProfile -ConnectedSystemId 1 -Name "Test Profile" | Remove-JIMRunProfile -Force

Delete all Run Profiles for a Connected System

Get-JIMRunProfile -ConnectedSystemId 1 | Remove-JIMRunProfile -Force

Capture before deleting

$deleted = Remove-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Force -PassThru
Write-Host "Removed Run Profile: $($deleted.Name)"

Start-JIMRunProfile¶

Queues a Run Profile for execution on the JIM worker service. The operation is asynchronous by default; use -Wait to block until execution completes.

Every parameter set requires both a Connected System identifier (-ConnectedSystemId or -ConnectedSystemName) and a Run Profile identifier (-RunProfileId or -RunProfileName); a Run Profile identifier alone does not resolve to a parameter set.

Syntax¶

# By Connected System ID and Run Profile ID (default)
Start-JIMRunProfile -ConnectedSystemId <int> -RunProfileId <int> [-Wait] [-Timeout <int>] [-PreviewActivityId <guid>] [-PassThru]

# By Connected System name and Run Profile name
Start-JIMRunProfile -ConnectedSystemName <string> -RunProfileName <string> [-Wait] [-Timeout <int>] [-PreviewActivityId <guid>] [-PassThru]

# By Connected System ID and Run Profile name
Start-JIMRunProfile -ConnectedSystemId <int> -RunProfileName <string> [-Wait] [-Timeout <int>] [-PreviewActivityId <guid>] [-PassThru]

# By Connected System name and Run Profile ID
Start-JIMRunProfile -ConnectedSystemName <string> -RunProfileId <int> [-Wait] [-Timeout <int>] [-PreviewActivityId <guid>] [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`ConnectedSystemId`	`int`	Yes (ById, ByIdAndName sets)		ID of the Connected System that owns the Run Profile. Accepts pipeline input by property name.
`ConnectedSystemName`	`string`	Yes (ByName, ByNameAndId sets)		Name of the Connected System that owns the Run Profile. Must be an exact match.
`RunProfileId`	`int`	Yes (ById, ByNameAndId sets)		ID of the Run Profile to execute. Alias: `Id`. Accepts pipeline input by property name (ById set).
`RunProfileName`	`string`	Yes (ByName, ByIdAndName sets)		Name of the Run Profile to execute. Must be an exact match.
`Wait`	`switch`	No	`$false`	Blocks until execution completes, displaying live progress: current phase, object counts, throughput and estimated time remaining. Polls the lightweight Activity progress endpoint every 2 seconds.
`Timeout`	`int`	No		Maximum number of seconds to wait when `-Wait` is specified. If exceeded, an error is thrown containing the Activity ID for manual follow-up.
`PreviewActivityId`	`guid`	No		The Full Synchronisation preview read before starting this run, as returned by `New-JIMConfigurationChangePreview -FullSynchronisation`. Recorded on the run's Activity, which then shows that the run was informed by it. Only a Full Synchronisation Run Profile can cite one, and it must be a completed Full Synchronisation preview of the same Connected System; anything else is refused and the run is not queued.
`PassThru`	`switch`	No	`$false`	Returns the execution response object to the pipeline.

Output¶

By default, writes status messages to the host. When -PassThru is specified, returns a PSCustomObject with the following properties:

Property	Type	Description
`ActivityId`	`Guid`	ID of the Activity created for tracking the execution
`TaskId`	`Guid`	ID of the queued worker task
`Message`	`string`	Message describing the result of queuing the execution
`Warnings`	`string[]`	Any warning messages about the execution (e.g. partition validation warnings). Empty if none

Examples¶

Start a Run Profile by ID

Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42

Start by name

Start-JIMRunProfile -ConnectedSystemName "Active Directory" -RunProfileName "Full Import"

Start and wait for completion

Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Wait

Start with a timeout

Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Wait -Timeout 300

Preview a Full Synchronisation, then run it and record the preview

$preview = New-JIMConfigurationChangePreview -ConnectedSystemId 1 -FullSynchronisation -Wait
$preview.ImpactCounts | Format-Table TransitionType, ObjectCount
if ($preview.IsComplete) {
    Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileName "Full Synchronisation" -PreviewActivityId $preview.ActivityId -Wait
}

Capture execution details

$result = Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -PassThru
Write-Host "Activity ID: $($result.ActivityId)"
Write-Host "Task ID: $($result.TaskId)"
if ($result.Warnings.Count -gt 0) {
    Write-Warning "Warnings: $($result.Warnings -join '; ')"
}

Pipeline: start all full imports for a Connected System

Get-JIMRunProfile -ConnectedSystemId 1 |
    Where-Object { $_.RunType -eq "FullImport" } |
    Start-JIMRunProfile -Wait

Automation with error handling

try {
    Start-JIMRunProfile -ConnectedSystemId 1 -RunProfileId 42 -Wait -Timeout 600 -PassThru -ErrorAction Stop
} catch {
    Write-Error "Run Profile execution failed or timed out: $_"
}

Notes¶

The Run Profile is queued as an asynchronous task on the JIM worker service. Without -Wait, the cmdlet returns immediately after the task is queued.
When -Wait is specified, the cmdlet polls the lightweight Activity progress endpoint (/activities/{id}/progress) every 2 seconds and displays a progress bar with the current phase, object counts, throughput and estimated time remaining. If authentication tokens expire during polling, the cmdlet retries up to 3 times before failing.
If -Timeout is exceeded, the cmdlet throws a terminating error that includes the Activity ID, allowing you to check progress manually via Get-JIMActivity or the JIM web interface.
Run Profiles that are already executing will be rejected by the server; you do not need to check for running profiles before calling this cmdlet.

Run Profiles¶

Get-JIMRunProfile¶

Syntax¶

Parameters¶

Output¶

Examples¶

New-JIMRunProfile¶

Syntax¶

Parameters¶

Output¶

Examples¶

Set-JIMRunProfile¶

Syntax¶

Parameters¶

Output¶

Examples¶

Remove-JIMRunProfile¶

Syntax¶

Parameters¶

Output¶

Examples¶

Start-JIMRunProfile¶

Syntax¶

Parameters¶

Output¶

Examples¶

Notes¶

See also¶