Entitlement Logic

Entitlement Logic defines how employee time off and activity-based entitlements are evaluated and consumed when employees submit requests or when managers perform related shift or request changes.
Before any entitlement can be used, the system evaluates three foundational conditions.

1. Planning Context

The system first determines where the request or shift-change interval sits within the roster lifecycle.
This defines whether entitlement balances may be evaluated or modified.

Finished Roster

• Entitlement-based requests cannot be created.
• Shift changes are allowed, and entitlements may be adjusted only when the shift change requires entitlement consumption.

Published / Effectively Published Roster

• Entitlement adjustments are allowed only if a shift exists on the affected day.
• If no shift exists, entitlement balances remain unchanged.

Unpublished Roster

• All entitlement evaluations and adjustments are possible for both requests and shift changes.

1. Roster Type Context (Public vs. Working Roster)

For the working roster, just like with the public roster, the year is divided into the three periods described earlier.
The only difference in entitlement calculation occurs in the Unpublished period.

Pending and Auto-Approved Requests

• On days where a shift exists, entitlement logic follows the shift.
• On days where no shift exists, the request is ignored for entitlement calculation.

1. Activity Type

The system evaluates whether the activity is linked to an entitlement.

• If the activity is not linked to an entitlement, no entitlement processing occurs.
• If the activity is linked to an entitlement, the entitlement deduction process is applied.

Entitlement Deduction Process

Once the context allows changes and the activity requires an entitlement, the system determines how entitlements are consumed.
This process applies to both employee requests and shift changes.

General Eligibility Rule

An entitlement is considered only if its Validity overlaps the request or shift-change interval by at least one day.
This rule applies to all entitlements, including prerequisite and main entitlements.

Phase 1: Prerequisite Entitlements

Some activities require other entitlement types to be fully consumed before the requested entitlement may be used.
Prerequisites are defined in:
RosterItemsPart (Time off Types or Activity) → Rules tab → fields:

• Depleted Entitlements
• Depleted Past Entitlements

These fields define which prerequisite entitlements are included in prerequisite evaluation.
They do not define consumption order.

Prerequisite pool

The system forms a prerequisite pool consisting of entitlement allocations that:

• belong to the employee,
• satisfy the general eligibility rule,
• (for Depleted Past Entitlements) have a Period that has already ended, and
• have a remaining balance greater than zero.

All prerequisite entitlements are combined into a single pool.

Prerequisite consumption

All prerequisite entitlements must be fully consumed before any main entitlement is considered.
Within the prerequisite pool, entitlements are consumed in order of earliest Period.Start, consuming each entitlement up to its full available balance before moving to the next.

Phase 2: Main Entitlements

Once the prerequisite pool is fully depleted, the system evaluates the requested entitlement type.
The system considers entitlement allocations that:

• belong to the employee, and
• satisfy the general eligibility rule.

Eligible main entitlements are consumed in order of earliest Period.Start, consuming each entitlement up to its full available balance before moving to the next.

Entitlement Consumption

Entitlements are consumed according to the rules defined above.

• Entitlements are processed sequentially in the applicable order.
• For each entitlement, deduction is applied up to the full available balance.
• If the required amount is not yet fully covered, consumption continues with the next entitlement in the same order.
• Entitlement balances are updated accordingly.

Entitlement state records are not created during consumption; they are imported or generated later during attendance state finalization.
After entitlement consumption completes, processing continues according to standard request or roster handling.

Entitlement Calculation Types

Calculation types for the employee entitlements, deduction, balance a state reporting.

Calculation types

• Entitlement: Sum of values of employee entitlements with validity overlapping the reporting period and filtered by EntitlementPeriod parameter.
  • Parameters:
    • EntitlementPeriod
• EntitlementBalance: Calculated employee entitlement balance with validity overlapping the reporting period and filterd by EntitlementPeriod paremeter as of the BalanceDate.
  • Parameters:
    • EntitlementPeriod
    • BalanceDate
    • Add DuductionItems parameter to this calculation type - Albert needs balance from current year without not aproved request
• EntitlementDeduction: Calculated entitlement deduction by DeductionItems types from employee entitlements with validity overlapping the reporting period, filtered by EntitlementPeriod. The deduction is calculated from the reporting period overlap with the month if specified in the Month parameter.
  • Parameters:
    • EntitlementPeriod
    • DuductionItems
    • Month
  • Use cases:
    • EntitlementDeductions (with EntitlementPeriod: ReportingPeriodPastYears): since the deduction is calculated for the reporting period, the employee entitlements valid within the reporting period should be considered. The EntitlementPeriod parameter filters the employee entitlements for which the deduction is calculatet by the period.
  • Reported bug:
    • EntitlementDeduction is calculated independenlty for Roster Items, Aproved Requests, Pending/Auto Requests if htey are in individual metrics. If we want to calculate deduction from this year entitlement for individual Deduction Item Types, the deduction from previous years is substracted from all of this metrics, not just from the earlier items until the balance from previous years is zero.
• EntitlementBalanceState: Sum of last stored balance states of employee entitlemtns with validity overlapping the reporting period filtered by EntitlementPeriod parameter.
  • Parameters:
    • EntitlementPeriod

Calculation field parameters

EntitlementPeriod (string): The employee entitlement allocations selector based on the allocation period.

• Options
  • Total (default): All employee entitlements.
  • ReportingPeriod: Employee entitlements with period overlapping reporting period.
  • ReportingPeriodYear: Employee entitlements with period overlapping the whole reporting period year.
  • ReportingPeriodPastYears: Employee entitlements with period overlapping any year before the reporting period year.
• Used in calcucation types: Entitlement, EntitlementBalance, EntitlementDeduction, EntitlementBalanceState

BalanceDate (string): .

• Options
  • EntitlementValidityEnd (default): The selected employee entitlement balance is calculates as of their last validity end.
  • ReportingPeriodEnd: The selected employee entitlement balance is calculates as of the reporting period end.
• Used in calcucation types: EntitlementBalance

DuductionItems (string): Specifies the item types for them the deduction is calculated.

• Options
  • All (default): The deduction is calculated from all item types.
  • PublicShifts: The deduction is calculated from public shift only.
  • PublicShiftsWithApprovedRequests: The deduction is calculated from public shift and Approved requests.
  • ApprovedRequests: The deduction is calculated from Approved requests only.
  • PendingAutoRequests: The deduction is calculated from Pending/Auto requests only.
• Used in calcucation types: EntitlementDeduction

Month (int): Specifies the month for which the deduction is calulated. Default null value means that the month filter is not applied.

• Used in calcucation types: EntitlementDeduction

Example JSON

{
"EntitlementPeriod": "ReportingPeriod",
"BalanceDate": "ReportingPeriodEnd",
"DuductionItems": "PublicShiftsWithApprovedRequests",
"Month": 1
}