Regulations
Regulations reduce the complexity of payroll software by splitting it into layers. Unlike networked architectures (e.g. microservices), the components of the Payroll Engine are stacked in a layered model. Each layer contains models, calculations and evaluations. Object inheritance concepts allow information to be overridden and extended.
Regulations can be shared between tenants, which saves resources and greatly simplifies deployment. The Payroll Console can be used to import, export and test regulations. The Web Application supports editing regulations while respecting the inheritance hierarchy.
A regulation covers the following subject areas:
- Definition of the data model and business rules, see Case Fields
- Calculation of payroll data, see Payrun
- Evaluation of company and employee data, see Reports
- Testing company and employee data, see Testing
- Extending existing regulations, see Regulation Design
- Sharing regulations between tenants, see Regulation Sharing
- Deploying regulations, see Regulation Deployment
A regulation consists of the following objects:
| Object | Description | Features |
|---|---|---|
Case |
Wage-relevant event of an employee 1) | - Case availability - Container for input fields |
CaseField |
Data field of a case | - Unique field name - Data and time type - Control of user input |
CaseRelation |
Relationship between two cases | - Conditional relationship - Relationship to cases in other regulations |
Collector |
Aggregation of payrun results | - Aggregation type (default: sum) - Group collectors - Custom results |
WageType |
Wage type in the payrun | - Wages, deductions and contributions - Numbered processing sequence - Custom results |
Report |
Data evaluation and exchange | - Dynamic report parameters - Multilingual report templates - Raw data reports |
Lookup |
Data tables from external sources 2) | - Values by key - Multilingual values - Values for number ranges |
Script |
Shared functionality in C# | - Assignment to Functions - Custom Actions |
1) There are four case types: Employee, Company, National and Global.
2) External data should be kept in isolated regulations to ensure correct time data through versioning.
Each regulation object has the following properties:
- Audit trail of all changes
- Object can be deactivated and will no longer be evaluated
- Extensible with user-defined attributes
- Unique override key for inheritance
To avoid naming conflicts between regulations, each regulation is assigned a namespace. This can be a country and/or industry code. When a namespace is defined, it is automatically applied when creating and updating regulation objects. Object references into another regulation are not affected.
| Example | Value |
|---|---|
| Namespace | US |
| Object name | Salary |
| Stored as | US.Salary |
Object names can also be fully qualified to reference a specific namespace explicitly (e.g. CA.Salary). This convention significantly improves the readability of regulation scripting.
Regulations are based on the principle of inheritance: an object in a regulation can be overridden by an object in a higher-level regulation. The object to be overridden is identified by its override key:
| Object | Override Key |
|---|---|
Case |
Case name |
CaseField |
Case field name |
CaseRelation |
Source and target case names |
Collector |
Collector name |
WageType |
Wage type number |
Report |
Report name |
Report Parameter |
Parameter name |
Report Template |
Template name |
Lookup |
Lookup name |
Lookup Value |
Lookup value key |
A cluster is used to select or exclude regulation objects according to defined criteria. This is done using a tagging mechanism with whitelist and blacklist tags. Clusters can be used to:
- Group and filter objects such as cases and reports (e.g. in the web application)
- Narrow down the available case data in the payrun
- Optimize results in retroactive calculations
Actions can be used to control data entry and validation without programming knowledge. Like Excel functions, an action is a predefined function that can also be executed conditionally — analogous to the Excel IIf() function. Actions have access to case values, lookup tables, collectors and wage types.
See No-Code/Low-Code for an overview of available actions. Custom Actions are also possible as part of a regulation.
The runtime behavior of the Payroll Engine is determined by functions. Each regulation object provides corresponding functions — for example, the Wage Type Value function from the Wage Type object. A function is defined by C# code (script expression).
C# scripts for case and report functions can also be executed and debugged locally.
The following scenarios are supported by payroll regulations:
- Development of customer-specific regulations during onboarding
- Service providers offering commercial regulations
- Industry solutions such as association-wide payroll standards
- Country-specific and statutory payroll processing
- Company regulations, local or transnational
- Regulations for testing and further development
Regulations can be published on platforms such as GitHub under the desired license. Various commercialization options are available, such as a private repository that is unlocked for a fee.
A regulation consists of JSON, C# and report files that can be distributed as compressed zip archives. Regulations with extended functions are distributed as NuGet packages, which include versioning and dependency management for other regulations.
The following tools are available for developing regulations:
- Web App — Prototyping of a payroll solution with a modern user interface
- Payroll Console — Development using JSON/C# files, including version management and tests
- Visual Studio, VS Code — Development of complex payroll solutions in .NET projects, including version management, tests and debug support
- Payroll Model
- Payroll Automation
- Regulation Design guidelines
🤝 Thank you for supporting this project with a donation.
⚡ This is a pre-relase version of the initial development, please read the restrictions.
