TechnicalIntegration

Payroll Engine Technical Integration

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:

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.

Technologies

The following technologies are used in the Payroll Backend:

Component	Technology
REST API	OpenAPI 3.1 (OAS3.1), media type application/json
Scripting API	C# 14
Applications	.NET 10
Database	SQL Server 2017 or newer
Development packages	NuGet Packages
Application packages	Zip download or Docker Container

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:

• Payrun logs (see Payrun Scripting)
• Report logs (see Report Logs)

Exchange Tools

The Payroll Console provides the following commands for data exchange:

Command	Description
PayrollImport	Import regulations, company and employee data (case data) with support from zip-archive
PayrollImportExcel	Import regulations, company and employee data (case data) in Excel documents
PayrollExport	Export regulations, company and employee data (case data) selectively
Report	Data reports in XML, Excel and PDF
DataReport	Data reports io JSON