New and noteworthy

We have added a new BASIC demo data set which demonstrates a minimal set of Timefold features. This is a simple example that is not meant to be reflective of real-world scheduling needs. It is intended for those early on in their Timefold journey to help them understand the basic features and progress to the more complex features in our other demo data sets.

We have added support for defining hourly rolling window periods for the following rules. Previously, the rolling window rules were only available for daily and weekly periods.

This feature can help formulate constraints that need to be satisfied over a rolling window of time, for example:

The recommendations API response no longer includes constraintDiffs entries for unchanged justifications to improve clarity and lower the size of the response.

We have added a new constraint to rotate shift types for employees.

Use this to make sure that the employee’s shift types rotate in consecutive periods, for example, "morning" shifts on week 1 and "evening" shifts on week 2.

We have introduced 2 new constraints for better handling of consecutive days off.

This feature allows a minimum of consecutive number of days off per period to be set on contracts. So when an employee needs 2 consecutive days off, their contract can define 1 period rule defining "consecutiveDaysOffLimit.consecutiveDaysOffMin: 2".

We have added a new constraint that limits the variation in shift start times. It checks whether the time between the earliest shift start and the latest shift start in this period is larger than the period rule’s shiftStartTimeDifferenceInMinutesMax.

This constraint allows you to assign shifts with similar start times to employees, limiting the range of start times individual employees will have during a specific period of time and reducing the disruption to their daily schedule.

We have added 2 new metrics to provide more insights into solutions.

This update adds metrics that will give more insights into the model output, including how many shift groups were and how many weren’t allocated in the schedule.

A series of updates have been made to the available demo datasets:

This is to better demonstrate the full capabilities of Timefold. The demo data is now more representative of real working rules, including contract patterns, maximum hours worked per day, maximum hours worked per week, preferences, and unavailabilities.

When submitting a new schedule with unspecified unimprovedSpentLimit in the run termination configuration, the run will use the new diminished returns termination.

Diminished returns terminates the solver early if expected improvements are minimal, saving on CPU costs. This termination is desirable since it terminates based on the relative rate of improvement, and behaves similarly on different hardware and different problem instances. You can find more details in the documentation.

Please see migrating from 0.38.0 to 0.39.0 for more details on run termination configuration changes.

The recommendations API response no longer includes matchesDiff entries for unchanged justifications to improve clarity and lower the size of the response.

We have introduced 2 new constraints for better handling of days off.

This feature allows a minimum and/or maximum of days off per period to be set on contracts. This means inputs don’t require the inverse logic with period rules anymore, e.g. when an employee needs 2 days off their contract can define 1 period rule defining "daysOffLimit.daysOffMin: 2", instead of a period rule defining "daysWorkedMax: periodLength - 2" for every period with a different length that the rule would apply to.

We have introduced rolling window rules to define constraints that need to apply over consecutive number of hours, days, or weeks:

This feature can help formulate constraints that need to be satisfied over a rolling window of time, for example:

We have introduced 2 new constraints to limit the number of unique tags that can be used to assign shifts to employees:

This feature can help limit the maximum number of unique tags that can be used to assign shifts to employees. For instance, shift types, routes, skills.

When submitting a recommendations API request, you can specify an optional boolean includeJustifications query parameter to control whether constraint match justifications should be included in the response.

This is useful for getting more fine-grained information about the constraint matches, for instance to learn which period rule is violated by the recommended employee assignment.

Please see the Recommendations guide for more details.

Priorities have been added to contracts. This means some contracts can now have higher priority than others. By default, the highest priority is "1" and the lowest priority is "10". They respectively have the weights: 10 and 1. This means that a contract with priority "1" will have 10 times the impact of an identical contract with priority "10".

This feature allows for granular control over how much contracts comparatively weigh in solutions. It comes in handy when there is a contract that defines a certain rule that is more important than another, e.g. Contract A defines periodRules which are more important than Contract B’s minutesBetweenShiftRules. In this example, we can set Contract A’s priority to 5 and Contract B’s priority to 10 (default).

We have improved the performance of the model by introducing caching in constraints. We have observed a speedup of 10-50% of the calculation speed, depending on the dataset.

This will result in finding solutions quicker.

When shifts spanned multiple days, counting the days over which the shift spanned wasn’t accurate for periods longer than 1 day and when using the periodShiftOverlapKind START_AND_END. This is now fixed.

This fix makes sure that shifts spanning multiple days will be accurately counted when using contract period rules with days worked per period and periodShiftOverlapKind set to START_AND_END.

We have added 4 new KPIs to provide more insights into solutions.

See OpenAPI Spec or the Timefold Platform UI for a description of their meaning.

This update adds KPIs that will give more insights into the model output, including how many employees were assigned shifts in the schedule, the number mandatory and optional shifts that were scheduled, and the total travel distance.

We have improved the performance and scalability of global rules.

The impacted constraints are:

This improvement will result in finding solutions quicker, especially for large datasets.

A minimum with a REQUIRED satisfiability is now deprecated because it may be the cause of infeasible solutions when there is a lack of shifts in the input. Use the minimum with a PREFERRED satisfiability instead.

The impacted constraints are:

This update will result in fewer infeasible solutions when using minimums in the listed constraints.

We have added 3 new input metrics that provide information on the dataset input:

See OpenAPI Spec for a description of their meaning.

The Cost Rules, Period Rules and Global Period Rules previously only checked whether a shift broke a rule if the shift started within the rule’s validity period. Now this behaviour can be configured to also compare the shift’s end time with the rule’s validity period. See the constraint documentation costs per period not in required range and costs per period not in preferred range and the employee contract documentation.

