Guides
Time off rules and the rules language
On this page
Time off rules are checked every time someone books or cancels time off, including when HR books for them. A company starts from one of 17 templates (notice, longest stretch, staffing, blackout periods…) or writes its own condition in the rules language described here. Owners, admins and HR manage rules in Time off → Rules; over the API and MCP they use the timeoff.rules actions.
Anatomy of a rule#
| Part | What it is |
|---|---|
| Condition | A template with its settings, or your own expression. When it is true, the rule applies. |
| Outcome | block refuses the booking (HR can still record it with override_rules), warn lets it through with the message, needs_approval sends it to the manager, then HR, even when approvals are off. |
| Checked when | Booking (applies_to: "booking") or cancelling ("cancellation"). |
| Scope | Everyone, or people who match every list you fill in: locations, teams, people. Leave types: all, or the ones you list. |
| Message | What people read when the rule applies: your text, with placeholders for dates and day counts. |
Every applicable rule is checked on every booking and every problem is reported, so the order of rules never matters. A rule that can't be decided (a value is missing, or it takes too long) never blocks anyone.
What a rule checks#
The variables a condition uses decide what it is checked against:
| Unit | When the condition uses | It is checked |
|---|---|---|
| Each day | day.*, team.* counts, employee.tenureMonths | once per working day booked; the days that break it are reported one by one |
| The booking | request.*, booking.*, employee.* | once for the whole booking |
| The leave year | balance.*, period.* | once per leave year the booking touches |
| The cancellation | cancellation.* | once per booking being cancelled |
Per-day and per-cancellation variables can't be mixed in one rule: make two rules. Booking variables don't exist when cancelling, and cancellation variables don't exist when booking; the check refuses a rule that uses them in the wrong kind.
Writing a condition#
Conditions are written in CEL, an expression language that can't loop forever or change anything.
request.bookedWorkingDays >= 5 && request.noticeDays < 14- Comparisons:
==!=<<=>>=; logic:&&||!; arithmetic:+-*/%; a condition? a : b. - Text in double quotes:
booking.ptoTypeId == "vacation". Dates areYYYY-MM-DDtext, so they compare in order:day.date >= "2026-12-01". inchecks a list:employee.countryCode in ["PT", "ES"].- Your own named numbers:
rule.params.max_days(set them on the rule; names use lower-case letters, digits and_).
Variables#
The booking#
| Variable | Type | What it is |
|---|---|---|
request.bookedWorkingDays | number | Working days booked |
request.startDate | date | First day booked (YYYY-MM-DD) |
request.endDate | date | Last day booked (YYYY-MM-DD) |
request.hasHalfDay | bool | True if a morning or an afternoon is booked |
request.hasHours | bool | True if some hours of a day are booked |
request.bookedHours | number | Hours booked as some hours of a day |
request.noticeDays | number | Days between today and the first day booked |
request.longestConsecutiveRun | number | Longest stretch of working days in a row, joining this booking to the person's other days off |
request.longestRequestedRun | number | Longest stretch of working days in a row within this booking |
request.shortestRequestedRun | number | Shortest stretch of working days in a row within this booking |
booking.ptoTypeId | string | Leave type being booked (its id, e.g. "vacation") |
booking.startDate | date | First day booked |
booking.endDate | date | Last day booked |
booking.daysRequested | number | Working days booked |
Each day booked#
| Variable | Type | What it is |
|---|---|---|
day.date | date | The day (YYYY-MM-DD) |
day.dayOfWeek | number | Day of the week: 0 Sunday, 1 Monday … 6 Saturday |
day.isWorkingDay | bool | True if it is a working day for the person |
day.noticeDays | number | Days between today and that day |
employee.tenureMonths | number | Whole months since the person started, on that day |
team.concurrentLeaveCount | number | Teammates away on that day (never shown to the person) |
team.membersRemaining | number | Teammates working on that day |
team.percentageOff | number | Percentage of the team away on that day |
team.percentageOffAfter | number | Percentage of the team away on that day, counting this booking |
The leave year#
| Variable | Type | What it is |
|---|---|---|
balance.entitlement | number | The person's allowance for the leave year (carried days and adjustments count in balance.available) |
balance.used | number | Days used or booked in the leave year |
balance.available | number | Days available before this booking |
balance.afterSession | number | Days available after this booking |
period.runs | list | The stretches of consecutive working days off in the leave year, with this booking or cancellation applied |
period.maxConsecutiveAvailableWorkingDays | number | Longest stretch of working days not yet booked in the leave year |
period.maxAchievableConsecutiveRun | number | Longest stretch of working days off the person could still reach this leave year, given what is booked and their balance |
Each item of period.runs has startDate, endDate and workingDays.
The person and the team#
| Variable | Type | What it is |
|---|---|---|
employee.hireDate | date | The person's start date (YYYY-MM-DD) |
employee.countryCode | string | Country of the person's location (ISO code, e.g. "PT") |
countryCode | string | Same as employee.countryCode |
team.memberCount | number | People in the person's team |
now | date | When the rule is checked (date and time) |
The booking being cancelled#
| Variable | Type | What it is |
|---|---|---|
cancellation.startDate | date | First day of the booking being cancelled |
cancellation.endDate | date | Last day of the booking being cancelled |
cancellation.workingDays | number | Working days of the booking being cancelled |
cancellation.daysUntilStart | number | Days between today and the first day of the booking being cancelled |
cancellation.hasStarted | bool | True if the booking being cancelled has started |
cancellation.ptoTypeId | string | Leave type of the booking being cancelled |
request.minDaysUntilCancellation | number | Days between today and the start of the booking being cancelled |
timeoff.rules.reference returns this list from the engine itself, with each variable's unit and the kinds of rule it exists in.
Functions#
| Function | What it does |
|---|---|
between(x, a, b) | True if x is between a and b, both included (numbers, or dates as YYYY-MM-DD text) |
daysBetween(a, b) | Days from date a to date b (negative when b is earlier); use with civilDate |
civilDate(s) | A YYYY-MM-DD text as a date, for daysBetween |
isEmpty(x) | True for an empty text or list, or a missing value |
string(x) | x as text |
size(x) | Number of items in a list, or characters in a text |
has(a.b) | True if the field is present |
Lists and aggregations#
A list is checked with a macro that names each item:
| Macro | Gives |
|---|---|
list.exists(x, condition) | true if at least one item meets the condition |
list.all(x, condition) | true if every item does (true for an empty list) |
list.exists_one(x, condition) | true if exactly one item does |
list.filter(x, condition) | the items that do; count them with size(…) |
list.map(x, value) | a value per item |
size(period.runs.filter(r, r.workingDays >= 5)) >= 2The balance variables are aggregations computed by the engine with one formula everywhere (the balance page, the booking check and rules): balance.available is the allowance plus carried days and adjustments that are in effect today, minus the days used or booked; balance.afterSession subtracts this booking too.
Period awareness#
period.* looks at the whole leave year the booking falls in, with the booking (or cancellation) already applied. Weekends and public holidays don't break a stretch of days off; a half day counts as half. That is how a rule can ask for a long break each year without refusing every short booking:
!period.runs.exists(r, r.workingDays >= 10) && period.maxAchievableConsecutiveRun < 10It applies only when the year has no stretch of 10 working days off and the person can no longer fit one in, given what is booked and their balance.
Messages#
A message is text. Placeholders fill in values from the check:
| Placeholder | Is replaced by | In |
|---|---|---|
${day.date} | The day that breaks the rule | Booking rules that check each day |
${request.startDate} / ${request.endDate} | First / last day booked | Booking rules |
${request.bookedWorkingDays} | Working days booked | Booking rules |
${request.noticeDays} | Days between today and the first day booked | Booking rules |
${cancellation.startDate} / ${cancellation.endDate} | First / last day of the booking being cancelled | Rules that check each cancellation |
${cancellation.workingDays} | Working days of the booking being cancelled | Rules that check each cancellation |
${cancellation.daysUntilStart} | Days between today and the cancelled booking | Rules that check each cancellation |
${rule.params.<name>} | One of the rule's parameters | Any rule |
Nothing else can be printed: never balances, team counts, other people or ids. Messages are stored on bookings that managers see, so they only ever say what the person booked and what the rule allows.
Limits#
- A condition is at most 1,000 characters, with at most 12 list macros, no macro inside another (that would compare every pair of items) and nothing after a macro's result except as an argument (
size(list.filter(…)), notlist.map(…).filter(…)). - No map literals (
{…}); a list literal has at most 50 items and no list inside it. - Only the variables and functions on this page; anything else is refused when you save.
- A rule gets 50 ms per booking. One that takes longer is skipped for that booking: it never blocks.
- A message is at most 300 characters. A rule has at most 10 parameters. A company has at most 60 rules.
Recipes#
| Rule | Condition | Message |
|---|---|---|
| Long bookings need two weeks' notice | request.bookedWorkingDays >= 5 && request.noticeDays < 14 | Bookings of 5 days or more need 14 days' notice (this one starts on ${request.startDate}). |
| No Fridays off in July and August | day.dayOfWeek == 5 && between(day.date, "2026-07-01", "2026-08-31") | ${day.date} is a Friday in the summer rota. |
Keep days in reserve (param reserve = 3) | balance.afterSession < rule.params.reserve | Keep at least ${rule.params.reserve} days for later in the year. |
| A two-week break each year | !period.runs.exists(r, r.workingDays >= 10) && period.maxAchievableConsecutiveRun < 10 | Leave room for a break of 10 working days in a row this year. |
| New joiners: 3 days in a row at most | employee.tenureMonths < 6 && request.longestRequestedRun > 3 | In your first 6 months, book at most 3 days in a row. |
| No cancelling in the last week (cancellation) | cancellation.daysUntilStart < 7 | Time off starting on ${cancellation.startDate} can no longer be cancelled: ask HR. |
Over the API and MCP#
- Read the language:
timeoff.rules.reference. - Check the rule:
timeoff.rules.validatereturns every problem with the field it is about (condition,message,params). - Try it on a person and days:
timeoff.rules.trysays whether they are in scope, the verdict, the message and the days. - Save it:
timeoff.rules.createwithtemplate_id: "custom"(preview with?dry_run=truefirst). Saving refuses what validate refuses.
curl https://api.bizisy.com/v1/timeoff/rules.validate \
-H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
-d '{"condition": "day.dayOfWeek == 5 && between(day.date, \"2026-07-01\", \"2026-08-31\")", "message": "${day.date} is a Friday in the summer rota."}'curl https://api.bizisy.com/v1/timeoff/rules.create \
-H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id": "custom", "name": "No Fridays off in summer", "applies_to": "booking", "outcome": "block", "condition": "day.dayOfWeek == 5 && between(day.date, \"2026-07-01\", \"2026-08-31\")", "message": "${day.date} is a Friday in the summer rota.", "scope": {"location_ids": ["loc_porto"]}}'API keys and connected apps need a role with HR rights (owner, admin or HR), like for templates; every check applies to them too, and Activity records which key or app made the change.
Something missing or wrong on this page? Write to hello@bizisy.com.