Allowance Triggers
Allowance Triggers
AllowanceTriggerType defines the trigger vocabulary used by the calculator.
Trigger table
| Trigger | Config keys | Applies when | Quantity behavior |
|---|---|---|---|
always | none | Entry exists and application mode rules pass. | Depends on unit: hours, days, one week, etc. |
shift_hours_over | thresholdHours | Entry hours are greater than the threshold. This is strict >, not >=. | Usually matched entry hours or matched day count. |
project_flag | project allowances_data.apply | Project has a matching allowance row with apply true. | Depends on unit. |
timesheet_flag | value, flag, or slug | Entry work condition name, slug, or id matches the configured token. | Depends on unit. |
distance_from_depot | distanceThresholdKm, thresholdKm, depot/site coordinates | Timesheet/project metadata distance is greater than or equal to threshold. Living-away-from-home allowances bypass missing distance metadata. | Depends on unit. |
overtime_hours | dailyThresholdHours, thresholdHours, weeklyThresholdHours | Calculated overtime hours are greater than zero. | Quantity is overtime hours only. |
normal_time_hours | dailyThresholdHours, thresholdHours | Calculated normal hours are greater than zero. | Quantity is normal hours only. |
vehicle_type | vehicleType | Entry vehicle type equals the configured token, case-insensitive. | Depends on unit. |
manual_selection | entry selected allowance name | The allowance is selected on the entry. | Quantity is selected quantity or one. |
Application mode gate
Before trigger matching, isEntryTriggered() applies an application-mode gate:
if application mode is not auto and entry does not have a selected matching allowance:
trigger is falseThat means selectable_timesheet and manual allowances must be selected by the user before any trigger logic can apply. Auto allowances can apply without user selection.
Work condition matching
timesheet_flag reads triggerConfig.value, triggerConfig.flag, triggerConfig.slug, and triggerConfig.vehicleType through readTriggerNeedles(). If no needles are configured, the allowance name is used. It compares normalized strings against each work condition's name, slug, and id.
Distance behavior
distance_from_depot can use:
- explicit distance in trigger config
- timesheet location metadata
- project location metadata
- site and depot coordinates, using a Haversine distance calculation
Living Away Home Allowance and Living Away From Home Allowance are special-cased to match without distance metadata.
Overtime vs normal-time triggers
Overtime hours are calculated per date above a daily threshold, with an optional weekly threshold. If a weekly threshold exists, the calculator uses the maximum of daily overtime and weekly overtime.
Normal time hours are the sum of min(day hours, daily threshold) for each worked date.