Public/History/Get-JIMConnectedSystemObjectChangeValue.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Get-JIMConnectedSystemObjectChangeValue { <# .SYNOPSIS Gets one attribute's value changes on a Connected System Object change. .DESCRIPTION Gets the value changes one Connected System Object change recorded for one attribute, a page at a time, in the order the change recorded them. Get-JIMConnectedSystemObjectChangeHistory and Get-JIMActivityExecutionItem return each changed attribute's first ten value changes and its total in valueChangeTotal; a change to a large group can carry one value change per member, and this gets all of them. The change is found by its ID, so a change to an object since deleted can still be read. .PARAMETER ChangeId The ID of the change, as Get-JIMConnectedSystemObjectChangeHistory returns it. .PARAMETER AttributeName The name of the attribute whose value changes to get, matched case-insensitively. .PARAMETER Search Returns only the value changes whose value contains this text, including a referenced object's name. .PARAMETER Page The page to get. .PARAMETER PageSize How many value changes a page holds. .PARAMETER All Fetches every page instead of one. Stops after 1000 pages with a warning; -Force fetches the rest. .PARAMETER Force With -All, fetches every page, past the 1000-page limit. .OUTPUTS The attribute's value changes. .EXAMPLE Get-JIMConnectedSystemObjectChangeValue -ChangeId "a1b2c3d4-..." -AttributeName "member" Gets the first page of member value changes the change recorded. .EXAMPLE Get-JIMConnectedSystemObjectChangeValue -ChangeId "a1b2c3d4-..." -AttributeName "member" -Search "Engineering" Gets the member value changes whose value, or referenced object's name, contains "Engineering". .EXAMPLE Get-JIMConnectedSystemObjectChangeValue -ChangeId "a1b2c3d4-..." -AttributeName "member" -All | Where-Object { $_.valueChangeType -eq 'Remove' } Gets every member value change across all pages, keeping the removals. .LINK Get-JIMConnectedSystemObjectChangeHistory Get-JIMActivityExecutionItem #> [CmdletBinding(DefaultParameterSetName = 'Page')] [OutputType('JIM.CsoValueChangeDto')] param( [Parameter(Mandatory, ParameterSetName = 'Page')] [Parameter(Mandatory, ParameterSetName = 'All')] [guid]$ChangeId, [Parameter(Mandatory, ParameterSetName = 'Page')] [Parameter(Mandatory, ParameterSetName = 'All')] [ValidateNotNullOrEmpty()] [string]$AttributeName, [Parameter(ParameterSetName = 'Page')] [Parameter(ParameterSetName = 'All')] [string]$Search, [Parameter(ParameterSetName = 'Page')] [ValidateRange(1, [int]::MaxValue)] [int]$Page = 1, [Parameter(ParameterSetName = 'Page')] [Parameter(ParameterSetName = 'All')] [ValidateRange(1, 100)] [int]$PageSize = 50, [Parameter(Mandatory, ParameterSetName = 'All')] [switch]$All, [Parameter(ParameterSetName = 'All')] [switch]$Force ) process { if (-not $script:JIMConnection) { Write-Error "You are not connected to JIM. Run Connect-JIM -Url <your JIM URL> to authenticate, then try again." return } $baseEndpoint = "/api/v1/history/connected-system-object-changes/$ChangeId/attributes/$([System.Uri]::EscapeDataString($AttributeName))/values" $pageRequest = { param($p) $endpoint = "$($baseEndpoint)?page=$p&pageSize=$PageSize" if ($Search) { $endpoint += "&search=$([System.Uri]::EscapeDataString($Search))" } Invoke-JIMApi -Endpoint $endpoint } switch ($PSCmdlet.ParameterSetName) { 'Page' { Write-Verbose "Getting '$AttributeName' value changes on Connected System Object change $ChangeId (Page: $Page, PageSize: $PageSize)" $response = & $pageRequest $Page foreach ($item in $response.items) { $item } } 'All' { Write-Verbose "Getting all '$AttributeName' value changes on Connected System Object change $ChangeId" Invoke-JIMPagedFetch -PageRequest $pageRequest -CmdletName 'Get-JIMConnectedSystemObjectChangeValue' -PageSize $PageSize -Force:$Force ` -ItemNoun 'value changes' -NarrowHint 'filter with -Search' } } } } |