Public/Roles/Get-UKGRole.ps1
|
function Get-UKGRole { <# .SYNOPSIS Gets role information from the UKG HR Service Delivery API. .DESCRIPTION Retrieves role data by ID or lists all roles. .PARAMETER Id The unique identifier of the role to retrieve. .PARAMETER All Retrieves all roles. .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-UKGRole -Id "role123" .EXAMPLE Get-UKGRole -All .OUTPUTS UKG.Role or array of UKG.Role objects. #> [CmdletBinding(DefaultParameterSetName = 'ById')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('RoleId')] [string]$Id, [Parameter(ParameterSetName = 'List')] [switch]$All, [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 = "/roles/$Id" $response = Invoke-UKGRequest -Endpoint $endpoint -Method GET -QueryParameters $queryParams if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.Role') } return $response } 'List' { $queryParams['per_page'] = $PerPage if ($Cursor) { $queryParams['cursor'] = $Cursor } if ($All -and -not $Cursor) { $allRoles = Get-UKGAllPages -Endpoint '/roles' -Method GET -QueryParameters $queryParams foreach ($role in $allRoles) { $role.PSObject.TypeNames.Insert(0, 'UKG.Role') } return $allRoles } else { $response = Invoke-UKGRequest -Endpoint '/roles' -Method GET -QueryParameters $queryParams -ReturnHeaders if ($response.Data) { foreach ($role in $response.Data) { $role.PSObject.TypeNames.Insert(0, 'UKG.Role') } $pagination = Get-UKGNextPage -Headers $response.Headers if ($pagination.NextCursor) { Write-Verbose "Next cursor: $($pagination.NextCursor)" } return $response.Data } } } } } } function Set-UKGRole { <# .SYNOPSIS Updates an existing role in the UKG HR Service Delivery system. .DESCRIPTION Updates role properties using PUT (full replacement). .PARAMETER Id The unique identifier of the role to update. .PARAMETER Name The role name. .PARAMETER Description The role description. .PARAMETER Properties Hashtable of properties to update. .PARAMETER InputObject A hashtable or PSCustomObject containing the properties to update. .EXAMPLE Set-UKGRole -Id "role123" -Name "HR Administrator" .EXAMPLE Set-UKGRole -Id "role123" -Properties @{ name = "Admin"; description = "Administrative access" } .OUTPUTS UKG.Role object representing the updated role. #> [CmdletBinding(SupportsShouldProcess)] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('RoleId')] [string]$Id, [Parameter()] [string]$Name, [Parameter()] [string]$Description, [Parameter()] [hashtable]$Properties, [Parameter()] [object]$InputObject ) process { $body = @{} if ($InputObject) { if ($InputObject -is [hashtable]) { $body = $InputObject.Clone() } else { foreach ($prop in $InputObject.PSObject.Properties) { if ($prop.Name -notin @('id', 'created_at', 'updated_at', 'PSTypeName')) { $body[$prop.Name] = $prop.Value } } } } else { if ($Name) { $body['name'] = $Name } if ($Description) { $body['description'] = $Description } if ($Properties) { foreach ($key in $Properties.Keys) { $body[$key] = $Properties[$key] } } } if ($body.Count -eq 0) { Write-Warning "No properties specified to update." return } if ($PSCmdlet.ShouldProcess($Id, 'Update Role')) { $response = Invoke-UKGRequest -Endpoint "/roles/$Id" -Method PUT -Body $body if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.Role') } return $response } } } |