Data model

This section describes the Field Service Routing data model.

1. Route plan

The route plan is the top-level object of the Field Service Routing API. It serves both as an input and output of the API.

It is a container for all the data necessary for optimizing the route plan, as the table below summarizes.

Id Required Format Description

name

false

string

A label identifying the route plan.

planningWindow

true

object

The planning window is a time interval to schedule for.

constraintConfiguration

false

object

The constraint configuration contains global parameters of constraints.

vehicles

true

array

An array of all vehicles.

vehicleShifts

true

array

An array of all vehicle shifts.

visits

true

array

An array of all visits that should be scheduled.

visitGroups

false

array

An array of all visit groups that should be scheduled. A visit group defines a multi-resource visit, i.e. a visit that needs to be serviced by multiple vehicle shifts at the same time.

tags

false

array

An array of all tags to match by a vehicle shift with a visit.

freezeDeparturesBeforeTime

false

string (ISO-8601 date and time)

The date and time before which all vehicle shifts are considered pinned ("frozen").

In other words, every visit assigned to a vehicle shift which the shift already completed or started travelling to before the freezeDeparturesBeforeTime is considered pinned and will not be reassigned to another shift or moved to a different position in the list of assigned visits for the shift.

Usable for real-time planning scenario, such as re-submitting a plan that contains already assigned visits which must be pinned, such as in the following scenario:

1. The plan A is submitted to the solver, the solution for A contains assigned visits to shifts.

2. A few hours later, the solution for A is used as a base for an updated plan B adding new visits to be assigned after a (user-chosen) time T.

