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.

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.

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 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.

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

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.

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.

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.

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

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 re-run the solver after a schedule has been published to accommodate disruptions such as employee sick leave 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.

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 work period with start and end times that is assigned to an employee.

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. Learn more about skills and risk factors.

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.