Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Field Service Routing
  • New and noteworthy

Field Service Routing

    • Introduction
    • Planning AI concepts
    • Metrics and optimization goals
    • Getting started with field service routing
    • Understanding the API
    • Constraints
    • Vehicle resource constraints
      • Shift hours and overtime
      • Lunch breaks and personal appointments
      • Fairness
      • Technician costs
    • Visit service constraints
      • Time windows and opening hours
      • Skills
      • Visit dependencies
      • Visit requirements
      • Multi-vehicle visits
      • Priority visits and optional visits
    • Real-time planning
      • Real-time planning
      • Real-time planning: extended visit
      • Real-time planning: reassignment
      • Real-time planning: emergency visit
      • Real-time planning: no show
      • Real-time planning: technician ill
      • Real-time planning: pinning visits
    • Recommendations
      • Recommendations
      • Visit time window recommendations
      • Visit group time window recommendations
    • Time zones and daylight-saving time (DST)
    • New and noteworthy
    • Upgrading to the latest versions
    • Feature requests
    • Reference guide

New and noteworthy

0.40.0

Improved break handling

Break end times are now exclusive instead of inclusive. This change removes confusion that could occur when a break end time overlapped with a shift start time.

Breaks API improvement

The way of defining required breaks has been deprecated and has been replaced with a simpler alternative.

More information can be found in the required break section in the reference guide.

Information on how to upgrade can be found on the upgrade to the latest version page.

In order to avoid confusion around the fixed and floating breaks, the API has been simplified for breaks. Instead of using minStartTime and maxStartTime to determine if a break is a fixed/floating break, there is now a field type which can be set to either FIXED or FLOATING.

Removed unchanged constraints from the recommendations API response

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

Fixed potential score corruption with VehicleShift.minFirstVisitArrivalTime

Fixed potential score corruption when using VehicleShift.minFirstVisitArrivalTime.

0.39.0

Added support for diminished returns termination

When submitting a new route plan with an 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.

Removed unchanged justifications from the recommendations API response

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

0.38.0

Rebalanced hard constraint weights

A missing skill or tag in an input dataset was penalized as -1hard resulting in a much smaller penalty than, for example, violating the maximum service end time of a visit.

As a result, an infeasible solution that broke a skill or tag requirement was favored over an infeasible solution with all skills/tags but that didn’t finish the service in time by a couple of minutes.

The following hard constraints weights were rebalanced: Require skills, Require tags and Require vehicles.

0.37.0

Configurable justifications in the recommendations API

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 visits are not completed in time because of the recommended visit (or visit group) assignment.

Please see the Visit time window recommendations and Visit group time window recommendations guides for more details.

0.36.0

Improved movable visit handling

We have added a custom move to facilitate movable visits assignment.

Previously, a movable visit could have blocked the assignment of another visit, resulting in the model not being able to assign all visits. The new custom move reassigns the movable visit, increasing the chance of assigning all visits.

0.35.0

Input metrics

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

  1. number of visits

  2. number of visitGroups

  3. number of vehicles

  4. number of mandatory visits

  5. number of optional visits

  6. number of vehicleShifts

See OpenAPI Spec for a description of their meaning.

Improved scalability and memory usage efficiency

We have improved memory usage efficiency, resulting in better scalability over datasets with large numbers of visits.

Added a new set of KPIs

A new set of KPIs has been added, please see the Key Performance Indicators section for details:

  • The number of visits assigned in the schedule.

  • The number of mandatory visits assigned in the schedule.

  • The number of optional visits assigned in the schedule.

  • The number of vehicles used in the schedule.

  • The amount of overtime required for the schedule.

0.33.0

Recommendation calls now validate the input dataset

Similarly to the model run, the recommendation calls now validate the input dataset.

Added technician costs optimization

Every vehicle shift can specify a Vehicle Shift Cost that will be used in the optimization by the minimize shift cost constraint. Please see the Technician costs guide for details.

We have added a new KPI representing the total cost of the solution.

Visualization UI improvements

We have improved the Visualization UI, with better formatting of dates and coordinates as well as improvements to the color scheme.

