Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Field Service Routing
  • User guide
  • Constraints

Field Service Routing

    • Introduction
    • Getting started with field service routing
    • User guide
      • User guide
      • Terms
      • Planning AI concepts
      • Constraints
      • Understanding the API
      • Planning window
      • Model configuration
      • Configuration overrides
      • Time zones and daylight-saving time (DST)
      • Routing with Timefold’s maps service
      • Validation
      • Model response
      • Key performance indicators (KPIs)
      • Metrics and optimization goals
    • Vehicle resource constraints
      • Vehicle resource constraints
      • Shift hours and overtime
      • Lunch breaks and personal appointments
      • Fairness
      • Route optimization
      • Technician coverage area
      • Technician costs
      • Technician ratings
    • Visit service constraints
      • Visit service constraints
      • Time windows and opening hours
      • Skills
      • Visit dependencies
      • Visit requirements
      • Multi-vehicle visits
      • Movable visits and multi-day schedules
      • Priority visits and optional visits
      • Visit service level agreement (SLA)
    • Recommendations
      • Recommendations
      • Visit time window recommendations
      • Visit group time window recommendations
    • 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
    • Real-time planning (preview)
      • Real-time planning (preview)
      • Real-time planning: extended visit (preview)
      • Real-time planning: reassignment (preview)
      • Real-time planning: emergency visit (preview)
      • Real-time planning: no show (Preview)
      • Real-time planning: technician ill (Preview)
      • Real-time planning: pinning visits (preview)
    • Scenarios
      • Long-running visits
    • Changelog
    • Upgrade to the latest version
    • Feature requests

Constraints

1. Overview

Constraints can be considered hard, medium, or soft.

Hard constraints represent rules and limitations of the real world that any planning solution has to respect. For instance, there are only 24 hours in a day and people can only be in one place at a time. Hard constraints also include rules that must be adhered to, for instance, technicians must have specific skills for specific jobs.

Breaking hard constraints results in infeasible plans.

Medium constraints help manage plans when resources are limited, for instance, scheduling as many mandatory visits as possible. Medium constraints incentivize Timefold Platform to assign as many customer visits as possible.

Soft constraints help optimize plans based on the business goals, for instance, minimizing travel time.

To help determine the quality of solutions, plans are assigned a score with values for hard, medium, and soft constraints.

0hard/-257medium/-6119520soft

Timefold examines many solutions during solving and is incentivized to use the solution with the highest score.

From the example score above, you can see zero hard constraints were broken, while both the medium and soft scores have negative values (the scores do not show how many constraints were broken, but values associated with those constraints).

Because breaking hard constraints would result in an infeasible solution, a solution that breaks zero hard constraints and has a soft constraint score of -1,000,000 is better than a solution that breaks 1 hard constraint but has a soft constraint score of 0.

It’s important to note that constraints have competing goals, for instance, a constraint that is concerned with fairness or load balancing may result in a solution that takes longer to execute, whereas constraints concerned with shortening the overall solution time may result in a solution that isn’t fairly disrupted among the available resources.

Timefold balances the competing priorities of constraints to arrive at solutions with the best overall score.

2. Field service routing constraint groups and constraints

Constraints are grouped together with similar constraints into constraint groups. The following constraint groups and constraints are available in field service routing.

2.1. Dependencies between visits

The constraints in this group are designed to sequence visits in the correct order, and if delays are required, make sure the delay is included.

The following constraints are part of the Dependencies between visits constraint group.

  • Require the same vehicle for dependent visit

  • Require visit dependency delay

  • Require visit dependency prerequisite assigned

For more information about this constraint group see the Visit dependencies guide.

2.2. Fairness

The constraint in this group is designed to distribute work fairly across all technicians.

The following constraint is part of the Distribute work fairly across all technicians constraint group.

  • Balance time utilization

For more information about this constraint group see the Fairness guide.

2.3. Lunch breaks and personal appointments

The constraints in this group are designed to apply breaks (lunch, appointments, team meetings, etc) for the technicians.

The following constraints are part of the Lunch breaks and personal appointments constraint group.

  • Max floating break end time (hard)

  • No conflict with fixed break

  • No conflict with fixed location break

For more information about this constraint group see the Lunch breaks and personal appointments guide.

2.4. Movable visits and multi-day schedules

The constraints in this group are designed to delay flexible visits until a technician is in the neighborhood.

The following constraints are part of the Movable visits and multi-day schedules constraint group.

  • Balance movable and non-movable visits

  • Prefer visits scheduled to the earliest day

For more information about this constraint group see the Movable visits and multi-day schedules guide.

2.5. Multi-vehicle visits

The constraint in this group is designed to send multiple technicians to a visit together for compliance, efficiency, or safety reasons, while let them travel independently before and afterward the visit.

The following constraint is part of the Multi-vehicle visits constraint group.

  • No semi-assigned visit groups

For more information about this constraint group see the Multi-vehicle visits guide.

2.6. Priority visits and optional visits

The constraints in this group are designed to schedule as much high priority work as possible when there aren’t enough people to cover all the work.

The following constraints are part of the Priority visits and optional visits constraint group.

  • Minimize the visit completion risk

  • Prefer scheduling optional visits

  • Require scheduling mandatory visits

For more information about this constraint group see the Priority visits and optional visits guide.

2.7. Route optimization

The constraints in this group are designed to reduce the travel time and mileage per technician to increase productivity and reduce CO2 emissions.

The following constraints are part of the Route optimization constraint group.

  • Max shift travel time (soft)

  • Max shift travel time (hard)

  • Max travel time per visit (hard)

  • Minimize travel distance

  • Minimize travel time

