Skip to content

Technical Integration

Provider|REST API · OpenAPI 3.1

Contents

Section Description
Whitebox API Blackbox vs. Whitebox REST API — Scripting API concept
REST API OpenAPI, technologies, list queries, attribute queries
.NET Client Integration Client Services SDK
Report Integration FastReport and custom IDataMerge
Webhooks Events, tracking, HTTP POST callbacks
Database Integration SQL Server and custom IDbContext
Logger Integration Serilog and custom ILogger
Administration API Cache, app termination, report endpoints
Application Logs Log files, payrun logs, report logs
Exchange Tools Import, export, convert commands

Whitebox API

The Payroll Engine is a Whitebox REST API with an additional interface—the Scripting API—through which runtime behavior can be influenced. The following diagram shows the difference between a conventional Blackbox REST API and the Payroll Engine Whitebox REST API:

Whitebox API

With a Blackbox API, the REST client communicates with the payroll REST API directly. The Whitebox API additionally allows a Payroll Solution to influence runtime behavior by providing C# scripts (Scripting API) that are compiled and executed by the backend at runtime.

REST API

The Payroll Engine is based on the open standard OpenAPI Specification and can be used by any REST-enabled client. The swagger.json file is included in the Release assets.

When running the Backend with ASPNETCORE_ENVIRONMENT=Development (default in the Docker Compose setup), the Swagger UI is available at http://localhost:5001/swagger. See Container Setup for details.

Technologies

The following technologies are used in the Payroll Backend:

Component Technology
REST API OpenAPI 3.1 (OAS3.1), media type application/json
Authentication None, API Key, or OAuth
Scripting API C# 14
Applications .NET 10
Database SQL Server 2017 or newer
Development packages NuGet Packages (GitHub Packages + NuGet.org)
Application packages Docker Container (ghcr.io)

See Security for authentication and authorization details. See Container Setup for Docker deployment.

List Queries

The following criteria can be used to restrict data in API list queries:

  • Status filter for active or inactive objects
  • OData filter expressions
  • OData field ordering
  • OData field selection
  • Pagination with page size and offset

See API Usage for OData query syntax and examples.

Attribute Queries

The engine supports filtering, sorting and grouping of list queries by attribute values. The prefix in the attribute name determines the data type:

Prefix Data Type Example
TA_ Text TA_MyName
DA_ Date DA_ProjectCreated
NA_ Number NA_SecurityLimit

.NET Client Integration

.NET clients can use the Payroll Engine at code level with the Client Services. Examples of the use of Client Services are the Payroll Console and the Web Application.

Report Integration

The Payroll Engine Clients are using by default the FastReport solution. To integrate another report engine, the IDataMerge interface from the payroll core project needs to be implemented.

Webhooks

Webhooks enable bidirectional communication between the API client and the backend. When certain events occur, the backend calls an external endpoint. Triggers for webhooks are

  • Engine: System events for changes in cases, payruns and tasks
  • Automation: Custom webhook invocation in scripting function (InvokeWebhook, see Payrun Scripting)

The engine provides webhooks for the following events:

Event Trigger Track
CaseFunctionRequest Case function request —
CaseValueAdded New case mutation ✓
PayrunFunctionRequest Payrun function request —
PayrunJobStarted Statutory payrun job released for processing ✓
PayrunJobCompleted Statutory payrun job completed ✓
ReportFunctionRequest Report function request —
TaskChange Task change —

Webhook messages are sent via HTTP POST. The backend evaluates the HTTP status code and content (JSON) of the webhook response. Specific webhook messages are tracked and can be queried via the REST API.

The tutorial Webhook Consumer shows how Payroll Engine messages are forwarded to another service.

Database Integration

Currently the backend supports the SQL Server with about 65 tables, 40 stored procedures and 8 functions. To integrate other databases, the IDbContext interface from the backend project needs to be implemented.

Logger Integration

The Payroll Engine Clients are using by default the Serilog Logger solution. To integrate another logger, the ILogger interface from the payroll core project needs to be implemented.

Administration API

The Payroll API provides several endpoints for system administration:

  • Terminate the application
  • Clear the application cache
  • List available report endpoints (see Reports)

Application Logs

For system analysis, the engine logs certain events to log files that do not contain sensitive information. Log files are stored in the Windows system program data directory (%ProgramData%).

In addition to the application log, the following customer-specific logs are available:

Exchange Tools

The Payroll Console provides the following commands for data exchange:

Command Description
PayrollImport Import regulations, company and employee data (JSON, YAML) with zip-archive support
RegulationExcelImport Import regulations from Excel workbooks (cases, wage types, lookups, reports, scripts)
PayrollExport Export regulations, company and employee data selectively
PayrollConvert Convert payroll files between JSON and YAML (supports file masks and recursive conversion)
Report Data reports in XML, Excel and PDF
DataReport Data reports in JSON

See Client Services for the complete list of Payroll Console commands.