History¶

Cmdlets for querying configuration change history, querying deleted objects, and managing change history retention. These cmdlets provide access to the configuration audit trail, the audit trail for deleted objects, and let you control how long change history records are kept.

Get-JIMConfigurationChangeHistory¶

Retrieves the recorded configuration changes for a Synchronisation Rule, Connected System, Schedule, Service Setting, Metaverse Object Type, Metaverse Attribute, Trusted Certificate, API Key, Role, Predefined Search, Connector Definition, Example Data Set, or Example Data Template. Every create, update, and delete is captured as a complete, versioned snapshot carried on its Activity, so you can see exactly what changed, when, and who changed it. Three retrieval modes are supported: a paged summary list (default), a single version with its diff against the previous version (-Version), and a comparison of any two versions (-CompareFrom / -CompareTo). Sensitive values (for example encrypted Connected System settings) are never returned; a changed secret is reported only as changed, never by value. An API Key's history stores only its metadata and Role assignments; the key secret is never returned in any form, not even as a hash. A Role's history covers both its definition and its static membership, so each member add or remove appears as its own version. A Predefined Search's history also covers its criteria groups and criteria: each add, edit, or removal rolls up into a version on the owning search. A Connector Definition's history covers its capabilities, setting definitions, and files, so a capability or setting shipped in an updated connector appears as its own version; a file's contents are fingerprinted by hash, never returned. An Example Data Set's history records only its metadata and value count (never the individual values), and an Example Data Template's history covers its object-type and attribute configuration; a template's data-generation runs are a separate operational activity, not part of its configuration history.

Syntax¶

# Paged summary list (default)
Get-JIMConfigurationChangeHistory -Type <string> -Id <int|guid|string>
    [-Page <int>] [-PageSize <int>]

# Stream every version
Get-JIMConfigurationChangeHistory -Type <string> -Id <int|guid|string> -All [-Force] [-PageSize <int>]

# A single version, with its diff against the previous version
Get-JIMConfigurationChangeHistory -Type <string> -Id <int|guid|string> -Version <int> [-AsDiff] [-Raw]

# Compare any two versions
Get-JIMConfigurationChangeHistory -Type <string> -Id <int|guid|string>
    -CompareFrom <int> -CompareTo <int> [-AsDiff] [-Raw]

Parameters¶

Name	Type	Required	Default	Parameter Set	Description
`Type`	`string`	Yes		All	The configuration object kind. Valid values: `SynchronisationRule`, `ConnectedSystem`, `Schedule`, `ServiceSetting`, `MetaverseObjectType`, `MetaverseAttribute`, `TrustedCertificate`, `ApiKey`, `Role`, `PredefinedSearch`, `ConnectorDefinition`, `ExampleDataSet`, `ExampleDataTemplate`.
`Id`	`int`, `guid` or `string`	Yes		All	The ID of the configuration object: an integer for a Synchronisation Rule, Connected System, Metaverse Object Type, Metaverse Attribute, Role, Predefined Search, Connector Definition, Example Data Set, or Example Data Template; a GUID for a Schedule, Trusted Certificate, or API Key; the dot-notation setting key for a Service Setting. Accepts the `id` property from the pipeline, so a piped object binds automatically.
`Page`	`int`	No	`1`	Page	Page number for the summary list.
`PageSize`	`int`	No	`50`	Page, All	Items per page. Maximum: `100`.
`All`	`switch`	No		All	Automatically paginate through, and return, every change-history entry. Fetches at most 1000 pages and then stops with a warning; use `-Force` to fetch beyond the cap, up to the API's maximum retrieval depth of 1,000,000 rows.
`Force`	`switch`	No		All	Override the `-All` 1000-page ceiling and fetch every page regardless of size. Only valid with `-All`.
`Version`	`int`	Yes		Version	Retrieve a single change by its per-object version number, returning the snapshot and the diff against the previous version.
`CompareFrom`	`int`	Yes		Compare	The earlier version to compare from.
`CompareTo`	`int`	Yes		Compare	The later version to compare to.
`AsDiff`	`switch`	No		Version, Compare	Render the change as a git-style coloured diff (using `$PSStyle`) instead of returning the structured object.
`Raw`	`switch`	No		Version, Compare	Return the underlying structured change object. This is the default; the switch is provided for explicitness.

Output¶

In the summary modes, returns one PSCustomObject per change with Version, Operation, InitiatedByName, When, Reason, and a one-line Summary. With -Version, returns the change detail (metadata, the redacted snapshot, and the diff against the previous version). With -CompareFrom / -CompareTo, returns the structured diff. With -AsDiff, returns the rendered diff as coloured strings.

Examples¶

List the most recent changes for a Synchronisation Rule

