PSUKG

1.0.3

Public/Users/Get-UKGUser.ps1

function Get-UKGUser {
    <#
    .SYNOPSIS
        Gets user information from the UKG HR Service Delivery API.

    .DESCRIPTION
        Retrieves user data by ID or lists all users with pagination support.
        Users are typically HR administrators or system users, not employees.

    .PARAMETER Id
        The unique identifier of the user to retrieve.

    .PARAMETER All
        Retrieves all users.

    .PARAMETER Count
        Returns only the count of users (HEAD request).

    .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-UKGUser -Id "user123"

    .EXAMPLE
        Get-UKGUser -All

    .EXAMPLE
        Get-UKGUser -Count

    .OUTPUTS
        UKG.User or array of UKG.User objects, or count if -Count is specified.
    #>
    [CmdletBinding(DefaultParameterSetName = 'ById')]
    [OutputType([PSCustomObject])]
    param(
        [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [Alias('UserId')]
        [string]$Id,

        [Parameter(ParameterSetName = 'List')]
        [switch]$All,

        [Parameter(Mandatory, ParameterSetName = 'Count')]
        [switch]$Count,

        [Parameter(ParameterSetName = 'List')]
        [ValidateRange(1, 100)]
        [int]$PerPage = 25,

        [Parameter(ParameterSetName = 'List')]
        [string]$Cursor,

        [Parameter()]
        [string[]]$Fields
    )

    begin {
        $queryParams = @{}
        if ($Fields) {
            $queryParams['fields'] = $Fields -join ','
        }
    }

    process {
        switch ($PSCmdlet.ParameterSetName) {
            'ById' {
                $endpoint = "/users/$Id"
                $response = Invoke-UKGRequest -Endpoint $endpoint -Method GET -QueryParameters $queryParams
                if ($response) {
                    $response.PSObject.TypeNames.Insert(0, 'UKG.User')
                }
                return $response
            }

            'Count' {
                $headers = Invoke-UKGRequest -Endpoint '/users' -Method HEAD
                if ($headers.ContainsKey('X-Total-Count')) {
                    return [int]$headers['X-Total-Count']
                }
                return 0
            }

            'List' {
                $queryParams['per_page'] = $PerPage
                if ($Cursor) {
                    $queryParams['cursor'] = $Cursor
                }

                if ($All -and -not $Cursor) {
                    $allUsers = Get-UKGAllPages -Endpoint '/users' -Method GET -QueryParameters $queryParams
                    foreach ($user in $allUsers) {
                        $user.PSObject.TypeNames.Insert(0, 'UKG.User')
                    }
                    return $allUsers
                }
                else {
                    $response = Invoke-UKGRequest -Endpoint '/users' -Method GET -QueryParameters $queryParams -ReturnHeaders
                    if ($response.Data) {
                        foreach ($user in $response.Data) {
                            $user.PSObject.TypeNames.Insert(0, 'UKG.User')
                        }

                        $pagination = Get-UKGNextPage -Headers $response.Headers
                        if ($pagination.NextCursor) {
                            Write-Verbose "Next cursor: $($pagination.NextCursor)"
                        }

                        return $response.Data
                    }
                }
            }
        }
    }
}