3. The plan B contains visits already planned (assigned during A's planning) to a time before T that need to be preserved, since they already happened.

4. When the plan B is submitted for solving, it needs to have the freezeDeparturesBeforeTime set to T.

When omitted, no pinning/freeze is in effect.

The Field Service Routing adds the following attributes in the reply.

Id Format Description Example

status

object

The current status of the route plan

See route plan status

totalTravelTime

string (ISO-8601 duration)

The total travel time by all the vehicle shifts.

"PT2H15M"

totalUnassignedVisits

number

The total amount of visits that were not assigned in the route plan.

10

1.1. Route plan status

The route plan status object is used to give more information about the solver run.

Id Format Description Example

id

string

Unique identifier of the solver run

"3e26e4d5-9447-46c5-8c3b-a8fef78bc1cb"

name

string

Name of the solver run

"VehicleRoutePlan-2023-11-29T09:09:30.825044+01:00"

submitDateTime

string (ISO-8601 date, time and time zone offset)

The date the route plan was submitted to solve.

"2023-11-29T09:09:30.825044+01:00"

solverStatus

string (one of: "NOT_SOLVING", "SOLVING_SCHEDULED", "SOLVING_ACTIVE", "SOLVING_COMPLETED", "SOLVING_FAILED", "SOLVING_DISABLED")

The status of the solver.

"SOLVING_COMPLETED"

score

string

The current score of the route plan, as calculated by the solver.

"0hard/-7medium/-8116soft"

2. Constraint configuration

The constraint configuration contains weights of soft constraint and additional constraint parameters, influencing whether these constraints trigger and how much they impact the solution’s score.

Id Format Description Example

endLocationMaxArrivalTimeSoftLimitWeight

number

A weight of the End location max arrival time soft limit constraint.

1

lastVisitMaxDepartureTimeSoftLimitWeight

number

A weight of the Last visit max departure time soft limit constraint.

1

minimizeTravelTimeWeight

number

A weight of the Minimize travel time constraint.

1

minimizeTravelDistanceWeight

number

A weight of the Minimize travel distance constraint.

0

preferVisitsScheduledToEarliestDayWeight

number

A weight of the Prefer visits scheduled to the earliest day constraint.

1

preferSchedulingOptionalVisitsWeight

number

A weight of the Prefer scheduling optional visits constraint.

1

minimizeVisitCompletionRiskWeight

number

A weight of the Minimize the visit completion risk constraint.

1

visitCompletionRiskMinimalTimeToShiftEnd

string (ISO-8601 duration)

A length of the time window between the visit departure time and the vehicle shift end. If a visit ends in this time window, its completion is considered risky.

"PT1H"

visitCompletionRiskMinimalPriority

string

A minimal priority of a visit to consider it for the risk evaluation.

"LOW"

3. Planning window

The planning windows specified a time range to plan for.

Id Required Format Description Example

startDate

true

string (ISO-8601 date and time)

A start date of the planning window.

"2023-11-27T00:00:00"

endDate

true

string (ISO-8601 date and time)

An end date of the planning window.

"2023-11-30T23:59:59"

4. Vehicle

The vehicle represents a single vehicle visiting customers across the planning window.

Id Required Format Description Example

id

true

string

A unique string identifier of the vehicle.

"Alice Fox"

vehicleType

true

string

A type of the vehicle

"VAN"

5. Vehicle shift

Vehicle shift is an instance of a vehicle projected to a time interval in which the vehicle operates. In a multi-day field service routing, a vehicle shift a typically a single working day of the vehicle crew. After the optimization process, each vehicle shift contains an ordered list of visits.

Id Required Format Description Example

id

true

string

A unique string identifier of the vehicle shift.

"vehicle-shift-8026f548"

vehicle

true

string

A unique string identifier of the associated vehicle.

"Alice Fox"

shiftStartTime

true

string (ISO-8601 date and time)

A start date and time of the vehicle shift.

"2023-11-27T09:00:00"

shiftStartsFrom

false

string

Specifies if the shift starts from its start location or from the first visit.

"SHIFT_START_LOCATION" (default) or "FIRST_VISIT"

lastVisitMaxDepartureTimeSoftLimit

false

string (ISO-8601 date and time)

A maximal departure time from the last visit (soft).

"2023-11-27T17:00:00"

lastVisitMaxDepartureTimeHardLimit

false

string (ISO-8601 date and time)

A maximal departure time from the last visit (hard).

"2023-11-27T17:15:00"

endLocationMaxArrivalTimeSoftLimit

false

string (ISO-8601 date and time)

A maximal arrival time to the end location (soft).

"2023-11-27T17:00:00"

endLocationMaxArrivalTimeHardLimit

false

string (ISO-8601 date and time)

A maximal arrival time to the end location (hard).

"2023-11-27T17:15:00"

maxTravelTimePerVisitHardLimit

false

string (ISO-8601 duration)

A maximal travel time limit per visit (hard).

"PT1H"

startLocation

true

array (latitude, longitude)

A start location coordinates of the vehicle shift.

[ 52.5441475, -0.265105009 ]

endLocation

true

array (latitude, longitude)

An end location coordinates of the vehicle shift.

[ 52.5441475, -0.265105009 ]

tags

false

array

An array of tag references.

["plumber", "emergency"]

serviceDurationMultipliers

false

array

Multipliers affecting a visit service duration.

[ { "tag": "plumber", "multiplier": 0.8 } ]

temporaryTagSets

false

array

Tags that are applicable within specified time intervals.

[ { "start": "2023-11-27T09:00:00", "end": "2023-11-27T13:00:00", "tags": [ "plumber" ] }

floatingBreaks

false

array

An array of floating breaks.

[{ "id": "233", "triggerTime": "2023-11-27T12:00:00", "duration": "PT1H" } ]

unavailabilities

false

array

An array of unavailabilities.

[{ "id": "123", "startTime": "2023-11-27T14:00:00", "endTime": "2023-11-27T16:00:00" } ]

movableOccupationRatioThreshold

false

number

Influences the ratio between movable and non-movable visits to assigned to this vehicle shift.

"0.5"

The Field Service Routing adds the following attributes in the reply.

Id Format Description Example

visits

array

An array of visit references in the order of the vehicle’s itinerary.

["974a7e67", "75b436f"]

statistics

object

Statistics of the vehicle shift route.

6. Vehicle shift statistics

Id Format Description Example

totalTravelTime

string (ISO-8601 duration)

The total travel time by the vehicle shift.

"PT2H15M"

travelTimeFromStartLocationToFirstVisit

string (ISO-8601 duration)

The travel time from the start location to the first visit.

"PT10M"

travelTimeBetweenVisits

string (ISO-8601 duration)

The total travel time between visits excluding the travel time from the start location to the first visit and the travel time from the last visit to the end location.

"PT2H"

travelTimeFromLastVisitToEndLocation

string (ISO-8601 duration)

The travel time from the last visit to the end location.

"PT5M"

totalTravelDistanceMeters

integer

The total travel distance by the vehicle shift in meters.

25000

travelDistanceFromStartLocationToFirstVisitMeters

integer

The travel distance from the start location to the first visit in meters.

3000

travelDistanceBetweenVisitsMeters

integer

The total travel distance in meters between visits excluding the distances from the start location to the first visit and from the last visit to the end location.

20000

travelDistanceFromLastVisitToEndLocationMeters

integer

The travel distance from the last visit to the end location in meters.

2000

endLocationArrivalTime

string (ISO-8601 date and time)

The arrival time of the vehicle shift at the endLocation.

"2023-11-27T17:15:00"

7. Visit

A visit represents an individual service job at customer location. For every visit, you can define the following attributes.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit.

"974a7e67"

name

true

string

A name of the visit.

"Alex Pot"

location

true

array (latitude, longitude)

A location coordinates of the visit.

[ 52.0233688, 0.239470348 ],

minimumStartTime

true

string (ISO-8601 date and time)

A minimum start time of the visit

"2023-11-27T10:00:00"

maximumStartTime

true

string (ISO-8601 date and time)

A maximum start of the visit

"2023-11-27T10:00:00"

maximumEndTime

true

string (ISO-8601 date and time)

A maximum end of the visit

"2023-11-27T14:00:00"

serviceDuration

true

string (ISO-8601 duration)

The estimated duration of the service.

"PT15M"

serviceDurationAdjustment

false

string (ISO-8601 duration)

The adjustment of the serviceDuration. Can be negative.

"PT15M"

requiredTags

false

array

An array of tag references required by this visit.

["plumber", "emergency"]

priority

false

string

Visit priority.

"HIGH"

visitDependencies

false

array

An array of visit dependencies.

[ { "id": "1", "precedingVisit": "58f18bb7", "minDelay": "PT2H" } ]

pinningRequested

false

boolean

Determines if the user requested to pin this particular visit (the visit must already be assigned).

Setting pinningRequested == true on a visit forces this visit pinned even when the departure to this visit happens after the Route Plan freezeDeparturesBeforeTime (so it is not considered pinned by default). Please note that all previous visits in the vehicle shift assigned to this visit must be pinned, otherwise an exception is thrown.

Useful when pinning needs to be extended beyond freezeDeparturesBeforeTime only for a particular visit or visits.

true, false (default)

minimumStartTravelTime

false

string (ISO-8601 date and time)

The minimum time when a shift can start travelling to this visit. When set, it can postpone visit’s arrivalTime.

Important: The value is set automatically during solving, the user must only preserve the value when re-submitting a plan that contains already assigned pinned visits.

For example, consider the following scenario:

1. The plan A is submitted to the solver, the solution for A contains assigned visits to shifts, including visits' minimumStartTravelTime.

2. A few hours later, the solution for A is used as a base for an updated plan B adding new visits to be assigned after a (user-chosen) time T.

3. The plan B contains visits already planned (assigned during A's planning) to a time before T that need to be preserved, since they already happened.

4. When the plan B is submitted for solving with the freezeDeparturesBeforeTime set to T, the model will: a. use the existing minimumStartTravelTime values of pinned visits to calculate their arrivalTime correctly, b.calculate minimumStartTravelTime values for the unpinned visits to ensure they are assigned into the time period after the freezeDeparturesBeforeTime.

"2023-11-27T14:00:00"

Apart from the attributes above, that serve as an input for the optimization, the Field Service Routing adds the following attributes in the reply.

Id Format Description Example

vehicleShift

string

A reference to a vehicle shift assigned to this visit.

"vehicle-shift-8026f548"

arrivalTime

string (ISO-8601 date and time)

The arrival time of the vehicle at the customer location.

"2023-11-27T11:10:09"

startServiceTime

string (ISO-8601 date and time)

The beginning of the service at the customer location.

"2023-11-27T11:10:09"

departureTime

string (ISO-8601 date and time)

The end of the service at the customer location.

"2023-11-27T11:25:09"

effectiveServiceDuration

string (ISO-8601 duration)

The effective duration of the service after applying the serviceDurationMultipliers of the assigned vehicle shift and adding the serviceDurationAdjustment.

"PT15M"

travelTimeFromPreviousStandstill

string (ISO-8601 duration)

The travel time either from the previous visit or from the start location of the assigned vehicle shift.

"PT10M3S"

travelDistanceMetersFromPreviousStandstill

integer

The travel distance either from the previous visit or from the start location of the assigned vehicle shift.

5000

breakDuration

string (ISO-8601 duration)

The duration of all breaks the assigned vehicle shift is eligible to take between the previous visit and this visit.

"PT30M"

8. Visit Group

A visit group represents a multi-resource visit, i.e. a group of individual service jobs that need to be performed at customer location at the same time. For every visit group, you can define the following attributes.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit group.

"974a7e67"

serviceDurationStrategy

false

string

The strategy to calculate the service duration of the visits in this visit group:

INDIVIDUAL: The service duration of each visit in the group is calculated independently based on the service proficiency modifiers for the assigned vehicle shift. When multiple service proficiency modifiers match the visit’s requirements, their average is used to adjust the service duration. (default)

BEST_PROFICIENCY: The service duration of each visit in the group is calculated using the best service proficiency modifiers (separately for each tag) from all vehicle shifts assigned to the visits in the visit group. When multiple service proficiency modifiers match the requirements of a visit in the group, their average is used to adjust the visit’s service duration.

"INDIVIDUAL" (default), "BEST_PROFICIENCY"

visits

false

array

An array of visits that form together the visit group.

[ {"id":"1abcd","name":"John","location":[49.288087,16.562172],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T12:00:00","serviceDuration":"PT1H","priority":"NORMAL"} ],

9. Tag

Tags connect visits with the right vehicle shift. For instance, a visit may require a plumber skill, which limits the range of vehicle shifts that can pick up the visit.

Id Required Format Description Example

name

true

string

A unique string identifier of the tag.

"plumber"

10. Visit dependency

A visit can declare a dependency on some other visit, specifying a minimal delay between them. For example, a technological break between two maintenance tasks.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit dependency.

"25"

precedingVisit

true

string

A reference to the preceding visit that must be completed first.

"58f18bb7"

11. Floating break

Represents a break a vehicle shift is eligible for that is scheduled to the first available interval between two visits after the triggerTime. The arrival time to the visit after the scheduled break is delayed accordingly.

Id Required Format Description Example

id

true

string

A unique string identifier of the floating break.

"353"

triggerTime

true

string (ISO-8601 date and time)

The earliest time to schedule the break at.

"2023-11-27T12:00:00"

12. Unavailability

Represents a time interval in which the vehicle shift is unavailable and thus, it cannot work on any visit or travel to the next location. The travel to the next location starts only after the unavailability, as the location of the vehicle during the unavailability is unknown.

Id Required Format Description Example

id

true

string

A unique string identifier of the unavailability.

"123"

startTime

true

string (ISO-8601 date and time)

The unavailability start time.

"2023-11-27T14:00:00"

endTime

true

string (ISO-8601 date and time)

The unavailability end time.

"2023-11-27T16:00:00"

location

false

array (latitude, longitude)

The location coordinates of the unavailability

[ 52.0233688, 0.239470348 ],