Payrun Jobs
Payrun Processing
Synchronous Payrun Job
The standard payrun job endpoint creates and executes a payrun job synchronously. The request body is a PayrunJobInvocation:
POST /api/tenants/{tenantId}/payrolls/{payrollId}/payruns/jobs
Payrun Job Preview
The preview endpoint performs a synchronous single-employee payrun calculation without persisting results. It returns a PayrollResultSet with wage type, collector, and payrun results.
POST /api/tenants/{tenantId}/payrolls/{payrollId}/payruns/jobs/preview
The preview supports any RetroPayMode to match production behavior. If retro calculation is triggered, the endpoint returns HTTP 422 with employee identifier and retro date context.
Asynchronous Payrun Job
For long-running payrun jobs, the async endpoint pre-creates the job, enqueues it for background processing, and returns immediately with HTTP 202 and a location header.
The background queue uses a bounded channel (capacity: 100) for backpressure. A webhook notification is sent on job completion or abort. Unhandled exceptions or service shutdown trigger an infrastructure abort.
Parallel Employee Processing
The MaxParallelEmployees setting controls concurrent employee processing within a payrun job:
| Value | Behavior |
|---|---|
0 or off |
Sequential processing (default) |
half |
Half of available processors |
max or -1 |
All available processors |
1–N |
Explicit thread count |
Each employee runs in an isolated PayrunEmployeeScope to prevent mutable state conflicts.
Employee Timing Logs
When LogEmployeeTiming is enabled, the engine logs per-employee duration and a summary (mode, total, average) at Information level.
Retro Payrun Limit
The MaxRetroPayrunPeriods setting (default: 0/unlimited) acts as a safety guard to prevent runaway retro calculations with RetroTimeType.Anytime.
Bulk Operations
For high-throughput data import, the API provides bulk creation endpoints that use SqlBulkCopy internally. Bulk endpoints accept an array of items and return the created item count (no individual IDs). Duplicate identifiers are caught by the database unique constraint.
POST /api/tenants/{tenantId}/employees/bulk
Content-Type: application/json
[ { "identifier": "emp001", ... }, { "identifier": "emp002", ... } ]
Items are processed in chunks of 5'000. Bulk endpoints are available for employee creation and case change import.
See also Load Testing for using bulk endpoints in performance testing scenarios.
Security
Rate Limiting
The RateLimiting configuration provides two policies:
- Global policy — applies to all endpoints with configurable PermitLimit and WindowSeconds
- Payrun job policy — dedicated limit for the payrun job start endpoint
CORS
Cross-origin requests are blocked by default. The Cors configuration supports:
| Setting | Description |
|---|---|
AllowedOrigins |
Permitted origin URLs |
AllowedMethods |
Permitted HTTP methods |
AllowedHeaders |
Permitted request headers |
AllowCredentials |
Allow credentials in cross-origin requests |
PreflightMaxAgeSeconds |
Cache duration for preflight responses |
Script Safety Analysis
When ScriptSafetyAnalysis is enabled (default: false), the backend performs static analysis of user scripts for banned API usage (System.IO, System.Net, System.Diagnostics, System.Reflection). This is opt-in due to compilation overhead.
Audit Trail
The AuditTrail configuration provides per-category flags to control audit logging:
| Category | Tracks changes to |
|---|---|
Script |
Script modifications |
Lookup |
Lookup and lookup value changes |
Input |
Case value input |
Payrun |
Payrun job execution |
Report |
Report generation |