Public/Activities/Get-JIMActivityChildren.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Get-JIMActivityChildren { <# .SYNOPSIS Gets child Activities for a parent Activity in JIM. .DESCRIPTION Retrieves child activities that were spawned by a parent activity. For example, a schedule execution activity may have child activities for each individual run profile step. Returns a paginated summary of child Activities, newest-first creation order ascending. Use -All to page automatically and return every child Activity. The API returns a paginated response envelope, but this cmdlet unwraps it internally and still emits one object per child Activity to the pipeline, so existing scripts that pipe its output are unaffected by the change to a paginated response shape. .PARAMETER Id The parent Activity. .PARAMETER All Returns every child Activity, fetching page after page. Stops with a warning after 1,000 pages unless -Force is given. .PARAMETER Force With -All, fetches every page however many there are, up to the API's limit of 1,000,000 rows. .PARAMETER Page The page of child Activities to return. .PARAMETER PageSize How many child Activities per page. .OUTPUTS Each child Activity's header. .EXAMPLE Get-JIMActivityChildren -Id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" Gets the first page of child activities for the specified parent activity. .EXAMPLE Get-JIMActivityChildren -Id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" -All Returns every child activity for the specified parent activity, paginating automatically. .EXAMPLE Get-JIMActivityChildren -Id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" -All -Force Returns every child activity, overriding the 1000-page safety cap for a very large parent Activity. .EXAMPLE Get-JIMActivity -Id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | Get-JIMActivityChildren Gets child activities for a parent activity via pipeline. .LINK Get-JIMActivity Get-JIMActivityStats #> [CmdletBinding(DefaultParameterSetName = 'Page')] [OutputType('JIM.ActivityHeader')] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [guid]$Id, [Parameter(Mandatory, ParameterSetName = 'All')] [switch]$All, [Parameter(ParameterSetName = 'All')] [switch]$Force, [Parameter(ParameterSetName = 'Page')] [ValidateRange(1, [int]::MaxValue)] [int]$Page = 1, [Parameter(ParameterSetName = 'Page')] [Parameter(ParameterSetName = 'All')] [ValidateRange(1, 100)] [int]$PageSize = 50 ) process { # Check connection first 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 } try { # The shared helper owns the -All loop, the page cap and the warnings (issue #487); a single # page is fetched directly. Both paths unwrap the paginated response envelope so callers keep # receiving one object per child Activity. $pageRequest = { param($p) Write-Verbose "Getting child activities for Activity: $Id (Page: $p, PageSize: $PageSize)" Invoke-JIMApi -Endpoint "/api/v1/activities/$Id/children?page=$p&pageSize=$PageSize" } if ($All) { Invoke-JIMPagedFetch -PageRequest $pageRequest -CmdletName 'Get-JIMActivityChildren' -PageSize $PageSize -Force:$Force ` -ItemNoun 'child activities' } else { $response = & $pageRequest $Page foreach ($item in $response.items) { $item } } } catch { Write-Error "Failed to get child activities: $_" } } } |