Public/CustomFields/Get-UKGCustomField.ps1
|
function Get-UKGCustomField { <# .SYNOPSIS Gets custom field information from the UKG HR Service Delivery API. .DESCRIPTION Retrieves custom field definitions by ID or lists all custom fields. .PARAMETER Id The unique identifier of the custom field to retrieve. .PARAMETER All Retrieves all custom fields. .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-UKGCustomField -Id "cf123" .EXAMPLE Get-UKGCustomField -All .OUTPUTS UKG.CustomField or array of UKG.CustomField objects. #> [CmdletBinding(DefaultParameterSetName = 'ById')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('CustomFieldId')] [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 = "/custom_fields/$Id" $response = Invoke-UKGRequest -Endpoint $endpoint -Method GET -QueryParameters $queryParams if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.CustomField') } return $response } 'List' { $queryParams['per_page'] = $PerPage if ($Cursor) { $queryParams['cursor'] = $Cursor } if ($All -and -not $Cursor) { $allFields = Get-UKGAllPages -Endpoint '/custom_fields' -Method GET -QueryParameters $queryParams foreach ($field in $allFields) { $field.PSObject.TypeNames.Insert(0, 'UKG.CustomField') } return $allFields } else { $response = Invoke-UKGRequest -Endpoint '/custom_fields' -Method GET -QueryParameters $queryParams -ReturnHeaders if ($response.Data) { foreach ($field in $response.Data) { $field.PSObject.TypeNames.Insert(0, 'UKG.CustomField') } $pagination = Get-UKGNextPage -Headers $response.Headers if ($pagination.NextCursor) { Write-Verbose "Next cursor: $($pagination.NextCursor)" } return $response.Data } } } } } } function Set-UKGCustomField { <# .SYNOPSIS Updates an existing custom field in the UKG HR Service Delivery system. .DESCRIPTION Updates custom field properties using either PUT (full replacement) or PATCH (partial update). .PARAMETER Id The unique identifier of the custom field to update. .PARAMETER Name The custom field name. .PARAMETER Label The display label for the custom field. .PARAMETER Type The field type (string, number, date, boolean, etc.). .PARAMETER Required Whether the field is required. .PARAMETER Options Array of options for select/dropdown fields. .PARAMETER Properties Hashtable of properties to update. .PARAMETER InputObject A hashtable or PSCustomObject containing the properties to update. .PARAMETER Replace Use PUT method for full replacement instead of PATCH. .EXAMPLE Set-UKGCustomField -Id "cf123" -Label "Employee Badge Number" .EXAMPLE Set-UKGCustomField -Id "cf123" -Properties @{ required = $true; options = @("Option1", "Option2") } .OUTPUTS UKG.CustomField object representing the updated custom field. #> [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Properties')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('CustomFieldId')] [string]$Id, [Parameter(ParameterSetName = 'Properties')] [string]$Name, [Parameter(ParameterSetName = 'Properties')] [string]$Label, [Parameter(ParameterSetName = 'Properties')] [ValidateSet('string', 'number', 'date', 'boolean', 'select', 'multiselect')] [string]$Type, [Parameter(ParameterSetName = 'Properties')] [bool]$Required, [Parameter(ParameterSetName = 'Properties')] [string[]]$Options, [Parameter(ParameterSetName = 'Properties')] [hashtable]$Properties, [Parameter(Mandatory, ParameterSetName = 'InputObject')] [object]$InputObject, [Parameter()] [switch]$Replace ) 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 ($Label) { $body['label'] = $Label } if ($Type) { $body['type'] = $Type } if ($PSBoundParameters.ContainsKey('Required')) { $body['required'] = $Required } if ($Options) { $body['options'] = $Options } if ($Properties) { foreach ($key in $Properties.Keys) { $body[$key] = $Properties[$key] } } } if ($body.Count -eq 0) { Write-Warning "No properties specified to update." return } $method = if ($Replace) { 'PUT' } else { 'PATCH' } if ($PSCmdlet.ShouldProcess($Id, "Update Custom Field ($method)")) { $response = Invoke-UKGRequest -Endpoint "/custom_fields/$Id" -Method $method -Body $body if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.CustomField') } return $response } } } |