Public/Employees/Get-UKGEmployee.ps1
|
function Get-UKGEmployee { <# .SYNOPSIS Gets employee information from the UKG HR Service Delivery API. .DESCRIPTION Retrieves employee data by ID or lists all employees with pagination support. Note: The /employees endpoint (list all) is deprecated. Use Search-UKGEmployee instead. .PARAMETER Id The unique identifier of the employee to retrieve. .PARAMETER ExternalId The external identifier of the employee to retrieve. .PARAMETER All Retrieves all employees (deprecated - use Search-UKGEmployee). .PARAMETER PerPage Number of results per page (1-100, default 25). .PARAMETER Cursor Pagination cursor for retrieving a specific page. .PARAMETER Fields Array of field names to include in the response. .EXAMPLE Get-UKGEmployee -Id "emp123" .EXAMPLE Get-UKGEmployee -ExternalId "EXT001" .EXAMPLE Get-UKGEmployee -All -PerPage 50 .OUTPUTS UKG.Employee or array of UKG.Employee objects. #> [CmdletBinding(DefaultParameterSetName = 'ById')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('EmployeeId')] [string]$Id, [Parameter(Mandatory, ParameterSetName = 'ByExternalId')] [ValidateNotNullOrEmpty()] [string]$ExternalId, [Parameter(ParameterSetName = 'List')] [switch]$All, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, 100)] [int]$PerPage = 25, [Parameter(ParameterSetName = 'List')] [string]$Cursor, [Parameter()] [string[]]$Fields ) begin { # Build query parameters for fields $queryParams = @{} if ($Fields) { $queryParams['fields'] = $Fields -join ',' } } process { switch ($PSCmdlet.ParameterSetName) { 'ById' { $endpoint = "/employees/$Id" $response = Invoke-UKGRequest -Endpoint $endpoint -Method GET -QueryParameters $queryParams if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.Employee') } return $response } 'ByExternalId' { $endpoint = "/employees/by_external_id/$ExternalId" $response = Invoke-UKGRequest -Endpoint $endpoint -Method GET -QueryParameters $queryParams if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.Employee') } return $response } 'List' { Write-Warning "The /employees endpoint is deprecated. Consider using Search-UKGEmployee instead." $queryParams['per_page'] = $PerPage if ($Cursor) { $queryParams['cursor'] = $Cursor } if ($All -and -not $Cursor) { # Retrieve all pages $allEmployees = Get-UKGAllPages -Endpoint '/employees' -Method GET -QueryParameters $queryParams foreach ($emp in $allEmployees) { $emp.PSObject.TypeNames.Insert(0, 'UKG.Employee') } return $allEmployees } else { # Retrieve single page $response = Invoke-UKGRequest -Endpoint '/employees' -Method GET -QueryParameters $queryParams -ReturnHeaders if ($response.Data) { foreach ($emp in $response.Data) { $emp.PSObject.TypeNames.Insert(0, 'UKG.Employee') } # Add pagination info $pagination = Get-UKGNextPage -Headers $response.Headers if ($pagination.NextCursor) { Write-Verbose "Next cursor: $($pagination.NextCursor)" } return $response.Data } } } } } } |