en-US/about_PSUKG_Pagination.help.txt
|
TOPIC about_PSUKG_Pagination SHORT DESCRIPTION Explains pagination and cursor-based navigation in the PSUKG module. LONG DESCRIPTION The UKG API uses cursor-based pagination for listing resources. The PSUKG module provides both manual cursor control and automatic pagination to retrieve all results. Understanding Cursor-Based Pagination Unlike traditional page number pagination, the UKG API uses cursors. How It Works: 1. Request the first page of results 2. API returns data plus a cursor pointing to the next page 3. Use that cursor to request the next page 4. Repeat until no cursor is returned (last page) Benefits: - Consistent results even if data changes during pagination - Better performance than offset-based pagination - No "lost" or "duplicate" records when data is added/removed Pagination Parameters Most List cmdlets support these parameters: -PerPage [int] Number of results per page (1-100, default 25). Controls how many items are returned in each API call. Example: Get-UKGEmployee -All -PerPage 50 -Cursor [string] Pagination cursor for retrieving a specific page. Typically used for manual pagination control. Example: $result = Get-UKGEmployee -PerPage 25 $nextPage = Get-UKGEmployee -Cursor $result.meta.cursor -All [switch] Automatically retrieves all pages and returns all results. The module handles cursor management internally. Example: Get-UKGEmployee -All Automatic Pagination When you use the -All switch, the module automatically: 1. Makes the first API request 2. Checks for a cursor in the response 3. If cursor exists, requests the next page 4. Repeats until no cursor is returned 5. Returns all collected results as a single array Example: # Get all employees (automatically handles pagination) $allEmployees = Get-UKGEmployee -All # Get all users with 100 per page for faster retrieval $allUsers = Get-UKGUser -All -PerPage 100 Manual Pagination For fine-grained control, you can manually handle pagination: Example: $cursor = $null $allEmployees = @() do { if ($cursor) { $result = Get-UKGEmployee -Cursor $cursor -PerPage 50 } else { $result = Get-UKGEmployee -PerPage 50 } $allEmployees += $result.data $cursor = $result.meta.cursor Write-Verbose "Retrieved $($result.data.Count) employees, Total: $($allEmployees.Count)" } while ($cursor) Response Structure Paginated responses contain two main sections: data: Array of resource objects (employees, users, etc.) meta: Metadata about the pagination: - cursor: Token for the next page (null if last page) - per_page: Number of items per page - total_count: Total number of items (when available) Example Response: @{ data = @( @{ id = "emp1"; first_name = "John"; last_name = "Doe" }, @{ id = "emp2"; first_name = "Jane"; last_name = "Smith" } ) meta = @{ cursor = "eyJpZCI6ImVtcDIifQ==" per_page = 25 } } Performance Considerations PerPage Size: - Smaller values (1-25): More API calls, slower overall - Larger values (50-100): Fewer API calls, faster overall - Recommended: 50-100 for bulk operations, 25 for interactive use Memory Usage: When using -All, all results are loaded into memory. For very large result sets (10,000+ items), consider: - Processing in batches with manual pagination - Using streaming patterns with ForEach-Object - Filtering with -Fields to reduce data size Network Impact: Each page requires an API call. Larger PerPage values reduce network round-trips. Filtering and Pagination Some cmdlets support filtering, which reduces the result set: # Search with automatic pagination Search-UKGEmployee -Filter @{ status = @{ eq = "active" } } -All # Get specific fields only (reduces data size) Get-UKGEmployee -All -Fields @("id", "email", "first_name", "last_name") Pipeline Support Paginated results work seamlessly with PowerShell pipelines: # Process each employee as it's retrieved Get-UKGEmployee -All | ForEach-Object { Write-Host "$($_.first_name) $($_.last_name) - $($_.email)" } # Filter and transform Get-UKGEmployee -All | Where-Object { $_.status -eq "active" } | Select-Object id, email, department Cmdlets with Pagination Support The following cmdlets support pagination parameters: Employees: Get-UKGEmployee -All Search-UKGEmployee -All Users: Get-UKGUser -All Organizations: Get-UKGOrganization -All Get-UKGOrganizationGroup -All Roles: Get-UKGRole -All Custom Fields: Get-UKGCustomField -All Documents: Get-UKGEmployeeDocument -All Get-UKGEmployeeDocumentType -All Get-UKGCompanyDocumentType -All Folders: Get-UKGEmployeeFolder -All Get-UKGCompanyFolder -All Subscriptions: Get-UKGEmployeeSubscription -All Troubleshooting Pagination Incomplete Results: Ensure you're using -All or manually checking for cursors. Without -All, only the first page is returned. Performance Issues: Increase -PerPage to reduce API calls: Get-UKGEmployee -All -PerPage 100 Memory Issues: For very large datasets, use manual pagination and process in batches: $cursor = $null do { $result = Get-UKGEmployee -Cursor $cursor -PerPage 100 $result.data | Process-Employee # Process immediately $cursor = $result.meta.cursor } while ($cursor) Cursor Expiration: Cursors are typically valid for a short time. Complete pagination promptly. If a cursor expires, start from the beginning. EXAMPLES Example 1: Automatic Pagination # Get all employees (simplest approach) $employees = Get-UKGEmployee -All Write-Host "Retrieved $($employees.Count) employees" Example 2: Large Page Size for Performance # Get all users with 100 per page $users = Get-UKGUser -All -PerPage 100 # Significantly faster than default 25 per page Example 3: Manual Pagination with Progress # Manually paginate with progress indication $cursor = $null $allEmployees = @() $pageNum = 0 do { $pageNum++ Write-Progress -Activity "Retrieving Employees" -Status "Page $pageNum" if ($cursor) { $result = Get-UKGEmployee -Cursor $cursor -PerPage 50 } else { $result = Get-UKGEmployee -PerPage 50 } $allEmployees += $result.data $cursor = $result.meta.cursor } while ($cursor) Write-Progress -Activity "Retrieving Employees" -Completed Write-Host "Retrieved $($allEmployees.Count) employees in $pageNum pages" Example 4: Stream Processing (Memory Efficient) # Process employees in batches without loading all into memory $cursor = $null $processedCount = 0 do { $result = Get-UKGEmployee -Cursor $cursor -PerPage 100 # Process this batch immediately foreach ($employee in $result.data) { if ($employee.status -eq "active") { # Do something with each employee Write-Host "Processing: $($employee.email)" $processedCount++ } } $cursor = $result.meta.cursor } while ($cursor) Write-Host "Processed $processedCount active employees" Example 5: Filtered Pagination # Search with filter and automatic pagination $activeEmployees = Search-UKGEmployee -Filter @{ status = @{ eq = "active" } hire_date = @{ gte = "2024-01-01" } } -All -PerPage 100 Write-Host "Found $($activeEmployees.Count) employees hired in 2024" Example 6: Selective Field Retrieval # Get only specific fields to reduce data size $employeeEmails = Get-UKGEmployee -All -Fields @("id", "email") -PerPage 100 # Export to CSV $employeeEmails | Export-Csv -Path "employees.csv" -NoTypeInformation Example 7: Pipeline Processing # Pipeline approach - processes as data arrives Get-UKGEmployee -All -PerPage 100 | Where-Object { $_.department -eq "Engineering" } | ForEach-Object { Send-UKGEmployeePortalInvite -Id $_.id } KEYWORDS Pagination, Cursor, PerPage, All, Navigation, Listing SEE ALSO about_PSUKG Get-UKGEmployee Search-UKGEmployee Get-UKGUser |