Get-JIMConfigurationChangeHistory -Type SynchronisationRule -Id 5

Return every recorded change for a Connected System

Get-JIMConfigurationChangeHistory -Type ConnectedSystem -Id 9 -All

List the recorded changes for a Schedule (GUID-keyed)

Get-JIMSchedule -Name "Nightly Sync" | Get-JIMConfigurationChangeHistory -Type Schedule

Show one version as a git-style coloured diff

Get-JIMConfigurationChangeHistory -Type ConnectedSystem -Id 9 -Version 7 -AsDiff

Pipe a Synchronisation Rule in and show its latest change

Get-JIMSyncRule -Name "HR Inbound" |
    Get-JIMConfigurationChangeHistory -Type SynchronisationRule -Version 7 -AsDiff

Compare two versions

Get-JIMConfigurationChangeHistory -Type SynchronisationRule -Id 5 -CompareFrom 6 -CompareTo 8 -AsDiff

List the recorded changes for a Service Setting (string-keyed)

Get-JIMConfigurationChangeHistory -Type ServiceSetting -Id 'History.RetentionPeriod'

Pipe a Metaverse Attribute in and list its recorded changes

Get-JIMMetaverseAttribute -Name 'Email' | Get-JIMConfigurationChangeHistory -Type MetaverseAttribute

List the recorded changes for a Trusted Certificate (GUID-keyed)

Get-JIMCertificate | Get-JIMConfigurationChangeHistory -Type TrustedCertificate

List the recorded changes for an API Key (GUID-keyed)

Get-JIMApiKey | Get-JIMConfigurationChangeHistory -Type ApiKey

List the recorded changes for a Role (int-keyed), covering its definition and membership

Get-JIMRole -Name "Administrator" | Get-JIMConfigurationChangeHistory -Type Role

List the recorded changes for a Predefined Search (int-keyed), covering the search and its criteria

Get-JIMPredefinedSearch -Uri people | Get-JIMConfigurationChangeHistory -Type PredefinedSearch

List the recorded changes for a Connector Definition (int-keyed), covering its capabilities, settings and files

Get-JIMConfigurationChangeHistory -Type ConnectorDefinition -Id 3

List the recorded changes for an Example Data Set (int-keyed)

Get-JIMConfigurationChangeHistory -Type ExampleDataSet -Id 5

Recording a reason

To attach a reason to a change so it appears in this history, pass -ChangeReason to the write cmdlets: New-JIMSyncRule, Set-JIMSyncRule, Remove-JIMSyncRule, New-JIMConnectedSystem, Set-JIMConnectedSystem, Set-JIMServiceSetting, Reset-JIMServiceSetting, New-JIMMetaverseObjectType, Set-JIMMetaverseObjectType, New-JIMMetaverseAttribute, Set-JIMMetaverseAttribute, Remove-JIMMetaverseAttribute, Add-JIMCertificate, Set-JIMCertificate, Remove-JIMCertificate, New-JIMApiKey, Set-JIMApiKey, Remove-JIMApiKey, Add-JIMRoleMember, Remove-JIMRoleMember, Set-JIMPredefinedSearch, and New-JIMPredefinedSearchCriteriaGroup.

Get-JIMDeletedObject¶

Retrieves deleted objects from the audit trail. Supports filtering by object type, date range, and search terms, with paginated results for efficient browsing of large deletion histories.

Syntax¶

# Get deleted Metaverse Objects (default)
Get-JIMDeletedObject [-ObjectType <string>] [-MetaverseObjectTypeId <int>]
    [-Search <string>] [-FromDate <DateTime>] [-ToDate <DateTime>]
    [-Page <int>] [-PageSize <int>]

# Get deleted Connected System Objects
Get-JIMDeletedObject -ObjectType CSO -ConnectedSystemId <int>
    [-Search <string>] [-FromDate <DateTime>] [-ToDate <DateTime>]
    [-Page <int>] [-PageSize <int>]

Parameters¶

Name	Type	Required	Default	Description
`ObjectType`	`string`	No	`MVO`	Type of deleted object to retrieve. Valid values: `MVO` (Metaverse Objects), `CSO` (Connected System Objects).
`ConnectedSystemId`	`int`	No		Filters deleted CSOs by Connected System. Only applicable when `ObjectType` is `CSO`.
`MetaverseObjectTypeId`	`int`	No		Filters deleted MVOs by Metaverse Object Type. Only applicable when `ObjectType` is `MVO`.
`Search`	`string`	No		Search term to filter results. Searches `ExternalId` for CSOs and `DisplayName` for MVOs.
`FromDate`	`DateTime`	No		Start of the deletion date range (UTC).
`ToDate`	`DateTime`	No		End of the deletion date range (UTC).
`Page`	`int`	No	`1`	Page number for paginated results.
`PageSize`	`int`	No	`50`	Number of items per page. Maximum: `1000`.

