Resumable Jobs

resumable lets a long job be interrupted by a period in which the resource is unavailable, and resumed once that period ends. Without it, a job can never straddle an unavailability: the solver pushes the whole job until after the unavailability ends.

resumable only applies to UNAVAILABILITY breaks.WINDOWED, DRIVE and DUTY breaks are inserted between jobs, never inside one, so they can never interrupt a job and resumable has no effect on them. If you set resumable: true on a resource whose only breaks are WINDOWED, the flag is silently ignored.

Overview

Setting resumable: true on a job enables:

The job to be paused by an overlapping UNAVAILABILITY break and resumed afterward
Long jobs to fit into shifts that contain a fixed unavailability
Any travel to and from the unavailability’s own location to be accounted for

Basic Configuration

Mark the job resumable, and express the interruption as an UNAVAILABILITY break:

{
  "jobs": [
    {
      "name": "installation-project",
      "location": {"latitude": 52.520, "longitude": 13.405},
      "duration": 14400,  // 4 hours
      "resumable": true   // May be paused by an UNAVAILABILITY break
    },
    {
      "name": "quick-repair",
      "location": {"latitude": 52.523, "longitude": 13.401},
      "duration": 1800,   // 30 minutes
      "resumable": false  // Must be completed without interruption (default)
    }
  ],
  "resources": [
    {
      "name": "technician-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "breaks": [{
          "type": "UNAVAILABILITY",
          "from": "2024-03-15T12:00:00Z",
          "to": "2024-03-15T13:00:00Z"
        }]
      }]
    }
  ]
}

Default Behavior: jobs are non-resumable (resumable: false). Only mark a job resumable when pausing the work halfway is operationally acceptable.

An UNAVAILABILITY break has no duration field — it is a fixed interval, and its length is simply to minus from. This is the trade-off versus a WINDOWED break: you gain the ability to interrupt a job, and you give up the solver’s freedom to choose when within a window the break is taken.

How Resumable Jobs Work

Break interruption

Job starts

The resource arrives and begins the resumable job.

Unavailability begins

The unavailability’s fixed from time arrives and the job is paused.

Break is taken

If the break defines start/end locations, travel from the job to start and back from end to the job is added to the job’s duration. With no locations, the pause costs only the interval itself.

Job resumes and completes

The remaining work is carried out after to, and the job’s departure time is pushed by the length of the interruption.

Example timeline

A 4-hour resumable job started at 08:00, with an unavailability from 12:00 to 13:00:

00 - Arrive at job location
00 - Start 4-hour installation (resumable)
00 - Unavailability begins - 3 hours completed, 1 hour remaining
00 - Resource unavailable
00 - Resume installation
00 - Installation complete (elapsed 6h for 4h of work)
00 - Available for the next job

The same job with resumable: false cannot straddle 12:00–13:00 at all: the solver either starts it early enough to finish before 12:00, or pushes its start to 13:00.

Interaction with break types

Break type	Interrupts a job?	Effect of `resumable`
`UNAVAILABILITY`	Yes	This is the only type `resumable` affects.
`WINDOWED`	No — placed between jobs	None. The break is attached to the first job whose ready time falls after `from`.
`DRIVE`	No — placed between jobs	None. Triggered by accumulated drive time.
`DUTY`	No — placed between jobs	None. Triggered by accumulated working time.

Unavailability break

The interruption mechanism. Optionally give it start/end locations when the resource has to be somewhere specific (end requires start, and defaults to it):

{
  "breaks": [{
    "type": "UNAVAILABILITY",
    "from": "2024-03-15T13:00:00Z",
    "to": "2024-03-15T14:00:00Z",
    "start": {"latitude": 52.520, "longitude": 13.405}
  }]
}

Omit both locations when the pause happens wherever the resource already is — no detour travel is then added.

Windowed break

Flexible in when it is taken, but it never interrupts a job:

{
  "breaks": [{
    "type": "WINDOWED",
    "from": "2024-03-15T11:00:00Z",
    "to": "2024-03-15T14:00:00Z",
    "duration": 3600
  }]
}

Note that a WINDOWED break is attached to the first job whose ready time falls after from, so with a single break per shift the to bound has little effect, and if no job follows within the shift the break is not placed at all. Use UNAVAILABILITY when the break must be honoured.

Drive break

