Worked Examples
Concrete examples of how allowance inputs become calculated lines.
Example 1: Site allowance by project flag
Configuration:
{
"clientAllowance": {
"name": "Site Allowance",
"amountUnit": "daily",
"amount": "25.00",
"triggerType": "project_flag",
"applicationMode": "auto"
},
"projectAllowance": {
"name": "Site Allowance",
"apply": true,
"rate": "30.00"
}
}Timesheet has entries on Monday and Tuesday.
Result:
quantity = 2.00
unitRate = 30.00
amount = 60.00
reason = project flag matched through project applicabilityThe project rate wins over the client allowance amount.
Example 2: Long shift meal allowance
Configuration:
{
"name": "Long Shift Meal Allowance",
"amountUnit": "daily",
"amount": "18.50",
"triggerType": "shift_hours_over",
"triggerConfig": { "thresholdHours": 10 },
"applicationMode": "auto"
}Entries:
| Date | Start | Finish | Hours |
|---|---|---|---|
| Monday | 07:00 | 17:00 | 10.0 |
| Tuesday | 07:00 | 17:30 | 10.5 |
Result:
Monday does not trigger because the code uses hours > threshold.
Tuesday triggers because 10.5 > 10.
quantity = 1.00
amount = 18.50Example 3: Personal vehicle use
Configuration:
{
"name": "Personal Vehicle Use",
"amountUnit": "daily",
"triggerType": "vehicle_type",
"triggerConfig": { "vehicleType": "P" },
"applicationMode": "auto"
}The calculator checks TimeEntry.vehicleType case-insensitively against configured vehicleType. If an entry's vehicle type is P, that entry can contribute to the daily count. If the vehicle type is C, no line is generated for that entry.
Example 4: Manual travel selection
Configuration:
{
"name": "Travel Allowance",
"amountUnit": "daily",
"triggerType": "manual_selection",
"applicationMode": "manual",
"amount": "45.00"
}Time entry payload:
{
"allowancesData": [
{ "name": "Travel Allowance", "quantity": 2 }
]
}Result:
application mode is not auto, so selection is required.
selected allowance name matches client allowance name after normalization.
quantity = 2.00
unitRate = 45.00
amount = 90.00Example 5: Daily-or-weekly tool allowance
Configuration:
{
"name": "Tool Allowance",
"amountUnit": "daily_or_weekly",
"amount": "12.00",
"triggerType": "always",
"triggerConfig": {
"weeklyThresholdDays": 5,
"weeklyAmount": 50
},
"applicationMode": "auto"
}If the worker has entries on three unique dates, the selected mode is daily:
quantity = 3.00
unitRate = 12.00
amount = 36.00If the worker has entries on five or more unique dates, the selected mode is weekly:
quantity = 1.00
unitRate = 50.00
amount = 50.00Example 6: Distance from depot
Configuration can provide a direct distance:
{
"triggerConfig": {
"distanceThresholdKm": 50,
"distanceFromDepotKm": 73
}
}Or it can provide coordinates through trigger config, timesheet location, or project location metadata. The calculator computes a haversine distance and compares it to the threshold.
applies when distanceKm >= thresholdKmLiving-away-from-home allowance names are special-cased and pass the distance trigger even when distance metadata is absent.