Create a timesheet-based Payroll Application

This article describes how the Payroll Engine is used to develop a payroll solution based on a variable timesheet. The Payroll Engine is an open source project that enables the development of scalable cloud payroll solutions. The following requirements were considered: Support for different payroll periods: weekly, bi-weekly, monthly, bi-monthly, etc. Wage factor for casual workers. Variable daily rates divided into regular working hours and early/late periods. Parallel use of timesheets with different working time models. Timesheet data can be changed daily, scheduled and time limited. Customization of wage calculation with individual additional rates and factors. Automated payroll testing. Definition of special days (public holidays, trade fair, etc.). Integration of external working hours from Excel documents. Report on employee working hours and wages by period. Use Cases The application covers the following use cases: Timesheet: Configure timesheet Employment: Manage employee employment Work Time: Record employee work time Payrun: Perform wage calculation Wage Report: Create employee wage document Work Time Report: Create employee working time report Working times are recorded by the employee themselves (self-service) or by the HR user. Timesheet The timesheet describes the working time and basic wage data: Field Description Value type StartTime Regular period start time Hour EndTime Regular period end time Hour MinWorkTime Minimum work time Hour MaxWorkTime Maximum work time Hour BreakMin Minimum break time Minute BreakMax Maximum break time Minute RegularRate Regular hour rate Money CasualRateFactor Casual worker factor to the regular rate Percent Time Periods In the timesheet, the working day is divided into different time periods: Regular period: Start and end of the working day and pay rates Early periods: Working periods from midnight to the start of regular working hours Late periods: Working periods after the regular working time until midnight The periods are arranged according to the sort key next to the standard working time. Negative sort values apply to early periods and positive sort values to late periods. The following standard fields exist for each period: Field Description Value type Duration Period duration Hour Factor Period rate factor Percent Work Time The employee's working time is defined in the WorkTime object with the following standard fields: Field Description Value type WorkTimeDate Working day Date WorkTimeStart Start hour Hour WorkTimeEnd End hour Hour WorkTimeBreak Break time Minute WorkTimeHours Working hours (calculated) Minute Wage Calculation To calculate the daily wage, the average working time is divided into different periods. The period wage is calculated according to the duration of work within the period and the wage factors. The total daily wage is calculated from the wage of the regular working time and all early and late periods. The following example shows the distribution of the employee's working time between the daily periods. The employee has worked from 9.00 to 20.00 with a break of 30 minutes: Application Usage The use cases are executed in the Payroll Engine web application: First, the timesheet is defined using the Timesheet use case and the employee's employment type is defined using the Employment use case. The employee's working and break times are then recorded using the Work Time use case: Break times are optional and can be hidden. Authorized users can also run these cases for forecast scenarios. When a pay run job is executed, the payroll data for the employees is created and saved as Payroll Results. The employees' working times and the payroll results can be downloaded in various formats (pdf, excel, json, xml). Special days import Special days, such as public holidays to be excluded or weekend days to be included, such as trade fairs, are managed in the Workday lookup. The special days can also be imported from an Excel file using the Payroll Console (see example Lookup/Workday/Workdays.2025.xlsx). Working hours import For employees who do not have online access, the Payroll Console can also be used to import the working times of employees who have Online (see example Case.Data/WorkingTimes.2025.Week8.xlsx). Implementation Tenant Setup The payroll calendar, which determines the payroll cycle and the regular working days, is defined in the client. The users are assigned to divisions. The calendar determines the payroll cycle and the working days. Employees, who are also entered as users, can record and query their working time. The payroll data is managed in the regulation object: Lookup tables such as the special days. Cases and their fields, which define the data model. Wage types and collectors for the wage run. Evaluation with reports.

Mar 27, 2025 - 11:28

Create a timesheet-based Payroll Application

This article describes how the Payroll Engine is used to develop a payroll solution based on a variable timesheet.
The Payroll Engine is an open source project that enables the development of scalable cloud payroll solutions.

