Calendars

Payroll Calendars

The payroll calendar describes how payroll runs are mapped to the calendar. The system culture serves as the basis. The payroll calendar determines the frequency of wage payments through the wage cycle, the wage period, and the weekly and annual definitions. Each tenant has one or more calendar definitions that are referenced by different objects.

The payroll calendar is the basis for case fields with the time type Period and CalendarPeriod.

Calendar Types

The payroll calendar divides business data into two time units:

• Period — the interval in which the salary is paid, usually the calendar month (PeriodTimeUnit).
• Cycle — the interval in which the salary periods repeat, usually the calendar year (CycleTimeUnit).

The cycle time unit is always a multiple of the period time unit.

The following overview shows the possible combinations of the two time units with the number of wage payments per cycle.

Cycle → Period ↓	Week	Bi-Week	Semi-Month	Lunar-Month	Month	Bi-Month	Quarter	Semi-Year	Year
Week	1	2	-	4	-	-	13	26	52
Bi-Week	-	1	-	2	-	-	-	13	26
Semi-Month 3)	-	-	1	-	2	4	6	12	24
Lunar-Month	-	-	-	1	-	-	-	-	13
Month 1)	-	-	-	-	1	2	3	6	12 4)
Bi-Month 2)	-	-	-	-	-	1	-	3	6
Quarter 2)	-	-	-	-	-	-	1	2	4
Semi-Year 2)	-	-	-	-	-	-	-	1	2
Year 2)	-	-	-	-	-	-	-	-	1

¹⁾ Override the effective number of days in the calendar month with a configurable average.
²⁾ Fiscal years with the year starting on any calendar month.
³⁾ Month breakdown: 1 to 15 and 16 to end of month.
⁴⁾ Default payroll calendar.

Calendar Example

Example of different payroll calendars:

1   "calendars": [
2     {
3       "name": "YearlySalary",
4       "cycleTimeUnit": "Year",
5       "periodTimeUnit": "CalendarMonth",
6       "timeMap": "Cycle"
7     },
8     {
9       "name": "MonthlySalary",
10      "cycleTimeUnit": "Year",
11      "periodTimeUnit": "CalendarMonth",
12      "timeMap": "Period"
13    },
14    {
15      "name": "QuarterSalary",
16      "cycleTimeUnit": "Year",
17      "periodTimeUnit": "Quarter",
18      "firstMonthOfYear": "April",
19      "timeMap": "Period"
20    }
21  ]

The calendars in detail:

• 3: Custom calendar name YearlySalary
• 4: Cycle time unit is Year
• 5: Period time unit is CalendarMonth
• 6: Values apply to the cycle: annual wages
• 9: Custom calendar name MonthlySalary
• 10: Cycle time unit is Year
• 11: Period time unit is CalendarMonth
• 12: Values apply to the period: monthly wages
• 15: Custom calendar name QuarterSalary
• 16: Cycle time unit is Year
• 17: Period time unit is Quarter
• 18: Start of the fiscal year is April
• 19: Values apply to the period: quarterly wages

Calendar Resolution Order

The calendar is resolved during the payrun according to the following priority:

1. Wage Type
2. Employee
3. Division
4. Tenant

World Time

All date values in the REST API must be specified in UTC. Other time zones will result in errors.

Calendar Configuration

The calendar is configured with the following settings:

• Cycle time unit
• Period time unit
• Time mapping — cyclic or periodic, examples:
  • Cycle=Year, Period=Month, Base value=60,000 → Payroll value=5,000
  • Cycle=Semi-year, Period=Bi-Week, Base value=52,000 → Payroll value=4,000
• First month of year for fiscal years (default: January)
• Rule for determining the first week of the year
• First day of the week (default: Monday)
• Average number of days in a month
• Definition of working days in a week (e.g. Monday to Friday)

Payrun Time Value Calculation

When calculating a period value, all relevant mutations within the period are distributed proportionally according to the calendar (e.g. mid-month salary adjustments). The Scripting API provides access to the calendar's distribution logic, which significantly simplifies the calculation syntax. Two case values with different mutations can be combined using the standard mathematical operators (addition, subtraction, multiplication, division).

See Time Data for details on time types and time calculations.