Skip to content

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#

PartWhat it is
ConditionA template with its settings, or your own expression. When it is true, the rule applies.
Outcomeblock 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 whenBooking (applies_to: "booking") or cancelling ("cancellation").
ScopeEveryone, or people who match every list you fill in: locations, teams, people. Leave types: all, or the ones you list.
MessageWhat 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:

UnitWhen the condition usesIt is checked
Each dayday.*, team.* counts, employee.tenureMonthsonce per working day booked; the days that break it are reported one by one
The bookingrequest.*, booking.*, employee.*once for the whole booking
The leave yearbalance.*, period.*once per leave year the booking touches
The cancellationcancellation.*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.

Text
request.bookedWorkingDays >= 5 && request.noticeDays < 14
  • Comparisons: == != < <= > >=; logic: && || !; arithmetic: + - * / %; a condition ? a : b.
  • Text in double quotes: booking.ptoTypeId == "vacation". Dates are YYYY-MM-DD text, so they compare in order: day.date >= "2026-12-01".
  • in checks 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#

VariableTypeWhat it is
request.bookedWorkingDaysnumberWorking days booked
request.startDatedateFirst day booked (YYYY-MM-DD)
request.endDatedateLast day booked (YYYY-MM-DD)
request.hasHalfDayboolTrue if a morning or an afternoon is booked
request.hasHoursboolTrue if some hours of a day are booked
request.bookedHoursnumberHours booked as some hours of a day
request.noticeDaysnumberDays between today and the first day booked
request.longestConsecutiveRunnumberLongest stretch of working days in a row, joining this booking to the person's other days off
request.longestRequestedRunnumberLongest stretch of working days in a row within this booking
request.shortestRequestedRunnumberShortest stretch of working days in a row within this booking
booking.ptoTypeIdstringLeave type being booked (its id, e.g. "vacation")
booking.startDatedateFirst day booked
booking.endDatedateLast day booked
booking.daysRequestednumberWorking days booked

Each day booked#

VariableTypeWhat it is
day.datedateThe day (YYYY-MM-DD)
day.dayOfWeeknumberDay of the week: 0 Sunday, 1 Monday … 6 Saturday
day.isWorkingDayboolTrue if it is a working day for the person
day.noticeDaysnumberDays between today and that day
employee.tenureMonthsnumberWhole months since the person started, on that day
team.concurrentLeaveCountnumberTeammates away on that day (never shown to the person)
team.membersRemainingnumberTeammates working on that day
team.percentageOffnumberPercentage of the team away on that day
team.percentageOffAfternumberPercentage of the team away on that day, counting this booking

The leave year#

VariableTypeWhat it is
balance.entitlementnumberThe person's allowance for the leave year (carried days and adjustments count in balance.available)
balance.usednumberDays used or booked in the leave year
balance.availablenumberDays available before this booking
balance.afterSessionnumberDays available after this booking
period.runslistThe stretches of consecutive working days off in the leave year, with this booking or cancellation applied
period.maxConsecutiveAvailableWorkingDaysnumberLongest stretch of working days not yet booked in the leave year
period.maxAchievableConsecutiveRunnumberLongest 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#

VariableTypeWhat it is
employee.hireDatedateThe person's start date (YYYY-MM-DD)
employee.countryCodestringCountry of the person's location (ISO code, e.g. "PT")
countryCodestringSame as employee.countryCode
team.memberCountnumberPeople in the person's team
nowdateWhen the rule is checked (date and time)

The booking being cancelled#

VariableTypeWhat it is
cancellation.startDatedateFirst day of the booking being cancelled
cancellation.endDatedateLast day of the booking being cancelled
cancellation.workingDaysnumberWorking days of the booking being cancelled
cancellation.daysUntilStartnumberDays between today and the first day of the booking being cancelled
cancellation.hasStartedboolTrue if the booking being cancelled has started
cancellation.ptoTypeIdstringLeave type of the booking being cancelled
request.minDaysUntilCancellationnumberDays 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#

FunctionWhat 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:

MacroGives
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
Text
size(period.runs.filter(r, r.workingDays >= 5)) >= 2

The 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:

Text
!period.runs.exists(r, r.workingDays >= 10) && period.maxAchievableConsecutiveRun < 10

It 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:

PlaceholderIs replaced byIn
${day.date}The day that breaks the ruleBooking rules that check each day
${request.startDate} / ${request.endDate}First / last day bookedBooking rules
${request.bookedWorkingDays}Working days bookedBooking rules
${request.noticeDays}Days between today and the first day bookedBooking rules
${cancellation.startDate} / ${cancellation.endDate}First / last day of the booking being cancelledRules that check each cancellation
${cancellation.workingDays}Working days of the booking being cancelledRules that check each cancellation
${cancellation.daysUntilStart}Days between today and the cancelled bookingRules that check each cancellation
${rule.params.<name>}One of the rule's parametersAny 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(…)), not list.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#

RuleConditionMessage
Long bookings need two weeks' noticerequest.bookedWorkingDays >= 5 && request.noticeDays < 14Bookings of 5 days or more need 14 days' notice (this one starts on ${request.startDate}).
No Fridays off in July and Augustday.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.reserveKeep 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 < 10Leave room for a break of 10 working days in a row this year.
New joiners: 3 days in a row at mostemployee.tenureMonths < 6 && request.longestRequestedRun > 3In your first 6 months, book at most 3 days in a row.
No cancelling in the last week (cancellation)cancellation.daysUntilStart < 7Time off starting on ${cancellation.startDate} can no longer be cancelled: ask HR.

Over the API and MCP#

  1. Read the language: timeoff.rules.reference.
  2. Check the rule: timeoff.rules.validate returns every problem with the field it is about (condition, message, params).
  3. Try it on a person and days: timeoff.rules.try says whether they are in scope, the verdict, the message and the days.
  4. Save it: timeoff.rules.create with template_id: "custom" (preview with ?dry_run=true first). Saving refuses what validate refuses.
Shell
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."}'
Shell
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.

Developer docs