Terminology

This section lists frequently used terms and their meanings:

Defines when an employee is available or unavailable for shifts. Use unavailableTimeSpans for employees who are generally available but have occasional absences, and availableTimeSpans for employees who are only available during specific periods. Learn more about employee availability.

A call-out is when an employee cancels a shift at short notice, for example, by calling in sick. A no-show is when an employee doesn’t arrive for a shift. Both leave a gap in the schedule that real-time planning can fill while keeping other assignments in place. Learn more about real-time planning.

A closing shift followed by an opening shift the next morning, leaving the employee too little rest in between. Clopenings are common in retail and hospitality and are prevented with a minimum rest period between shifts. Learn more about minutes between shifts.

The hard, medium, and soft rules that must be taken into account when creating an employee shift schedule. Learn more about constraints.

A set of rules that apply to a specific group of employees. Contracts define conditions such as maximum hours worked, minimum time off, and shift rotation requirements. Learn more about employee contracts.

Rules that make labor costs part of the optimization, so the model minimizes them alongside other soft constraints. Employee rates set base and overtime hourly costs for time worked in a period. Cost groups set the cost of assigning employees from one group to shifts from another, and can cap the total cost. Learn more about cost management.

Timefold accepts input datasets that include information about the employees and the shifts to be scheduled and optimized. Input datasets are created using our predefined model schema which follows the OpenAPI specification. Timefold returns output datasets that contain the optimized solution.

See the API spec for more information.

A scheduling mode where the number of employees required per hour is known rather than the exact number of shifts. Timefold selects shifts from a pool to meet the demand curve, assigning fewer employees during quiet periods and more during busy ones. The demand often comes from a forecast the business already produces, such as hotel occupancy, restaurant covers, or retail footfall. The alternative is shift slot scheduling, where a fixed number of shifts is defined upfront. Learn more about demand-based scheduling.

A person who can be assigned to shifts. Employees can have contracts, skills, availability constraints, and a priority level.

An employee is activated when they’re assigned at least one shift in the planning window. Activation rules can minimize the number of activated employees, add a fixed activation cost, for example, for contractors, or keep a ratio between employee groups, so that internal staff are used before contractors. Learn more about employee activation.

Times when an employee prefers or prefers not to work, and tags that express preferences such as a department or location. Preferences are soft constraints and can be weighted to rank them. Learn more about employee preferences.

A value assigned to an employee (1–10, where 1 is highest) that controls how strictly the model honors that employee’s preferences and working-hours rules when trade-offs must be made. Learn more about employee priority.

Labor regulations in some jurisdictions that set rules for how employers schedule hourly staff, such as minimum rest between shifts. The model enforces rest requirements with minutes between shifts rules. Requirements outside the schedule itself, such as how far in advance a schedule must be published, are managed in your own processes. Learn more about configuring labor law compliance.

The principle of distributing shifts evenly across employees. Fairness constraints can balance the total number of shifts assigned or the total time worked, helping to avoid situations where some employees work many shifts while others work few. Learn more about fairness.

The minimum number of hours an employee’s contract promises in a period, common for part-time staff. Guaranteed hours are modeled with a preferred minimum on a minutes worked per period rule. Learn more about preferred minutes worked per period.

Shifts that ended before the planning window, included in the input to give work-limit and time-off constraints the history they need to evaluate rolling windows correctly. Historic shifts are excluded from optimization and do not appear in output metrics. Learn more about planning windows.

The time an employee is paid for on a shift, which can differ from the shift’s duration, for example, when the shift includes unpaid breaks or runs longer than planned. Work limits can apply to logged time instead of scheduled time. Learn more about minutes logged per period.

A mandatory shift must be covered and cannot be left unassigned. An optional shift can remain unassigned if there are not enough employees to cover all shifts. Learn more about mandatory and optional shifts.

Shifts for employees on standby who can step in when another employee is suddenly unavailable. On-call shifts are given a lower priority than regular shifts, so real-time planning can reassign the on-call employee to cover a gap. Learn more about real-time planning and on-call shifts.

Shifts assigned to the same employee that occur at the same time, for example, a regular shift and an on-call shift. By default, an employee’s shifts can’t overlap. Contract rules can allow specific shifts, identified by their tags, to overlap. Learn more about overlapping shifts.

