PayrunModel

Payrun Model

The creation of payrun objects requires that the case model is in place. The following procedure is recommended for modeling:

1. Determine output values:
   • Payslip data
   • Legally required data (monthly, annual)
   • Data for downstream systems such as financial accounting
2. Break down output values into:
   • Wage types: each represents one calculation step for an output value
   • Collectors: aggregation values derived from wage types
3. Determine wage types with their processing order
4. Determine collectors and assign wage types to them
5. Determine clusters and assign them to wage types (optional)

Wage Types and Collectors

Wage types are typically executed in the following order:

1. Income and benefits
2. Gross salary
3. Deductions and expenses
4. Net salary
5. Consolidated values (Collectors)

To simplify access to payroll results, step 5 additionally maps collector results as wage types.

The next step is to define the wage type number ranges:

Wage Type Range	Scope
1000 - 4999	Income and benefits
5000 - 5009	Gross salary
5010 - 6499	Deductions and expenses
6500 - 6599	Net salary
6600 - 9099	Consolidated values

To document wage types and collectors, it is advisable to create an assignment matrix. The following example shows such a matrix:

Wage Type #	Wage Type Name	Gross Salary Collector	Withholding Tax Collector
1000	Monthly wage	yes	yes
...	...	.	.
1005	Hourly wage	yes	yes
...	...	.	.
1980	Further education	yes	no
...	...	.	.
5000	Gross salary	no	no
...	...	.	.
6500	Net salary	no	no
...	...	.	.
9070	Withholding tax	no	no

In this example, the withholding tax collector result is exposed as wage type 9070.

The matrix can be extended for special cases:

• Additional clustering columns
• Collectors can be grouped for complex scenarios

Sub Wage Types

Wage types are calculated in numerical order, which allows sub-wage types to be defined.

In the following example, sub wage type 1000.1 calculates the year-to-date value of wage type 1000:

Wage Type #	Wage Type Name	Calculation Formula
1000	Monthly wage	...
1000.1	Monthly wage year-to-date	Total of wage type 1000 across all cycle periods

Sub wage types with complex data queries can be excluded using clustering.

Payrun with Multiple Calendars

The calculation of wage data is based on the calendar assigned to the employee, division or tenant. In situations where a payrun must handle different calendars, this can be configured per wage type:

Wage Type #	Wage Type Name	Calendar
1000	Monthly wage	Monthly payroll calendar
1001	Bi-week wage	Bi-week payroll calendar

Additional Payroll Results

Additional payroll results can be stored as:

• Wage type result attributes — best performance
• Custom wage type results — easy to query
• Payrun results — for non-numerical or arbitrary data

Low-code example: set a custom attribute in the wage type value expression.

SetResultAttribute("MyAttribute", 2560)

Low-code example: add a custom result in the wage type value expression.

AddCustomResult("MySource", 9217)

No-code example: set a payrun result using a wage type value action.

^|MyPayrunResult = PeriodStartDate

Payrun Job

The payrun job starts the payrun for a pay period and stores the results in the payroll result. The underlying payroll uses the employee's division assignment to determine whether the employee is included.

A payrun job defines the purpose of execution:

• Statutory payroll run
• Forecast analysis of payroll data for projections, scenario planning, etc.

The payrun job is controlled by its job status:

Job Status	Type	Description	Webhook
*		New payrun job
Draft	Working	Statutory payrun job for preview
Release	Working	Statutory payrun job released for processing
Process	Working	Statutory payrun job in processing	PayrunJobProcess
Complete	Final	Statutory payrun job successfully completed	PayrunJobFinish
Forecast	Final	Forecast payrun job
Abort	Final	Statutory payrun job aborted before release
Cancel	Final	Statutory payrun job failed during processing	PayrunJobFinish

For statutory payruns, only one job in Draft status is allowed per payrun type and pay period. Multiple jobs with Release or Process status are possible. Forecast payruns can be executed any number of times.

Payrun Restart

During the payrun, all wage types are processed in the order of their wage type numbers. In special cases, the payrun can be restarted for an individual employee. Each run is identified in the wage type by a run counter. Runtime values (see Payrun Scripting) can be used to exchange data between runs.

See Testing for how to verify payrun behavior with automated tests.

Payroll Results

The results of the payrun are stored in the following objects:

Object	Description
Collector Result	The aggregated decimal result of a collector
Collector Custom Result	User-defined collector result (decimal)
Payrun Result	Payrun-specific result, including non-numerical values
Wage Type Result	The wage type result (decimal) including custom attributes
Wage Type Custom Result	User-defined wage type result (decimal)

Cluster sets in the payroll configuration control which results are generated (see Clusters).

Incremental Payrun

When multiple payruns are executed within a single period, the engine stores only incremental results — values that have changed since the last payrun. The REST API provides dedicated endpoints to retrieve the currently valid (consolidated) results for a pay period.

Retroactive Calculation

Retroactive calculations are triggered automatically when mutations have occurred after the last payrun that affect prior pay periods.

The retroactive calculation steps are:

1. Calculate the current pay period (accounting for mutations into prior periods)
   • Execution phase: Setup
   • Results are transient
2. Calculate all affected prior periods, starting from the earliest mutation period
   • Store incremental results for each prior period
3. Recalculate the current pay period
   • Execution phase: Reevaluation
   • Consolidated results include prior retroactive results
   • Store final results

For forecasts, prior runs with the same forecast name apply. The number of retroactive periods is unlimited; however, retroactive calculation can be restricted to the current payroll cycle.

Manual Retroactive Calculation

In addition to automatic retroactive calculation, a retroactive payrun can also be triggered manually via scripts. Results generated during retroactive calculation are tagged with Payroll Result Tags, which can be used as filter criteria when querying payroll results.

The following scenario shows a current-period payrun triggering two retroactive payruns:

Next Steps

• Regulation Design guidelines
• Lookups design guidelines
• Case Model design guidelines