Skip to content

Client Services

Automator|Client Services · .NET 10

The Client Services (SDK) are the primary toolset for Automators — developers who automate payroll workflows, build tooling, and extend the platform. Typical Automators include DevOps engineers, tool builders, and automation specialists integrating PayrollEngine into CI/CD pipelines or LLM workflows.

The SDK is a .NET client library that wraps the REST API and provides higher-level abstractions for common tasks.

What You Can Do

Task Tool Example
Import/export payroll data Exchange JSON and Excel regulation import
Run and validate payrun calculations Test runners Case-Test, Payrun-Test, Report-Test
Automate bulk operations Bulk API + Console Load test setup, mass employee creation
Preview payrun results Preview API Single-employee calculation without persistence
Build custom CLI tools Console Extensions Custom commands with .pecmd scripts
Integrate with LLM pipelines SDK + Console Regulation generation, review automation
Develop and debug scripts Scripting Runtime Local C# script development

SDK Components

Client Services

Component Purpose
Model API object model (based on Swagger schema), copyable and comparable, extensible by inheritance
Service Typed access to all API endpoints, extensible by inheritance
Exchange JSON and Excel import/export of payrolls and regulations
Test Test runners for cases, payruns, and reports
Function Templates for scripting function development
Runtime Local scripting runtime for development and debugging
Service API HTTP communication layer with the backend
Runtime API Communication bridge between scripting runtime and Service API

NuGet Packages

Packages are available on NuGet.org (recommended, no auth required) and GitHub Packages (requires GitHub PAT):

Package Purpose
PayrollEngine.Client.Core Core client library
PayrollEngine.Client.Services Client services for API access
PayrollEngine.Client.Scripting Scripting runtime for local development
PayrollEngine.Client.Test Test runner framework

See Repositories for package source configuration.

Payroll Console

The Payroll Console is the primary CLI tool for Automators. It exposes SDK functionality as console commands.

Core Commands

Command Purpose
Import/Export
Payroll import Import regulations and payroll data (JSON)
Payroll export Export payroll data (JSON)
RegulationExcelImport Import regulations from Excel (cases, wage types, collectors, lookups, reports, scripts)
Text table import Import CSV and tab-delimited data
Testing
CaseTest Test case input and validation
PayrunTest Test payrun calculation results
ReportTest Test report output
PayrunEmployeePreviewTest Test payrun results via preview (no persistence)
Load Testing
LoadTestGenerate Generate scaled exchange files from a regulation template
LoadTestSetup Bulk-import employees via CreateEmployeesBulkAsync
LoadTestSetupCases Bulk-import case changes via AddCasesBulkAsync
PayrunLoadTest Execute payrun with warmup, measured repetitions, and CSV report
Other
Scripting import/export/rebuild Manage regulation scripts
Payroll log trail Audit trail queries
API queries Ad-hoc queries against the backend
Reports Generate reports in various formats

Command Files

For batch execution, command chains can be defined in command files with the .pecmd extension: 

# setup and test
PayrollImport MyRegulation.json
PayrunTest MyTests.json
PayrollExport MyResults.json

Custom Commands

Beyond the built-in commands, the Payroll Console supports Automation Extensions — C# class libraries dropped into the extensions subfolder that add domain-specific commands. Typical use cases include LLM-driven DSL processing, foreign format conversion, and tenant provisioning workflows.

See Automation Extension for setup, implementation, and examples.

Exchange Model

The Exchange Model contains all API objects for data exchange:

Exchange Model

The exchange supports both full and partial payroll models. Processing classes handle the import/export sequence and provide direct object access.

Exchange Formats

Format Import Export Use Case
JSON ✓ ✓ Full payroll exchange, regulations, test data
Excel ✓ — Regulation import (cases, wage types, lookups, etc.)
CSV ✓ — Text table import

Automation Patterns

CI/CD Integration

Use the Payroll Console in build pipelines to validate regulations on every commit: 

PayrollConsole PayrunTest MyRegulation.pt.json

Load Testing

The built-in load test workflow scales any regulation template for performance testing: 1. LoadTestGenerate — create scaled exchange files 2. LoadTestSetup — bulk-import employees 3. LoadTestSetupCases — bulk-import case changes 4. PayrunLoadTest — execute and measure (outputs CSV with client and server timing)

LLM Pipeline

Combine SDK access with LLM capabilities for regulation automation: 1. LLM generates regulation JSON and C# scripts 2. SDK imports the regulation via Exchange 3. Test runners validate against expected results 4. Regulator reviews and approves

Docker

Pre-built Linux containers are available for Backend, PayrollConsole, and WebApp: 

ghcr.io/payroll-engine/backend
ghcr.io/payroll-engine/payrollconsole
ghcr.io/payroll-engine/webapp

Pre-release images skip the :latest tag.

Web Application

The web application provides browser-based access to common tasks:

  • Management of tenants and employees
  • Management of regulations
  • Entry of case data
  • Execution of payruns
  • Evaluation of payrun results
  • Management of user tasks and developer logs

Next Steps