Output¶

Returns a PSCustomObject with paginated results containing Items, TotalCount, Page, and PageSize properties. Each item represents a deleted object with its attributes at the time of deletion.

Examples¶

Get all deleted Metaverse Objects

Get-JIMDeletedObject

Get deleted Connected System Objects

Get-JIMDeletedObject -ObjectType CSO

Search deleted MVOs by display name

Get-JIMDeletedObject -Search "John Smith"

Search deleted CSOs by external ID

Get-JIMDeletedObject -ObjectType CSO -Search "CN=jsmith"

Filter by date range

Get-JIMDeletedObject -FromDate "2026-01-01" -ToDate "2026-03-31"

Get deleted CSOs for a specific Connected System

Get-JIMDeletedObject -ObjectType CSO -ConnectedSystemId 5

Paginate through large result sets

Get-JIMDeletedObject -Page 3 -PageSize 100

Get-JIMHistoryCount¶

Gets the count of change history records for a Connected System. Useful for monitoring history growth and planning cleanup operations.

Syntax¶

# By Connected System ID (default)
Get-JIMHistoryCount -ConnectedSystemId <int>

# By Connected System name
Get-JIMHistoryCount -ConnectedSystemName <string>

Parameters¶

Name	Type	Required	Default	Parameter Set	Description
`ConnectedSystemId`	`int`	Yes		ById (default)	ID of the Connected System. Alias: `Id`. Accepts pipeline input.
`ConnectedSystemName`	`string`	Yes		ByName	Name of the Connected System.

Output¶

Returns a PSCustomObject with ConnectedSystemId, ConnectedSystemName, and ChangeRecordCount properties.

Examples¶

Get history count by ID

Get-JIMHistoryCount -ConnectedSystemId 3

Get history count by name

Get-JIMHistoryCount -ConnectedSystemName "Active Directory"

Get history counts for all Connected Systems

Get-JIMConnectedSystem | Get-JIMHistoryCount

Find systems with the most history records

Get-JIMConnectedSystem |
    Get-JIMHistoryCount |
    Sort-Object ChangeRecordCount -Descending |
    Format-Table ConnectedSystemName, ChangeRecordCount

Invoke-JIMHistoryCleanup¶

Manually triggers change history cleanup based on the configured retention policy. Deletes expired CSO changes, MVO changes, and activities older than the configured retention period.

Syntax¶

Invoke-JIMHistoryCleanup [-PassThru]

Parameters¶

Name	Type	Required	Default	Description
`PassThru`	`switch`	No		Returns cleanup statistics instead of producing no output.

Output¶

When PassThru is specified, returns a PSCustomObject with the following properties:

Property	Type	Description
`CsoChangesDeleted`	`int`	Number of Connected System Object change records deleted.
`MvoChangesDeleted`	`int`	Number of Metaverse Object change records deleted.
`ActivitiesDeleted`	`int`	Number of activity records deleted.
`OldestRecordDeleted`	`DateTime`	Timestamp of the oldest record removed.
`NewestRecordDeleted`	`DateTime`	Timestamp of the newest record removed.
`CutoffDate`	`DateTime`	The calculated cutoff date based on retention policy.
`RetentionPeriodDays`	`int`	The configured retention period in days.
`BatchSize`	`int`	Maximum number of records processed per invocation.

Without PassThru, produces no output.

Batch Size Limitation

Each invocation processes up to the configured batch size. For environments with large volumes of expired history, you may need to call this cmdlet multiple times or rely on automatic housekeeping, which runs every 60 seconds. Each cleanup invocation creates an audit activity.

Examples¶

Run a basic cleanup

Invoke-JIMHistoryCleanup

Run cleanup and view statistics

Invoke-JIMHistoryCleanup -PassThru

Batch cleanup loop for large backlogs

do {
    $result = Invoke-JIMHistoryCleanup -PassThru
    $total = $result.CsoChangesDeleted + $result.MvoChangesDeleted + $result.ActivitiesDeleted
    Write-Host "Deleted $total records (cutoff: $($result.CutoffDate))"
} while ($total -gt 0)

History¶

Get-JIMConfigurationChangeHistory¶

Syntax¶

Parameters¶

Output¶

Examples¶

Get-JIMDeletedObject¶

Syntax¶

Parameters¶

Output¶

Examples¶

Get-JIMHistoryCount¶

Syntax¶

Parameters¶

Output¶

Examples¶

Invoke-JIMHistoryCleanup¶

Syntax¶

Parameters¶

Output¶

Examples¶

See also¶