Planning window

The planning window is the upcoming time interval that the solver schedules employee shifts for.

Scheduling is typically done for an upcoming period such as the next 2 weeks. The input dataset can also include shifts that occurred before the planning window, providing constraints that need to look further back (such as work limits) the history they need.

For example, suppose today is 30th June 2026, and you want to plan the next 2 weeks. You would set the planning window to start on 1st July 2026 and end on 15th July 2026, and optionally attach the shifts already worked in late June so that work-limit rules can take them into account. See Historic shifts for details.

We recommend setting the planning window explicitly, especially when the input dataset contains shifts that fall before the upcoming period.

{
  "employees": [
    ...
  ],
  "shifts": [
    ...
  ],
  "planningWindow": {
    "start": "2026-07-01T00:00:00Z",
    "end": "2026-07-15T00:00:00Z"
  }
}

The start time is treated as inclusive, while the end is treated as exclusive.

When using Multi-day shift sequence patterns starting or ending with one or more OFF elements, the planning window must be set explicitly.

How the planning window is derived if not set

If planningWindow is omitted, the interval is derived from the shifts:

start: the start of the earliest of all shifts with time part adjusted to 00:00 (midnight).

Example: the earliest shift start = 2026-07-01T08:00:00Z → window start = 2026-07-01T00:00:00Z.
end: the next day after the start of the latest of all shifts with time part adjusted to 00:00 (midnight).

Example: the latest shift start = 2026-07-14T08:00:00Z → window end = 2026-07-15T00:00:00Z.

Historic shifts

Some constraints look further back than the planning window itself. For example, a Shifts worked in a rolling window rule of maximum 8 night shifts per 4 weeks needs to see what shifts employees have already worked in the weeks leading up to the planning window, so the upcoming assignments respect the limit.

Shifts that end before the planning window start are treated as historic. They stay in the input dataset to provide context to the constraints, but they are excluded from constraint matches and from input/output metrics: a match whose shifts all end before the planning window start is skipped entirely.

Example

Suppose you plan the next two weeks starting on 1st July 2026 and a contract has a maximum 8 night shifts per 4 weeks rule. The last shift in the planning window starts on 14th July, and its four-week lookback reaches back to 17th June. You therefore attach the last two weeks of history (17th-30th June) together with the two weeks of future shifts:

{
  "shifts": [
    {
      "id": "2026-06-25-night",
      "start": "2026-06-25T22:00:00Z",
      "end": "2026-06-26T06:00:00Z",
      "employee": "Ann",
      "pinned": true
    },
    {
      "id": "2026-07-05-night",
      "start": "2026-07-05T22:00:00Z",
      "end": "2026-07-06T06:00:00Z"
    }
  ],
  "planningWindow": {
    "start": "2026-07-01T00:00:00Z",
    "end": "2026-07-15T00:00:00Z"
  }
}

The 25th June shift is historic. It contributes to the rolling-window count but is not itself evaluated for violations, and it does not appear in the input or output metrics. The 5th July shift is inside the planning window and is assigned by the solver.

Pin historic shifts

Historic shifts represent decisions that have already been made and cannot be changed. They need to be pinned to their assigned employee otherwise they will trigger validation warnings. If a historic shift is not pinned, the model raises a validation warning.