We have added a new concurrent shifts worked not in required range constraint to control the maximum number of shifts that can take place at the same time. The feature is useful in scenarios where the shifts use a shared resource with limited capacity.

See concurrent shifts rules for more information.

It is now possible to specify a list of travel configurations per contract. Each travel configuration can limit the distance from the home location to a shift’s location and the time between 2 shifts at different locations, within a certain time period. See the updated user guide for examples.

Global travel configurations are now deprecated.

The contractual period rules can now specify minimum and maximum logged minutes evaluated against the new shift loggedTime attribute. This feature can be useful when limiting minimum/maximum shift hours that differ from the scheduled shift start to end interval, e.g. because breaks are not included in the shift working hours.

See Logged time and period rules and the constraint documentation for details on both REQUIRED and PREFERRED variants.

We have added a new required shift group assignment mode not met constraint to specify the way the shifts are assigned within shift groups. The feature is useful in scenarios where a piece of work (e.g. product demonstration) should only be done once, but we have multiple time slots (shifts) available for it.

See shift group rules for more information.

We have added a custom move to facilitate matching of PREFERRED patterns.

You may also specify the weight of a single-day shift pattern in the relation to the other single-day patterns. See Employee works preferred single-day shift sequence pattern rule for more information.

The REQUIRED single-day patterns are now deprecated and will be removed in a future version in favour of PREFERRED patterns with a high weight.

Single Day Shift Patterns now have a property ordered (true by default). When set to false, the pattern can be matched even if the shifts don’t follow the same order as their respective pattern elements.

Fixed a bug where DLS was not properly applied for employees. zoneOffset on employees is now deprecated in favour of timeZoneId.

For more information, please see:

Shift tags are now displayed in the visualization.

In Employee Contracts, you can specify the minimum or maximum time between shifts with minutesBetweenShiftsRules. You can now provide a scope for these rules. The scope will limit which pairs of shifts the rule is applied to. The scope excludes shift pairs where the start of the later shift is after the end of the prior shift plus the scope duration. See the updated Employee contracts: period rules for examples.

We have extended shift priorities to distinguish between mandatory (default) and optional shifts. Optional shifts are useful in scenarios when conformance with a soft constraint (e.g. a PREFERRED multi-day pattern rule) is more desired than having an extra shift assigned.

For more information, please see:

We have added a custom move to facilitate matching of PREFERRED patterns.

You may also specify the weight of a multi-day shift pattern in the relation to the other multi-day patterns. See Employee works preferred multi-day shift sequence pattern rule for more information.

The weight can be used to migrate from REQUIRED patterns to PREFERRED patterns with high weight, see Upgrading to the latest versions for details.

We have added 4 new KPIs that provide information on the employees' preferences:

See OpenAPI Spec or the Timefold Platform UI for a description of their meaning. These KPIs are marked as experimental and subject to change. We would love your feedback.

We have fixed the multi-day pattern rules to correctly handle a pattern starting with OFF. Please note that if you use a pattern starting or ending with OFF, you must specify the planning window interval to ensure the pattern matches properly throughout the whole period you are planning for.

The REQUIRED multi-day patterns are now deprecated and will be removed in a future version in favour of PREFERRED patterns with a high weight.

See Employee works preferred multi-day shift sequence pattern rule for more information.

We have added a constraint to prefer assigning employees to shifts that are close to each other to minimize the time between shifts. This is useful for cases where the employee works multiple shifts per day.

See Minimize gaps between shifts for employee rule for more information.

We have replaced the existing demo datasets with new ones that are more realistic and better showcase the model’s features.

The new demo datasets cover basic Employee Shift Scheduling capabilities, Contract Period Rules, and Hourly Demand Rules.

We have added the ability to define custom priorities and weights for shifts. Whenever the model needs to choose between multiple shifts to assign to an employee, it will favor shifts with higher priority.

See Unassigned shift rule for more information.

We extended the period rules to restrict the maximum number of locations an employee works during a period.

See documentation of the rules for more information:

We are renaming the “Employee Scheduling” model to “Employee Shift Scheduling” to distinguish between future other models involving scheduling for employees. (We are not changing API urls or entity names, because …)

We have also marked this model as “Stable”, meaning that we promise backwards-compatibility for future minor releases.

We have removed the shift’s duration from the constraint’s penalty. We now only consider the shift’s assignmentPriority.

We added a new Balance time worked rule.

Use this rule to make sure the time worked is balanced fairly across employees.

Tags can now be used to define preferred and required shifts for employees.

See documentation of the rules for more information:

We have improved our documentation related to tags to more clearly give an overview of their possible uses. See Tags and tag types for more information.

We fixed an issue in Balance shift count rule, that caused performance degradation for big datasets.

We fixed a bug for the Minutes between shifts rules, where the minimum was not always honored for shift sequences.

Period rule defined as a part of employee contract can now specify a validity date time span to further limit when the rule is applicable.

Please see Employee contract period rule for additional details.

All ISO 8601 local date time types have been replaced by ISO 8601 local date time with offset to UTC (Coordinated Universal Time) to support multiple time zones.

Please see Upgrading to the latest versions and Time zones and Daylight Saving Time (DST) for additional details.

Employees and shifts can now provide a location. This allows you to restrict the possible shifts where an employee can work and minimize the travel distance.

The following constraints have been added:

Employee preferences are more likely to be satisfied for employees with higher priority.

Affects the following constraints

See employee priority.

Affects the following constraints:

The filtering allows you to include, or exclude shifts worked by specific employee types. For example, you can consider only shifts worked by full time employees.