en-US/about_PSUKG_Examples.help.txt
|
TOPIC about_PSUKG_Examples SHORT DESCRIPTION Practical examples and common scenarios for the PSUKG module. LONG DESCRIPTION This topic provides comprehensive examples for common tasks using the PSUKG module. Examples are organized by scenario and include complete, working code. EMPLOYEE MANAGEMENT EXAMPLES Example 1: Onboard New Employee # Complete new hire onboarding workflow $secret = Read-Host -AsSecureString -Prompt "Enter Application Secret" Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" -Region EU # Create employee $newEmployee = New-UKGEmployee ` -Email "john.doe@company.com" ` -FirstName "John" ` -LastName "Doe" ` -EmployeeNumber "E12345" ` -HireDate "2024-03-01" ` -Department "Engineering" ` -Title "Software Engineer" ` -Status "active" Write-Host "Created employee: $($newEmployee.id)" # Send portal invitation Send-UKGEmployeePortalInvite -Id $newEmployee.id Write-Host "Portal invitation sent" # Send vault invitation Send-UKGEmployeeVaultInvite -Id $newEmployee.id Write-Host "Vault invitation sent" Disconnect-UKG Example 2: Bulk Import from CSV # Import employees from CSV file Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Read and transform CSV data $csvData = Import-Csv "new_employees.csv" $employees = $csvData | ForEach-Object { @{ email = $_.Email first_name = $_.FirstName last_name = $_.LastName employee_number = $_.EmployeeNumber hire_date = $_.HireDate department = $_.Department title = $_.Title status = "active" } } # Bulk create with progress tracking Write-Host "Creating $($employees.Count) employees..." $result = Invoke-UKGEmployeeBulk -Create -Employees $employees -WaitForCompletion # Report results Write-Host "Successfully created: $($result.successful_count)" Write-Host "Failed: $($result.failed_count)" # Handle failures if ($result.failed_count -gt 0) { $failed = $result.results | Where-Object { -not $_.success } $failed | Export-Csv -Path "failed_employees.csv" -NoTypeInformation Write-Warning "Failed employees exported to failed_employees.csv" } Disconnect-UKG Example 3: Update Employee Department # Move employees to new department Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Find employees in old department $employees = Search-UKGEmployee -Filter @{ department = @{ eq = "Sales" } status = @{ eq = "active" } } -All Write-Host "Found $($employees.Count) employees in Sales department" # Update each employee $updated = 0 foreach ($employee in $employees) { try { Set-UKGEmployee -Id $employee.id -Department "Business Development" $updated++ } catch { Write-Warning "Failed to update $($employee.email): $($_.Exception.Message)" } } Write-Host "Updated $updated employees" Disconnect-UKG Example 4: Export Active Employees # Export all active employees to CSV Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get all active employees with specific fields $employees = Search-UKGEmployee -Filter @{ status = @{ eq = "active" } } -All -Fields @("id", "email", "first_name", "last_name", "employee_number", "department", "title", "hire_date") # Export to CSV $employees | Select-Object ` @{N="EmployeeID";E={$_.id}}, ` @{N="Email";E={$_.email}}, ` @{N="FirstName";E={$_.first_name}}, ` @{N="LastName";E={$_.last_name}}, ` @{N="EmployeeNumber";E={$_.employee_number}}, ` @{N="Department";E={$_.department}}, ` @{N="Title";E={$_.title}}, ` @{N="HireDate";E={$_.hire_date}} | Export-Csv -Path "active_employees.csv" -NoTypeInformation Write-Host "Exported $($employees.Count) employees to active_employees.csv" Disconnect-UKG Example 5: Find and Update Employee by Email # Search for employee and update information Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" $email = "john.doe@company.com" # Search by email $results = Search-UKGEmployee -Email $email if ($results.Count -eq 0) { Write-Warning "No employee found with email: $email" } elseif ($results.Count -gt 1) { Write-Warning "Multiple employees found with email: $email" $results | Format-Table id, email, first_name, last_name } else { $employee = $results[0] Write-Host "Found employee: $($employee.id)" # Update employee Set-UKGEmployee -Id $employee.id ` -Title "Senior Software Engineer" ` -Department "Engineering" Write-Host "Employee updated successfully" } Disconnect-UKG USER MANAGEMENT EXAMPLES Example 6: Create Admin User # Create a new admin user Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get admin role ID $roles = Get-UKGRole -All $adminRole = $roles | Where-Object { $_.name -eq "Administrator" } if (-not $adminRole) { Write-Error "Admin role not found" return } # Create user $newUser = New-UKGUser ` -Email "admin@company.com" ` -FirstName "Admin" ` -LastName "User" ` -RoleId $adminRole.id ` -Active $true Write-Host "Created user: $($newUser.id)" # Send invitation Send-UKGUserInvite -Id $newUser.id Write-Host "Invitation sent to $($newUser.email)" Disconnect-UKG Example 7: Deactivate Users # Deactivate users who haven't logged in recently Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get all users $users = Get-UKGUser -All # Filter inactive users (example logic) $cutoffDate = (Get-Date).AddMonths(-6) $inactiveUsers = $users | Where-Object { $_.last_login_at -and [DateTime]$_.last_login_at -lt $cutoffDate } Write-Host "Found $($inactiveUsers.Count) inactive users" # Deactivate each user foreach ($user in $inactiveUsers) { try { Set-UKGUser -Id $user.id -Active $false Write-Host "Deactivated: $($user.email)" } catch { Write-Warning "Failed to deactivate $($user.email): $($_.Exception.Message)" } } Disconnect-UKG DOCUMENT MANAGEMENT EXAMPLES Example 8: Upload Employee Documents # Upload documents for multiple employees Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get folder ID for contracts $folders = Get-UKGEmployeeFolder -All $contractFolder = $folders | Where-Object { $_.name -eq "Contracts" } if (-not $contractFolder) { Write-Error "Contracts folder not found" return } # Upload documents $documents = Get-ChildItem -Path "C:\Contracts" -Filter "*.pdf" foreach ($doc in $documents) { # Extract employee ID from filename (e.g., "contract_emp123.pdf") if ($doc.Name -match "contract_(\w+)\.pdf") { $employeeId = $Matches[1] try { Send-UKGDocument ` -FilePath $doc.FullName ` -EmployeeId $employeeId ` -FolderId $contractFolder.id Write-Host "Uploaded $($doc.Name) for employee $employeeId" } catch { Write-Warning "Failed to upload $($doc.Name): $($_.Exception.Message)" } } } Disconnect-UKG Example 9: Download Employee Documents # Get document URLs for all employees Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" $employeeId = "emp123" # Get all documents for employee $documents = Get-UKGEmployeeDocument -EmployeeId $employeeId -All Write-Host "Found $($documents.Count) documents" # Get redirection URL for each document foreach ($doc in $documents) { $url = Get-UKGRedirectionUrl -EmployeeId $employeeId -DocumentId $doc.id Write-Host "$($doc.name): $url" # Optionally download using Invoke-WebRequest # Invoke-WebRequest -Uri $url -OutFile "C:\Downloads\$($doc.name)" } Disconnect-UKG ORGANIZATION MANAGEMENT EXAMPLES Example 10: Display Organization Hierarchy # Show organization structure Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get all organizations $orgs = Get-UKGOrganization -All # Display hierarchy function Show-OrgHierarchy { param( $Organization, $Indent = 0 ) $spaces = " " * $Indent Write-Host "$spaces$($Organization.name) (ID: $($Organization.id))" if ($Organization.children) { foreach ($child in $Organization.children) { Show-OrgHierarchy -Organization $child -Indent ($Indent + 1) } } } # Find root organizations (those without parent) $rootOrgs = $orgs | Where-Object { -not $_.parent_id } foreach ($root in $rootOrgs) { Show-OrgHierarchy -Organization $root } Disconnect-UKG Example 11: List Employees by Department # Get employees grouped by department Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get all active employees $employees = Search-UKGEmployee -Filter @{ status = @{ eq = "active" } } -All # Group by department $byDepartment = $employees | Group-Object -Property department # Display results foreach ($dept in $byDepartment | Sort-Object Name) { Write-Host "`n$($dept.Name): $($dept.Count) employees" $dept.Group | Sort-Object last_name | ForEach-Object { Write-Host " $($_.last_name), $($_.first_name) - $($_.title)" } } Disconnect-UKG REPORTING EXAMPLES Example 12: Monthly New Hire Report # Generate new hire report for current month Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" $startDate = Get-Date -Day 1 -Format "yyyy-MM-dd" $endDate = (Get-Date).ToString("yyyy-MM-dd") # Search for employees hired this month $newHires = Search-UKGEmployee -Filter @{ hire_date = @{ gte = $startDate lte = $endDate } } -All # Generate report $report = $newHires | Select-Object ` @{N="HireDate";E={$_.hire_date}}, ` @{N="EmployeeNumber";E={$_.employee_number}}, ` @{N="Name";E={"$($_.first_name) $($_.last_name)"}}, ` @{N="Email";E={$_.email}}, ` @{N="Department";E={$_.department}}, ` @{N="Title";E={$_.title}} # Export to CSV $filename = "NewHires_$(Get-Date -Format 'yyyy-MM').csv" $report | Export-Csv -Path $filename -NoTypeInformation Write-Host "New hire report exported to $filename" Write-Host "Total new hires: $($newHires.Count)" Disconnect-UKG Example 13: Employee Status Summary # Generate employee status summary Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Get all employees $employees = Get-UKGEmployee -All # Group by status $statusSummary = $employees | Group-Object -Property status Write-Host "`nEmployee Status Summary" Write-Host "=======================" foreach ($status in $statusSummary | Sort-Object Name) { Write-Host "$($status.Name): $($status.Count)" } Write-Host "`nTotal Employees: $($employees.Count)" Disconnect-UKG AUTOMATION EXAMPLES Example 14: Scheduled Employee Sync # Script to run on schedule for employee synchronization param( [string]$ConfigFile = "ukg_config.json" ) # Load configuration $config = Get-Content $ConfigFile | ConvertFrom-Json # Connect $secret = $config.ApplicationSecret | ConvertTo-SecureString Connect-UKG ` -ApplicationId $config.ApplicationId ` -ApplicationSecret $secret ` -ClientId $config.ClientId ` -Region $config.Region try { # Get employees from UKG $ukgEmployees = Get-UKGEmployee -All # Get employees from your HR system (example) $hrEmployees = Get-EmployeesFromHRSystem # Find new employees to create $newEmployees = $hrEmployees | Where-Object { $_.EmployeeNumber -notin $ukgEmployees.employee_number } if ($newEmployees) { # Bulk create new employees $employeeData = $newEmployees | ForEach-Object { @{ email = $_.Email first_name = $_.FirstName last_name = $_.LastName employee_number = $_.EmployeeNumber hire_date = $_.HireDate department = $_.Department } } $result = Invoke-UKGEmployeeBulk -Create -Employees $employeeData -WaitForCompletion Write-Host "Created $($result.successful_count) new employees" } # Find employees to update $toUpdate = $hrEmployees | Where-Object { $_.EmployeeNumber -in $ukgEmployees.employee_number } foreach ($emp in $toUpdate) { $ukgEmp = $ukgEmployees | Where-Object { $_.employee_number -eq $emp.EmployeeNumber } # Check if department changed if ($ukgEmp.department -ne $emp.Department) { Set-UKGEmployee -Id $ukgEmp.id -Department $emp.Department Write-Host "Updated department for $($emp.EmployeeNumber)" } } } catch { Write-Error "Sync failed: $($_.Exception.Message)" # Send notification email } finally { Disconnect-UKG } Example 15: Monitor Bulk Operation # Submit bulk operation and monitor in background Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Submit bulk operation without waiting $employees = Import-Csv "employees.csv" | ForEach-Object { @{ email = $_.Email first_name = $_.FirstName last_name = $_.LastName employee_number = $_.EmployeeNumber } } $bulkOp = Invoke-UKGEmployeeBulk -Create -Employees $employees Write-Host "Bulk operation submitted: $($bulkOp.id)" # Do other work while operation processes Write-Host "Performing other tasks..." Start-Sleep -Seconds 5 # Check status periodically $maxWait = 300 # 5 minutes $elapsed = 0 $pollInterval = 2 do { $status = Get-UKGEmployeeBulkStatus -Id $bulkOp.id Write-Host "Status: $($status.status) (Elapsed: $elapsed seconds)" if ($status.status -in @('pending', 'processing')) { Start-Sleep -Seconds $pollInterval $elapsed += $pollInterval } else { break } } while ($elapsed -lt $maxWait) # Check final result if ($status.status -eq 'completed') { Write-Host "Operation completed successfully" Write-Host "Created: $($status.successful_count)" Write-Host "Failed: $($status.failed_count)" } else { Write-Warning "Operation did not complete: $($status.status)" } Disconnect-UKG KEYWORDS Examples, Scenarios, Recipes, Cookbook, HowTo SEE ALSO about_PSUKG about_PSUKG_Authentication about_PSUKG_Pagination about_PSUKG_BulkOperations about_PSUKG_ErrorHandling |