Triggered by accumulated driving time, between jobs:

{
  "breaks": [{
    "type": "DRIVE",
    "driveTime": 16200,  // After 4.5 hours driving
    "duration": 2700     // 45-minute break
  }]
}

Use Cases

Long service appointments

A 6-hour job in a shift that contains a fixed midday unavailability:

{
  "jobs": [
    {
      "name": "server-room-upgrade",
      "duration": 21600,  // 6 hours
      "resumable": true,
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "resources": [{
    "name": "it-specialist",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T18:00:00Z",
      "breaks": [
        {
          "type": "UNAVAILABILITY",
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T10:30:00Z"
        },
        {
          "type": "UNAVAILABILITY",
          "from": "2024-03-15T12:00:00Z",
          "to": "2024-03-15T13:00:00Z"
        }
      ]
    }]
  }]
}

Without resumable: true this instance is infeasible: 6 hours of work cannot fit into any gap between the unavailabilities.

Mixed job types

{
  "jobs": [
    {
      "name": "emergency-repair",
      "duration": 2700,
      "resumable": false,  // Cannot interrupt emergency work
      "priority": 100
    },
    {
      "name": "preventive-maintenance",
      "duration": 14400,
      "resumable": true,   // Can pause for an unavailability
      "priority": 50
    }
  ]
}

Constraints and Behavior

Important considerations:

resumable is ignored unless the resource has UNAVAILABILITY breaks
A non-resumable job is not rejected by an overlapping unavailability — it is pushed until after the unavailability ends, which may in turn push it out of its time window
Travel to a break’s start location and back from its end location is added to the job’s duration; travel between start and end during the break is not modelled
A job can be interrupted by several consecutive unavailabilities

Solver behavior: unavailability intervals are fixed input, not decisions — the solver does not choose when they occur. What it optimises is which jobs sit around them, and whether a resumable job is worth starting before one.

Troubleshooting

`resumable: true` appears to do nothing

Cause: the resource’s breaks are WINDOWED, DRIVE or DUTY. Those are placed between jobs and never interrupt one, so the flag is never consulted.Solution: model the interruption as an UNAVAILABILITY break with an explicit from/to.

Job not scheduled despite being resumable

Causes:

The time window is too tight for the job plus the interruption
The break’s start/end locations add too much detour travel
Other constraints (hard tags, shift end, overtime limit) prevent assignment

Solutions:

Widen the job’s time windows, or extend the shift / allow overtime
Omit start/end on the unavailability so the pause adds no travel
Enable options.explanation to see which constraint is binding

Break placement looks inefficient

Cause: UNAVAILABILITY is a fixed interval by design — the solver cannot move it.Solution: if the timing is genuinely flexible and no job needs interrupting, use a WINDOWED break instead and let the solver choose the moment.

Performance Impact

Factor	Impact
Few unavailability breaks	Minimal impact
Many unavailability breaks per shift	Moderate impact
Consecutive/chained unavailabilities	Higher impact
Tight time windows around unavailabilities	Highest impact

Break Management

Configure the four break types and their rules

Time Windows

Coordinate job timing with breaks

Job Complexity

Balance workload across resources

Advanced Constraints

Additional scheduling constraints

Platform

VRP API

Fill API

Resumable Jobs

Resumable Jobs

Overview

Basic Configuration

How Resumable Jobs Work

Break interruption

Example timeline

Interaction with break types

Unavailability break

Windowed break

Drive break

Use Cases

Long service appointments

Mixed job types

Constraints and Behavior

Troubleshooting

Performance Impact

Break Management

Time Windows

Job Complexity

Advanced Constraints

​Resumable Jobs

​Overview

​Basic Configuration

​How Resumable Jobs Work

​Break interruption

​Example timeline

​Interaction with break types

​Unavailability break

​Windowed break

​Drive break

​Use Cases

​Long service appointments

​Mixed job types

​Constraints and Behavior

​Troubleshooting

​Performance Impact

​Related Features

Break Management

Time Windows

Job Complexity

Advanced Constraints

Resumable Jobs

Overview

Basic Configuration

How Resumable Jobs Work

Break interruption

Example timeline

Interaction with break types

Unavailability break

Windowed break

Drive break

Use Cases

Long service appointments

Mixed job types

Constraints and Behavior

Troubleshooting

Performance Impact

Related Features