Terminology

This section lists frequently used terms and their meanings:

Scheduled periods within a vehicle shift when a technician is not available for visits. Floating breaks (such as lunch breaks) can be taken at any location and are slotted in around visits. Fixed breaks occur at a specific time (optionally at a specific location); when a location is provided, travel time to and from the break is included in the route plan. Learn more about lunch breaks and personal appointments.

The hard, medium, and soft rules that must be taken into account when creating a field service routing plan. Learn more about constraints.

In home care, sending the same caregiver, or a small set of familiar caregivers, to a client over time. Continuity of care is modeled by setting preferred vehicles on a client’s visits. Learn more about preferred vehicles.

A geographic area defining where a technician can work, also called a service territory. A required coverage area is enforced as a hard constraint; a preferred coverage area is a soft constraint. Coverage areas are defined using GeoJSON polygon geometry, and can be set on a vehicle or overridden per vehicle shift (independently for the required and preferred area). Learn more about coverage areas.

Timefold accepts input datasets that include information about customer visits and the available vehicles 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.

An urgent, unplanned visit, also called an emergency callout, that must be added to a route plan that is already in progress. Real-time planning inserts the emergency visit and reassigns other visits where needed. Learn more about emergency visits.

The principle of distributing workload evenly across technicians. Fairness is measured as a percentage, where 100% indicates a perfectly balanced workload. Learn more about fairness.

The percentage of visits where the technician resolves the issue on the first visit, without needing a return visit. Assigning visits to technicians with the right skills raises the first-time-fix rate. First-time-fix rate is tracked in your own systems, not by the Field Service Routing model. Learn more about skills.

A break that occurs at a specific start and end time. When a location is provided, Timefold includes travel time to and from the break in the route plan. When no location is provided, the time is blocked but travel time cannot be accounted for. Fixed breaks model personal appointments, team meetings, and hotel stays. Learn more about fixed breaks.

A break with a defined duration that can be taken at any location within a specified time window. Timefold slots floating breaks in around visits to minimize disruption to the route. Lunch breaks are a typical example. Learn more about floating breaks.

A mandatory visit has a time window that falls within the current planning window and must be scheduled. An optional visit has an optional priority or a time window that extends beyond the planning window and can be deferred to a future day. Learn more about priority visits and optional visits.

A visit with a time window that spans multiple days and can be scheduled on any of those days. Contrast with non-movable visits, which have a single-day time window. Learn more about multi-day schedules and movable visits.

Time a technician works beyond the normal end of their vehicle shift. Overtime incurs a soft penalty, so Timefold assigns it only when it improves the overall plan, for example, to complete two visits on the same day instead of sending a technician back the next day. Learn more about overtime.

Locking a visit to its assigned technician and position in the route so it cannot be moved during re-planning. Useful when a technician is already en route to or working on a visit. Learn more about pinning visits.

The time period that will have visits scheduled during planning. Learn more about planning windows.

Preventive maintenance is planned work that keeps equipment running, such as quarterly inspections. Reactive maintenance, also called corrective work, responds to failures and emergencies. Both types of work compete for the same technicians, and visit priorities control the balance between them. Learn more about priority visits and optional visits.

The ability to adapt a route plan in response to disruptions such as a technician taking ill, a visit taking longer than expected, or an emergency visit being added. Learn more about real-time planning.

An API that quickly provides a range of time window options for a visit when a customer is requesting service, without having to wait for a full solve. Learn more about recommendations.

Visits that repeat on an agreed cadence, for example, monthly or quarterly. Each occurrence is modeled as a mandatory visit with a time window that reflects the cadence. Learn more about time windows.

The process of minimizing the travel time or distance technicians spend driving between visits. By default, Timefold minimizes travel time. Learn more about route optimization.

A route plan contains the travel, visits, and breaks that are assigned to vehicles. The route plan for a dataset can be found in the itinerary object of the output dataset.

A contractual commitment that a visit must be completed by a specific time. Visits that miss their SLA deadline incur a soft score penalty. Learn more about visit SLAs.

Capabilities that technicians possess and customer visits may require. A technician must have all required skills to be assigned to a visit. Learn more about skills.

Labels applied to vehicle shifts to model additional requirements not covered by skills or visit requirements. Visits can require specific tags, restricting which technicians can be assigned to them. Learn more about tags.

The wages and overtime rates associated with technicians. Timefold can minimize the total cost of all vehicle shifts in a plan. Learn more about technician costs.

A numerical quality rating for a technician, typically derived from customer feedback. Timefold can use ratings to prefer higher-rated technicians for visits when other constraints allow. Learn more about technician ratings.

The share of a technician’s shift spent working at visits rather than traveling or waiting. Utilization is often tracked as stops per day, the number of visits a technician completes in a shift. Reducing windshield time raises technician utilization. The model doesn’t report utilization directly, but you can calculate it from the shift metrics in the output dataset, such as totalServiceDuration, totalTravelTime, totalWaitingTime, totalShiftDuration, and assignedVisits. Learn more about model output.

The period during which a customer visit can be scheduled. Required time windows are enforced as hard constraints; preferred time windows are soft constraints. Learn more about time windows.

Vehicles and technicians complete visits at customer locations.

A single work period when a technician can visit customer locations. Learn more about vehicle shifts.

A visit to a customer’s location to provide a service.

A relationship between visits that controls the order in which they are completed. For example, an assessment visit may need to be completed before a repair visit can begin. Learn more about visit dependencies.

A set of visits that must be started at the same time by multiple technicians either in the same or multiple locations. Learn more about multi-vehicle visits.

A revenue value assigned to a visit that influences scheduling priority when capacity is limited. Timefold maximizes total profit across all scheduled visits. Learn more about visit profit.

Restrictions on which technicians can be assigned to a visit. A required technician must complete the visit; a preferred technician is assigned if possible; an excluded technician is never assigned. Learn more about visit requirements.

The time technicians spend driving between visits. Windshield time is unproductive, so reducing it is a key goal of route optimization. Learn more about route optimization.