Public/Employees/New-UKGEmployee.ps1
|
function New-UKGEmployee { <# .SYNOPSIS Creates a new employee in the UKG HR Service Delivery system. .DESCRIPTION Creates a new employee record with the specified properties. .PARAMETER Email The employee's email address (required). .PARAMETER FirstName The employee's first name (required). .PARAMETER LastName The employee's last name (required). .PARAMETER ExternalId External identifier for the employee. .PARAMETER EmployeeNumber The employee number. .PARAMETER OrganizationId The organization ID the employee belongs to. .PARAMETER HireDate The employee's hire date. .PARAMETER ManagerId The ID of the employee's manager. .PARAMETER Title The employee's job title. .PARAMETER Department The employee's department. .PARAMETER Properties Hashtable of additional properties to set on the employee. .PARAMETER InputObject A hashtable or PSCustomObject containing the employee data. .EXAMPLE New-UKGEmployee -Email "john.doe@company.com" -FirstName "John" -LastName "Doe" .EXAMPLE $emp = @{ email = "jane.smith@company.com" first_name = "Jane" last_name = "Smith" employee_number = "EMP001" } New-UKGEmployee -InputObject $emp .OUTPUTS UKG.Employee object representing the created employee. #> [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Properties')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, ParameterSetName = 'Properties')] [ValidateNotNullOrEmpty()] [string]$Email, [Parameter(Mandatory, ParameterSetName = 'Properties')] [ValidateNotNullOrEmpty()] [string]$FirstName, [Parameter(Mandatory, ParameterSetName = 'Properties')] [ValidateNotNullOrEmpty()] [string]$LastName, [Parameter(ParameterSetName = 'Properties')] [string]$ExternalId, [Parameter(ParameterSetName = 'Properties')] [string]$EmployeeNumber, [Parameter(ParameterSetName = 'Properties')] [string]$OrganizationId, [Parameter(ParameterSetName = 'Properties')] [datetime]$HireDate, [Parameter(ParameterSetName = 'Properties')] [string]$ManagerId, [Parameter(ParameterSetName = 'Properties')] [string]$Title, [Parameter(ParameterSetName = 'Properties')] [string]$Department, [Parameter(ParameterSetName = 'Properties')] [hashtable]$Properties, [Parameter(Mandatory, ParameterSetName = 'InputObject', ValueFromPipeline)] [object]$InputObject ) process { # Build the request body $body = @{} if ($PSCmdlet.ParameterSetName -eq 'InputObject') { if ($InputObject -is [hashtable]) { $body = $InputObject.Clone() } else { # Convert PSCustomObject to hashtable foreach ($prop in $InputObject.PSObject.Properties) { $body[$prop.Name] = $prop.Value } } } else { # Build from parameters $body['email'] = $Email $body['first_name'] = $FirstName $body['last_name'] = $LastName if ($ExternalId) { $body['external_id'] = $ExternalId } if ($EmployeeNumber) { $body['employee_number'] = $EmployeeNumber } if ($OrganizationId) { $body['organization_id'] = $OrganizationId } if ($HireDate) { $body['hire_date'] = $HireDate.ToString('yyyy-MM-dd') } if ($ManagerId) { $body['manager_id'] = $ManagerId } if ($Title) { $body['title'] = $Title } if ($Department) { $body['department'] = $Department } # Merge additional properties if ($Properties) { foreach ($key in $Properties.Keys) { $body[$key] = $Properties[$key] } } } $displayName = if ($body['email']) { $body['email'] } else { "$FirstName $LastName" } if ($PSCmdlet.ShouldProcess($displayName, 'Create Employee')) { $response = Invoke-UKGRequest -Endpoint '/employees' -Method POST -Body $body if ($response) { $response.PSObject.TypeNames.Insert(0, 'UKG.Employee') } return $response } } } |