Understand irregular work schedules better

Modified on Thu, 23 Apr at 3:33 PM

This document details the technical logic applied to the Hours Summary module following the update of Scheduled hours and the Priority Chain. It is designed to help administrators and managers understand how hours are calculated and how to resolve visual discrepancies in the Time balance.

1. Glossary of Terms

Term	Definition / Usage
Contracted hours (Mindestarbeitszeit)	The standard hours an employee is expected to work according to their contract (Gross).
Contracted weekly hours	The base weekly hours defined in the legal agreement.
Required hours (Sollstunden)	The hours an employee must work in a period, after deducting public holidays and paid absences (Net Expected Time).
Scheduled hours (Geplante Stunden)	The hours assigned via shift-based time tracking or work schedules.
Tracked time (Iststunden)	The actual time an employee has worked (clock-ins).
Ordinary time (Reguläre Stunden)	Tracked time minus unpaid breaks (Effective time).
Time Sheets (Stundenübersicht)	The historical overview of all logs and recorded time.

2. Contracted vs. Required Hours

The fundamental difference lies in the concept of Gross vs. Net.

Contracted hours (Gross): The time agreed upon in the contract (e.g., 40h/week). It is a static value defined in the Employee profile.
Required hours (Net): The time the employee actually needs to fulfill. It is calculated by subtracting paid absences and paid public holidays from the contracted hours.

Can they be equal? Yes. Both values are identical during periods with no paid absences or holidays.

Deduction Calculation: The system divides the Contracted hours by the defined Working Days to obtain the daily deduction base.
Example: 40h / 5 days = 8h deduction per holiday. If a month has 128h contracted and 2 holidays, Required hours = 112h.

3. Contracted vs. Scheduled Hours

This is the distinction between legal obligation (Contract) and operational planning (Shift Plan).

Contracted hours: Static value. It represents the fixed legal agreement.
Scheduled hours: Dynamic value. Represents the specific hours a manager assigns. Determined by the Priority Chain (Shift Plan > Work Schedule > Contract).

Feature	Contracted hours	Scheduled hours
Nature	Legal / Administrative	Operational / Practical
Flexibility	Static	Dynamic

4. Required vs. Scheduled Hours

Required hours (Net expected time): The daily portion of the contract that the employee needs to "fill" to comply legally. It is based on a fixed daily average (e.g., 8h).

Scheduled hours (The plan): The specific shift assigned. It can be variable (e.g., 10h on Monday, 6h on Friday) depending on operational needs.

5. Why don't they match mid-week?

Required hours are independent of daily planning to ensure equitable deductions. If a holiday falls on a day where a 10h shift was planned, the system credits the contractual average (e.g., 8h). This maintains contractual integrity and ensures the Time balance isn't unfairly affected by specific shift distributions.

6. System Limits and Balances

The system constantly monitors thresholds defined in the profile:

Contracted weekly limit: Maximum hours allowed per week.
Legal daily limit: Maximum hours allowed per day.

Comparison between Ordinary time and Required hours results in the Time balance:

Time surplus (Zeitplus): Tracked time exceeds required hours.
Time deficit (Zeitminus): Tracked time is less than required hours.

7. Why does Scheduled hours show 0h?

If shift-based time tracking is active, the system follows a strict priority. If a manager has not published shifts for that day, the system assumes the employee is not expected to work (0h).

8. Logic for Future Absences (My time off)

To allow employees to request My time off (vacations) in advance when shifts haven't been created yet, the system uses Contracted hours as a fallback. It distributes the weekly hours proportionally among working days to ensure requests are not blocked.