The following requirements were considered:

Support for different payroll periods: weekly, bi-weekly, monthly, bi-monthly, etc.
Wage factor for casual workers.
Variable daily rates divided into regular working hours and early/late periods.
Parallel use of timesheets with different working time models.
Timesheet data can be changed daily, scheduled and time limited.
Customization of wage calculation with individual additional rates and factors.
Automated payroll testing.
Definition of special days (public holidays, trade fair, etc.).
Integration of external working hours from Excel documents.
Report on employee working hours and wages by period.

Use Cases

The application covers the following use cases:

Timesheet: Configure timesheet
Employment: Manage employee employment
Work Time: Record employee work time
Payrun: Perform wage calculation
Wage Report: Create employee wage document
Work Time Report: Create employee working time report

Working times are recorded by the employee themselves (self-service) or by the HR user.

Timesheet

The timesheet describes the working time and basic wage data:

Field	Description	Value type
`StartTime`	Regular period start time	Hour
`EndTime`	Regular period end time	Hour
`MinWorkTime`	Minimum work time	Hour
`MaxWorkTime`	Maximum work time	Hour
`BreakMin`	Minimum break time	Minute
`BreakMax`	Maximum break time	Minute
`RegularRate`	Regular hour rate	Money
`CasualRateFactor`	Casual worker factor to the regular rate	Percent

Time Periods

In the timesheet, the working day is divided into different time periods:

Regular period: Start and end of the working day and pay rates
Early periods: Working periods from midnight to the start of regular working hours
Late periods: Working periods after the regular working time until midnight

The periods are arranged according to the sort key next to the standard working time. Negative sort values apply to early periods and positive sort values to late periods.

The following standard fields exist for each period:

Field	Description	Value type
`Duration`	Period duration	Hour
`Factor`	Period rate factor	Percent

Work Time

The employee's working time is defined in the WorkTime object with the following standard fields:

Field	Description	Value type
`WorkTimeDate`	Working day	Date
`WorkTimeStart`	Start hour	Hour
`WorkTimeEnd`	End hour	Hour
`WorkTimeBreak`	Break time	Minute
`WorkTimeHours`	Working hours (calculated)	Minute

Wage Calculation

To calculate the daily wage, the average working time is divided into different periods. The period wage is calculated according to the duration of work within the period and the wage factors. The total daily wage is calculated from the wage of the regular working time and all early and late periods.

The following example shows the distribution of the employee's working time between the daily periods. The employee has worked from 9.00 to 20.00 with a break of 30 minutes:

Application Usage

The use cases are executed in the Payroll Engine web application:

First, the timesheet is defined using the Timesheet use case and the employee's employment type is defined using the Employment use case. The employee's working and break times are then recorded using the Work Time use case:

Break times are optional and can be hidden. Authorized users can also run these cases for forecast scenarios.
When a pay run job is executed, the payroll data for the employees is created and saved as Payroll Results.

The employees' working times and the payroll results can be downloaded in various formats (pdf, excel, json, xml).

Special days import

Special days, such as public holidays to be excluded or weekend days to be included, such as trade fairs, are managed in the Workday lookup. The special days can also be imported from an Excel file using the Payroll Console (see example Lookup/Workday/Workdays.2025.xlsx).

Working hours import

For employees who do not have online access, the Payroll Console can also be used to import the working times of employees who have Online (see example Case.Data/WorkingTimes.2025.Week8.xlsx).

Implementation

Tenant Setup

The payroll calendar, which determines the payroll cycle and the regular working days, is defined in the client. The users are assigned to divisions. The calendar determines the payroll cycle and the working days. Employees, who are also entered as users, can record and query their working time.

The payroll data is managed in the regulation object:

Lookup tables such as the special days.
Cases and their fields, which define the data model.
Wage types and collectors for the wage run.
Evaluation with reports.