For more information about this constraint group see the Route optimization guide.

2.8. Service level agreements

The constraint in this group is designed to make sure visits are completed within service level agreement times.

The following constraints are part of the Service level agreements constraint group.

  • Latest SLA end time

For more information about this constraint group see the Visit service level agreement (SLA) guide.

2.9. Shift hours and overtime

The constraints in this group are designed to honor technicians' working hours and avoid unnecessary overtime.

The following constraints are part of the Shift hours and overtime constraint group.

  • Max last visit departure time (hard)

  • Max last visit departure time (soft)

  • Max shift end time (hard)

  • Max shift end time (soft)

For more information about this constraint group see the Shift hours and overtime guide.

2.10. Skills

The constraints in this group are designed to match skill requirements, seniority, and customer affinity to reduce the service duration per task.

The following constraints are part of the Skills constraint group.

  • Minimize scheduling vehicles with unnecessary skill levels

  • Require skills

For more information about this constraint group see the Skills guide.

2.11. Technician costs

The constraint in this group is designed to avoid unnecessary technician costs by outsourcing less work, using cheaper freelancers, and reducing overtime costs.

The following constraint is part of the Technician costs constraint group.

  • Minimize shift costs

For more information about this constraint group see the Technician costs guide.

2.12. Technician rating

The constraint in this group is designed to assign visits to technicians with the highest ratings.

The following constraint is part of the Technician rating constraint group.

  • Maximize technician rating

For more information about this constraint group see the Technician ratings guide.

2.13. Time windows and opening hours

The constraints in this group are designed to schedule visits to start and end within their time windows.

The following constraints are part of the Time windows and opening hours constraint group.

  • Require service max end time

  • Require service max start time

For more information about this constraint group see the Time windows and opening hours guide.

2.14. Visit requirements, area affinity and tags

The constraints in this group are designed to assigned required or preferred technicians for particular visits, keep technicians within their areas, and limit a technician’s time per visit type.

The following constraints are part of the Visit requirements, area affinity and tags constraint group.

  • No visits outside coverage area

  • Prefer visit vehicle match preferred vehicles

  • Require tags

  • Require visit vehicle match required vehicles

  • Require visit vehicle not match prohibited vehicles

For more information about this constraint group see the Visit requirements guide.

3. Constraint weights

Every constraint has a weight and a match score that will be applied to the dataset score every time the constraint is matched.

The final score for an instance of a constraint being matched is calculated by multiplying the constraint weight by the match score.

Active soft constraints have a default weight of 1, meaning that all soft constraints are equally weighted. Constraint weights can be changed to make some constraints more important than others.

A constraint with a weight of 10, increases the impact of the score by a factor of 10 (10 * match score).

When a constraint has a weight of 0, the constraint score has no impact.

The match score is derived from the penalty or reward constraints apply when they are matched.

For instance, if a rule specifies a technician should finish work at 17:00, but the technician is assigned overtime and does not arrive at their end location until 17:10, the Max shift end time (soft) will return a score of -600 (the penalty is derived from every second between the time they should have finished and the time they did finish).

If the maxSoftShiftEndTimeWeight (which sets the weight of the Max shift end time (soft) constraint) is set to 1, the final soft score for this instance of the constraint matching will be -600. If the maxSoftShiftEndTimeWeight is set to 2, the final soft score for this instance of the constraint matching will be -1200.

3.1. Constraint weight configuration

Constraint weights can be configured in individual input datasets or as part of a configuration profile that can be reused with future input datasets.

3.1.1. Configure a configuration profile

Constraint weights can be configured in Timefold Platform by creating a configuration profile and setting the weight in the configuration profile:

  1. Log in to Timefold Platform: app.timefold.ai

  2. Select the field service routing tile.

  3. Select Configuration profiles.

  4. Add a new configuration profile (or modify an existing profile) and configure the constraint weights.

The configuration profile can be specified when you submit a new dataset by appending a query parameter with the configuration profile name to the POST URL.

For instance, if the configuration profile is called test, the query parameter would be: ?configurationId=test

Learn more about configuration parameters and profiles.

3.1.2. Configure constraint weights in an input dataset

Constraint weights can be configured per JSON input dataset.

For instance, to set the exampleWeight to 10 add the following:

{
  "config": {
    "model": {
      "overrides": {
        "exampleWeight": 10
      }
    }
  }
}

3.2. Available constraint weights

Constraint Constraint weight

Balance technicians' workloads

balanceTimeUtilizationWeight

Latest SLA end time

latestSlaEndTimeWeight

Max last visit departure time (soft)

maxSoftLastVisitDepartureTimeWeight

Max shift end time (soft)

maxSoftShiftEndTimeWeight

Max shift travel time (soft)

maxSoftShiftTravelTimeWeight

Maximize technician rating (soft) 0 by default

maximizeTechnicianRatingWeight

Minimize vehicle shift cost

minimizeShiftCostsWeight

Minimize travel distance

minimizeTravelDistanceWeight

Minimize travel time

minimizeTravelTimeWeight

Minimize scheduling vehicles with unnecessary skill levels

minimizeUnnecessarySkillsWeight

Minimize the visit completion risk

minimizeVisitCompletionRiskWeight

Prefer scheduling optional visits

preferSchedulingOptionalVisitsWeight

Prefer visits scheduled to the earliest day

preferVisitsScheduledToEarliestDayWeight

Prefer scheduled vehicle matches preferred vehicle

preferVisitVehicleMatchPreferredVehiclesWeight

Next

  • See the full API spec or try the online API.

  • Learn more about field service routing from our YouTube playlist.

  • Learn about balancing different optimization goals.

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