0.32.0

Recommended time window alignment with visits

We have implemented minStartTime, maxStartTime, and maxEndTime to replace the now deprecated startTime and endTime. Adding maxStartTime opens the possibility to get recommendations for fixed-start visits (these are visits where minStartTime equals maxStartTime).

0.31.0

Visit can specify preferred vehicles

We have added a capability to specify preferred vehicles for a visit. When set, the visit can be assigned to a shift of one of the specified vehicles if possible. You can specify these as modelInput.visits[].preferredVehicles when submitting a new route-plan. Refer to the OpenAPI Spec for details.

New metadata in the model run

We have added activeDateTime and shutdownDateTime attributes in model run information.

Added a kpi for the fairness constraint

We have added a new KPI for the fairness constraint that we introduced with v0.30.0. See the feature guide for fairness or the Timefold Platform UI for a description of its meaning.

Enabled multi-threaded solving

We have enabled multi-threaded solving for this model. Based on our benchmarking results, the maximum number of threads is limited to 4 for now.

The desired maximum number of threads can be specified by the maxThreadCount attribute in Run configuration. The default is 1.

0.30.0

Added a fairness constraint

We have added a new constraint to the model that allows you to balance the workload fairly across technicians based on their time worked. The constraint also allows for historical data to be considered. This can be useful when you want to balance the workload fairly based on past hours worked by the technicians.

More information can be found in the feature guide for fairness.

Fine-grained priority

Priority is now defined as a number between 1 and 10 (both included), with 10 being the lowest priority and 1 being the highest priority. The default priority is "6".

Please see Upgrading to the latest versions for additional details.

0.28.0

We fixed a bug where travel time from a previous break on a specific location was not properly taken into account.

0.26.0

Extending the recommendation API with dependent vehicle shifts

Added includeDependencies as a new parameter to the VisitTimeWindowRecommendationRequest API. With this parameter you can select whether you want to check for possible dependent vehicle shift plans that might be influenced by a recommendation. If the recommendation for a visit puts it before other visits, it might change the arrival, start of service and departure times of the previously planned visits. If those have relations to other visits (e.g. visit groups, visit dependency), the recommendation might also affect other vehicle shift plans. By setting the includeDependencies parameter to ALL, these dependencies will be part of the response.

0.25.0

Improved demo datasets

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 Field Service Routing capabilities, Visit Dependencies, and Visit Groups.

New visit dependency feature

Added minStartDateAdjusterIncrement to the minDelayTo VisitDependency. The value determines how many times the minStartDateAdjuster is applied. This allows a more precise control over the delay.

More information can be found in Dependencies between visits under Visit dependency with minimum delay as a point in time

0.23.0

Visit can specify required vehicles

Added capability to specify vehicles required by a visit. When set, the visit can be assigned only to a shift of one of the specified vehicles. More information can be found in Visit assignment restrictions.

0.22.0

Visit dependency coordination

Added VisitDependency capability to specify additional conditions between dependent visits, such as requiring both visits to be assigned to the same vehicle (not the same vehicle shift). More information can be found in Visit dependency with coordination.

0.21.0

Visit group alignment

When defining Visit Groups, you can now specify they need to be aligned at the end of the Visit. You can use this if two or more technicians need to be present for a Visit at the end of the job. E.g. both technicians need to be present to finish the task after preparation work was done by one of them.

More information can be found in Visit Group reference.

0.20.0

Visit dependency minDelayTo

Added VisitDependency capability to specify a delay to the next day/week/day-of-week, more information can be found in Visit dependencies.

0.20.0 is backward compatible with 0.19.0 and no migration is required.

0.19.0

Input validation fixes and enhancements

Fixed validation of all model input date-time attributes to require the time zone offset.

Validation now rejects a vehicle without any vehicle shifts.

0.19.0 is backward compatible with 0.18.0 and no migration is required.

0.18.0

Local date time replaced by date time with offset to UTC

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

Please see migrating from 0.17.0 to 0.18.0 and Time zones and daylight-saving time (DST) for additional details.

  • © 2025 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default