en-US/about_PSFloRecruit.help.txt
|
TOPIC about_PSFloRecruit SHORT DESCRIPTION PSFloRecruit is a PowerShell module for interacting with the FloRecruit HRIS API to manage job applications, candidates, and recruitment data. LONG DESCRIPTION The PSFloRecruit module provides a PowerShell interface to the FloRecruit Human Resources Information System (HRIS) API. It enables automation of recruitment workflows, data retrieval, and integration with other systems. The module handles authentication, session management, rate limiting, and provides PowerShell-native cmdlets for working with FloRecruit data. Key Features - Secure authentication with MFA support - Automatic session and token management - Built-in rate limiting (1000 requests per 5 minutes) - Automatic pagination for large datasets - Cross-platform support (PowerShell 5.1 and 7+) - Pipeline support for data manipulation - Error handling with detailed messages System Requirements - PowerShell 5.1 or higher (PowerShell 7+ recommended) - Internet connectivity to FloRecruit API - FloRecruit admin account with API access enabled - Windows, macOS, or Linux operating system Installation From PowerShell Gallery (once published): Install-Module -Name PSFloRecruit -Scope CurrentUser From source: git clone https://github.com/yourusername/psflorecruit.git Import-Module ./psflorecruit/PSFloRecruit/PSFloRecruit.psd1 Module Structure The module is organized into the following components: Authentication Functions: Connect-FloRecruit - Establish authenticated session Disconnect-FloRecruit - Clear session and credentials Get-FloRecruitSession - View current session status Job Application Functions: Get-FloRecruitJobApplication - Retrieve job applications The module maintains a script-scoped session variable that persists authentication state across cmdlet calls within the same PowerShell session. GETTING STARTED Step 1: Import the Module Import-Module PSFloRecruit Step 2: Authenticate Basic authentication: $password = Read-Host -AsSecureString -Prompt "Password" Connect-FloRecruit -OrganizationName "myorg" ` -Email "admin@myorg.com" ` -Password $password With MFA enabled: $password = Read-Host -AsSecureString -Prompt "Password" $mfa = Read-Host -AsSecureString -Prompt "MFA Secret" Connect-FloRecruit -OrganizationName "myorg" ` -Email "admin@myorg.com" ` -Password $password ` -MFASecret $mfa Step 3: Verify Connection Get-FloRecruitSession Step 4: Retrieve Data # Get all job applications Get-FloRecruitJobApplication -All # Get filtered results Get-FloRecruitJobApplication -StatusBucket Hired -Limit 100 Step 5: Disconnect When Done Disconnect-FloRecruit AUTHENTICATION The module uses cookie-based authentication with the FloRecruit API. Credentials are stored securely using SecureString objects. Connection Parameters -OrganizationName Your FloRecruit organization identifier -Email Admin account email address -Password SecureString password (recommended) -PasswordPlainText Plain text password (use only when necessary) -MFASecret SecureString MFA secret (if MFA enabled) -BaseUrl Override API URL (for testing/staging) Session Management The module maintains a single session per PowerShell session. Each successful Connect-FloRecruit call replaces any existing session. Session properties include: - OrganizationName - Email (not password) - BaseUrl - AuthToken - TokenExpiry - ConnectedAt - RequestCount and rate limiting data Token Expiry and Refresh The module tracks token expiry (estimated at 30 minutes). When a request fails due to authentication, the module automatically re-authenticates using stored credentials. Security Best Practices 1. Always use SecureString for passwords: $password = Read-Host -AsSecureString -Prompt "Password" 2. Never hard-code credentials in scripts: # Bad: -Password "MyPassword123" # Good: -Password $password 3. Call Disconnect-FloRecruit when done to clear credentials from memory 4. Use Windows Credential Manager or secret management solutions: Install-Module -Name Microsoft.PowerShell.SecretManagement $password = Get-Secret -Name FloRecruitPassword 5. Consider using environment variables for organization name: $org = $env:FLORECRUIT_ORG Connect-FloRecruit -OrganizationName $org -Email $email -Password $pw RATE LIMITING The FloRecruit API enforces a rate limit of 1000 requests per 5-minute window. The module automatically tracks and manages this limit. Automatic Rate Limiting Features - Tracks requests in current window - Warns when approaching limit (at 950 requests) - Automatically sleeps when limit reached - Resets counter at window boundary Monitoring Rate Limits $session = Get-FloRecruitSession Write-Host "Requests made: $($session.RequestsInWindow)" Write-Host "Requests remaining: $($session.RequestsRemaining)" Write-Host "Window resets in: $($session.WindowRemaining)" Best Practices - Use -All parameter for automatic pagination - Apply filters to reduce data volume - Cache results when possible - Batch operations in single sessions WORKING WITH JOB APPLICATIONS The Get-FloRecruitJobApplication cmdlet retrieves job application data with comprehensive filtering and pagination support. Basic Retrieval # Get all applications (uses automatic pagination) $apps = Get-FloRecruitJobApplication -All # Get specific number of results $apps = Get-FloRecruitJobApplication -Limit 100 Filtering # By status Get-FloRecruitJobApplication -Status "Hired" # By status bucket Get-FloRecruitJobApplication -StatusBucket "Offered" # By date range $start = Get-Date "2026-01-01" $end = Get-Date "2026-01-31" Get-FloRecruitJobApplication -StatusStart $start -StatusEnd $end # Combine filters Get-FloRecruitJobApplication -StatusBucket Hired ` -StatusStart $start ` -StatusEnd $end ` -All Pagination Manual pagination using cursor: $page1 = Get-FloRecruitJobApplication -Limit 100 $cursor = $page1.next_cursor $page2 = Get-FloRecruitJobApplication -Limit 100 -Cursor $cursor Automatic pagination (recommended): $allApps = Get-FloRecruitJobApplication -All Pipeline Operations # Filter and transform Get-FloRecruitJobApplication -StatusBucket Hired | Where-Object { $_.jobTitle -like "*Engineer*" } | Select-Object firstName, lastName, email, hireDate # Export to CSV Get-FloRecruitJobApplication -All | Export-Csv -Path "applications.csv" -NoTypeInformation # Group and count Get-FloRecruitJobApplication -All | Group-Object -Property status | Sort-Object Count -Descending # Calculate statistics $apps = Get-FloRecruitJobApplication -StatusBucket Hired $avgDaysToHire = ($apps | Measure-Object -Property daysInPipeline -Average).Average ERROR HANDLING The module provides comprehensive error handling with descriptive messages. Common Errors Not Connected: Get-FloRecruitJobApplication # Error: Not connected to FloRecruit. Use Connect-FloRecruit first. Authentication Failed: Connect-FloRecruit -OrganizationName "test" -Email "wrong" -Password $pw # Error: FloRecruit API Error (HTTP 401): Authentication failed Invalid Parameters: Get-FloRecruitJobApplication -Limit 2000 # Error: Limit must be between 1 and 1000 Rate Limit Exceeded: # Warning: Rate limit reached (1000/1000). Waiting 305 seconds... Error Handling in Scripts try { Connect-FloRecruit -OrganizationName $org ` -Email $email ` -Password $password $apps = Get-FloRecruitJobApplication -All # Process applications foreach ($app in $apps) { # Your logic here } } catch { Write-Error "Failed to retrieve applications: $_" # Cleanup or retry logic } finally { Disconnect-FloRecruit } EXAMPLES Example 1: Basic Connection and Data Retrieval # Authenticate $password = Read-Host -AsSecureString -Prompt "Password" Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password # Get all hired candidates $hired = Get-FloRecruitJobApplication -StatusBucket Hired -All # Display results $hired | Format-Table firstName, lastName, jobTitle, hireDate # Disconnect Disconnect-FloRecruit Example 2: Export Monthly Hiring Report # Connect $password = Read-Host -AsSecureString -Prompt "Password" Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password # Get January hires $start = Get-Date "2026-01-01" $end = Get-Date "2026-01-31" $januaryHires = Get-FloRecruitJobApplication ` -StatusBucket Hired ` -StatusStart $start ` -StatusEnd $end ` -All # Export to CSV $januaryHires | Select-Object firstName, lastName, email, jobTitle, hireDate | Export-Csv -Path "January2026_Hires.csv" -NoTypeInformation Write-Host "Exported $($januaryHires.Count) hires to CSV" Disconnect-FloRecruit Example 3: Pipeline Filtering and Analysis Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password # Get engineering hires and calculate average time to hire $engineeringHires = Get-FloRecruitJobApplication -StatusBucket Hired | Where-Object { $_.jobTitle -like "*Engineer*" } $stats = $engineeringHires | Measure-Object -Property daysInPipeline -Average -Minimum -Maximum Write-Host "Engineering Hires: $($engineeringHires.Count)" Write-Host "Average Days to Hire: $($stats.Average)" Write-Host "Fastest Hire: $($stats.Minimum) days" Write-Host "Slowest Hire: $($stats.Maximum) days" Disconnect-FloRecruit Example 4: Monitoring Session and Rate Limits Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password # Check session before heavy operation $session = Get-FloRecruitSession Write-Host "Connected as: $($session.Email)" Write-Host "Requests remaining: $($session.RequestsRemaining)" Write-Host "Token expires: $($session.TokenExpiry)" # Perform operations $apps = Get-FloRecruitJobApplication -All # Check session after $session = Get-FloRecruitSession Write-Host "Requests used: $($session.RequestsInWindow)" Disconnect-FloRecruit Example 5: Automated Weekly Report Script # weekly-hiring-report.ps1 param( [Parameter(Mandatory)] [string]$OrganizationName, [Parameter(Mandatory)] [string]$Email, [Parameter(Mandatory)] [securestring]$Password, [Parameter()] [int]$DaysBack = 7 ) # Connect Connect-FloRecruit -OrganizationName $OrganizationName ` -Email $Email ` -Password $Password try { # Calculate date range $end = Get-Date $start = $end.AddDays(-$DaysBack) # Get applications $apps = Get-FloRecruitJobApplication ` -StatusStart $start ` -StatusEnd $end ` -All # Generate summary $summary = $apps | Group-Object -Property status | Select-Object @{N='Status';E={$_.Name}}, Count # Display report Write-Host "`nHiring Activity Report - Last $DaysBack Days" ` -ForegroundColor Green Write-Host "Period: $($start.ToShortDateString()) to $($end.ToShortDateString())`n" $summary | Format-Table -AutoSize # Export detailed data $filename = "hiring_report_$(Get-Date -Format 'yyyyMMdd').csv" $apps | Export-Csv -Path $filename -NoTypeInformation Write-Host "`nDetailed report saved to: $filename" ` -ForegroundColor Cyan } finally { Disconnect-FloRecruit } Example 6: Using Stored Credentials (SecretManagement) # One-time setup Install-Module Microsoft.PowerShell.SecretManagement -Force Install-Module Microsoft.PowerShell.SecretStore -Force # Store credentials $password = Read-Host -AsSecureString -Prompt "FloRecruit Password" Set-Secret -Name FloRecruitPassword -Secret $password Set-Secret -Name FloRecruitOrg -Secret "acme" Set-Secret -Name FloRecruitEmail -Secret "hr@acme.com" # Use in scripts $org = Get-Secret -Name FloRecruitOrg -AsPlainText $email = Get-Secret -Name FloRecruitEmail -AsPlainText $password = Get-Secret -Name FloRecruitPassword Connect-FloRecruit -OrganizationName $org ` -Email $email ` -Password $password ADVANCED TOPICS Custom Object Types The module adds PSTypeName to returned objects for enhanced formatting: FloRecruit.Session - Session object FloRecruit.SessionInfo - Session information object FloRecruit.JobApplication - Job application object You can create custom format files or type extensions for these objects. Verbose Logging Enable verbose output for troubleshooting: Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password ` -Verbose Get-FloRecruitJobApplication -All -Verbose Module Development The module structure: PSFloRecruit/ ├── PSFloRecruit.psd1 # Module manifest ├── PSFloRecruit.psm1 # Module loader ├── Public/ # Exported functions │ ├── Authentication/ │ └── JobApplications/ ├── Private/ # Internal functions ├── Tests/ # Pester tests └── en-US/ # Help files Contributing To contribute to the module: 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass with Invoke-Pester 5. Update this help file if adding features 6. Submit a pull request TROUBLESHOOTING Issue: "Not connected to FloRecruit" Solution: Call Connect-FloRecruit before using other cmdlets Issue: Authentication fails with valid credentials Possible causes: - Incorrect organization name - MFA required but not provided - Account doesn't have API access enabled - Incorrect password Solution: Verify credentials, check MFA requirement, contact FloRecruit support to enable API access Issue: "Rate limit reached" warnings Solution: The module automatically handles this by waiting. To avoid: - Use filters to reduce data volume - Cache results instead of repeated queries - Batch operations in single sessions Issue: Token expired errors Solution: The module should auto-refresh. If persistent: - Disconnect and reconnect: Disconnect-FloRecruit; Connect-FloRecruit - Check if token lifetime changed in FloRecruit settings Issue: Large datasets timing out Solution: Use -All parameter for automatic pagination instead of large -Limit values Issue: Module not loading Solution: - Verify PowerShell version: $PSVersionTable.PSVersion - Check module path: $env:PSModulePath - Import explicitly: Import-Module .\PSFloRecruit\PSFloRecruit.psd1 Enable Debug Output For detailed troubleshooting: $DebugPreference = 'Continue' Connect-FloRecruit -OrganizationName "acme" ` -Email "hr@acme.com" ` -Password $password ` -Debug FREQUENTLY ASKED QUESTIONS Q: Can I use this module in automation/scheduled tasks? A: Yes, but you must securely store and retrieve credentials. Use SecretManagement or Windows Credential Manager. Q: Does this work on Linux/Mac? A: Yes, the module is cross-platform and works on PowerShell 7+ on Windows, Linux, and macOS. Q: Can I connect to multiple organizations simultaneously? A: No, the module maintains a single session. You must disconnect and reconnect to switch organizations. Q: How do I handle proxy servers? A: PowerShell respects system proxy settings. For custom proxy: $PSDefaultParameterValues['Invoke-WebRequest:Proxy'] = 'http://proxy:8080' Q: Is there a limit to how much data I can retrieve? A: The API rate limit is 1000 requests per 5 minutes. Using -All handles pagination automatically within this limit. Q: Can I export data to Excel? A: Yes, use the ImportExcel module: Install-Module ImportExcel Get-FloRecruitJobApplication -All | Export-Excel -Path "data.xlsx" Q: How do I report bugs or request features? A: Use the GitHub issue tracker at: https://github.com/yourusername/psflorecruit/issues KEYWORDS FloRecruit HRIS HR Human Resources Recruiting ATS Applicant Tracking Job Applications API REST SEE ALSO Connect-FloRecruit Disconnect-FloRecruit Get-FloRecruitSession Get-FloRecruitJobApplication about_Functions_Advanced_Parameters about_SecureString Online Documentation: https://github.com/yourusername/psflorecruit |