Time an employee works beyond their contracted hours. Overtime is modeled with two minutes worked per period rules: a required rule for the absolute maximum and a preferred rule for the contracted hours, so the model avoids overtime where it can. Employee rates can apply a higher hourly cost to overtime. In contract staffing, non-billable overtime is overtime that can’t be charged back to the client. Learn more about modeling overtime and employee rates.

A rule that applies to a fixed period of time, such as a day, week, or month, and resets at the start of each new period, for example, "employees may not work more than 8 hours per day." The alternative is a rolling window. This distinction lets the model capture both fixed accounting rules and continuous requirements such as fatigue management. Learn more about work limits and time off.

Locking a shift to its assigned employee so the model can’t change the assignment. Pinning is used to keep published or manually assigned shifts in place during real-time planning. Learn more about manual intervention.

The upcoming time interval that the model schedules shifts for. Learn more about planning windows.

In security, a fixed position at a site that a guard must staff, such as an entrance or a control room. Posts are modeled as shifts, and critical posts as mandatory or high-priority shifts. Learn more about mandatory and optional shifts.

A higher pay rate for unsociable shifts, such as weekends and nights, also called a shift differential. Premium pay is modeled with cost management, so the model treats premium-rate hours as a cost to minimize. Learn more about cost management.

A priority value assigned to a shift that controls which shifts are scheduled first when there are not enough employees to cover all shifts. Learn more about mandatory and optional shifts.

The ability to update a schedule after it has been published to accommodate disruptions such as call-outs or sudden demand changes, while minimizing disruption to assignments already in place. Learn more about real-time planning.

An API that, given an open shift, returns an ordered list of the best-fit employees to assign to the shift. Useful for last-minute scheduling decisions when an employee is suddenly unavailable. Learn more about recommendations.

The minimum time off an employee must have between shifts, set by labor law or contract, for example, 11 hours. Rest periods protect against fatigue and prevent clopenings. Learn more about minutes between shifts.

Hazards associated with a shift that an employee must not be exposed to. If an employee has a prohibited risk factor that matches one on a shift, they cannot be assigned to it. Learn more about risk factors.

A rule that moves dynamically, functionally a moving filter, instead of resetting on a fixed calendar boundary. For example, a rolling window of type DAILY and size 7 expresses "employees must have at least one full day off in any consecutive 7 days," applied to every consecutive 7-day stretch across the entire planning interval. The alternative is a period rule.

There is some equivalency between rolling windows and period rules:

Learn more about work limits and time off.

Another term for employee shift scheduling: assigning employees to shifts to produce a roster (a schedule) for a set period. The term is common in healthcare and in the UK, Ireland, Australia, and New Zealand. When employees choose or request their own shifts, it’s called self-rostering.

A scheduling approach where employees select the shifts they want to work, rather than having a manager assign them, also called self-scheduling. Self-rostering is common in nursing and can be combined with optimization, where employees select shifts and the model fills the remaining gaps.

Learn more about self-rostering and optimization.

A work period with start and end times that is assigned to an employee.

Periods within a shift when the employee isn’t working, such as a lunch break. Time covered by breaks doesn’t count toward time worked. Learn more about shift breaks.

A group of alternative shifts of which only one shift should be assigned. Learn more about alternative shifts.

Sequences of shifts that define how employees rotate between different shift types over a set period, for example, one week of day shifts followed by one week of night shifts. Learn more about shift rotations and patterns.

Capabilities that employees have and shifts may require. Required skills are enforced as hard constraints; preferred skills apply a soft penalty when not matched. Skills aren’t limited to certifications. They can represent any yes/no eligibility trait, such as which department, location, or team an employee is allowed to work in. Learn more about skills and risk factors.

A workday divided into two or more shifts with a gap in between, for example, a lunch shift and a dinner shift in a restaurant. The model can keep the gap between split shifts as short as possible. Learn more about minimize gaps between shifts.

Labels applied to employees and shifts to categorize them. Tag types group related tags; tags on a rule can include or exclude specific employees or shifts from that rule’s scope. Learn more about tags and tag types.

Periods when employees are not scheduled to work, managed through time-off requests and contract rules (for example, days off per period and consecutive days off). Learn more about time off.

Contract rules that cap how many hours, days, or shifts an employee can work within a fixed period or rolling window. Learn more about work limits.