Public/Training/Get-KB4TrainingEnrollment.ps1
|
<# .SYNOPSIS Gets KnowBe4 training enrollments. .DESCRIPTION Retrieves training enrollments from the KnowBe4 Reporting API. Without Id, the command returns a page of enrollments or all enrollments when All is specified. With Id, the command returns a specific enrollment. Normal output unwraps KnowBe4 page data and returns enrollment objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER Id The KnowBe4 training enrollment ID. This parameter also accepts the alias EnrollmentId. .PARAMETER StorePurchaseId Filters enrollments by training store purchase ID. .PARAMETER CampaignId Filters enrollments by training campaign ID. .PARAMETER UserId Filters enrollments by KnowBe4 user ID. .PARAMETER ExcludeArchivedUsers Excludes archived users from list responses. .PARAMETER IncludeCampaignId Includes campaign ID values in responses where KnowBe4 supports this option. .PARAMETER IncludeStorePurchaseId Includes store purchase ID values in list responses. .PARAMETER IncludeEmployeeNumber Includes employee number values in list responses. .PARAMETER All Retrieves all available pages. .PARAMETER PageSize The number of enrollments to request per page. Valid range is 1 through 500. .PARAMETER Page The page number to request when using page-based pagination. .PARAMETER Cursor The cursor value to request. Use 'true' to start cursor pagination manually. .PARAMETER UsePagePagination Uses page-based pagination when All is specified. Cursor pagination is preferred. .PARAMETER Raw Returns the full PSKB4Reporting response envelope instead of unwrapped enrollment objects. .EXAMPLE Get-KB4TrainingEnrollment -CampaignId 12345 -PageSize 100 Gets the first page of enrollments for training campaign 12345. .EXAMPLE Get-KB4TrainingEnrollment -UserId 98765 -All Gets all training enrollments for user 98765. .EXAMPLE Get-KB4TrainingEnrollment -Id 555 -IncludeCampaignId Gets a specific training enrollment and requests the campaign ID field. .OUTPUTS PSCustomObject. #> function Get-KB4TrainingEnrollment { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('EnrollmentId')] [int] $Id, [Parameter(ParameterSetName = 'List')] [int] $StorePurchaseId, [Parameter(ParameterSetName = 'List')] [int] $CampaignId, [Parameter(ParameterSetName = 'List')] [int] $UserId, [Parameter(ParameterSetName = 'List')] [switch] $ExcludeArchivedUsers, [Parameter()] [switch] $IncludeCampaignId, [Parameter(ParameterSetName = 'List')] [switch] $IncludeStorePurchaseId, [Parameter(ParameterSetName = 'List')] [switch] $IncludeEmployeeNumber, [Parameter(ParameterSetName = 'List')] [switch] $All, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, 500)] [int] $PageSize = 100, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, [int]::MaxValue)] [int] $Page, [Parameter(ParameterSetName = 'List')] [string] $Cursor, [Parameter(ParameterSetName = 'List')] [switch] $UsePagePagination, [Parameter()] [switch] $Raw ) process { if ($PSCmdlet.ParameterSetName -eq 'ById') { $query = @{} if ($IncludeCampaignId) { $query['include_campaign_id'] = $true } $path = '/v1/training/enrollments/{0}' -f (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path -Query $query) -Raw:$Raw } $query = @{} Add-KB4QueryParameter -Query $query -Name 'store_purchase_id' -Value $StorePurchaseId Add-KB4QueryParameter -Query $query -Name 'campaign_id' -Value $CampaignId Add-KB4QueryParameter -Query $query -Name 'user_id' -Value $UserId if ($ExcludeArchivedUsers) { $query['exclude_archived_users'] = $true } if ($IncludeCampaignId) { $query['include_campaign_id'] = $true } if ($IncludeStorePurchaseId) { $query['include_store_purchase_id'] = $true } if ($IncludeEmployeeNumber) { $query['include_employee_number'] = $true } $pagedParameters = @{ Path = '/v1/training/enrollments' Query = $query All = $All PageSize = $PageSize UsePagePagination = $UsePagePagination Raw = $Raw } if ($PSBoundParameters.ContainsKey('Page')) { $pagedParameters['Page'] = $Page } if ($PSBoundParameters.ContainsKey('Cursor')) { $pagedParameters['Cursor'] = $Cursor } Invoke-KB4PagedRequest @pagedParameters } } |