Consecutive days off in a rolling window

There are different techniques for managing employee’s time off.

This guide shows you how to include consecutive days off in a rolling window. This can be useful for employees who don’t work conventional Monday to Friday, 9am to 5pm shifts. For instance, if an employee can work any 5 days in a 7-day period with 2 consecutive days off or if employees work on site for 14 days and return home for 14 days off.

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for the Employee Shift Scheduling model:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

In the examples, replace <API_KEY> with the API Key you just copied.

1. Define consecutive days off in a rolling window rules

Rolling window rules are defined in contracts:

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "rollingWindowRules": [
        {
          "id": "2ConsecutiveDaysOffRollingWindow",
          "rollingWindow": {
            "type": "DAILY",
            "size": 7
          },
          "consecutiveDaysOffLimit":
          {
            "consecutiveDaysOffMin": 2
          },
          "satisfiability": "REQUIRED"
        }
      ]
    }
  ]
}

You can define as many rollingWindowRules as required.

rollingWindowRules must include an ID.

rollingWindow specifies the type and size of the window.

Further information about rollingWindows:

There are three types of rolling windows HOURLY, DAILY, and WEEKLY.

The type specifies how the time rolling window progresses, hour-by-hour, day-by-day, or week-by-week.

HOURLY spans a single hour and occurs every hour when shifts are scheduled. The hourly window starts when a shift starts (for example 8:00, or 14:30)
DAILY spans a 24-hour period and covers the entire schedule. The daily window starts at the beginning of a calendar day (midnight).
WEEKLY spans 7 days and occurs every week (including partial weeks) in the schedule. The weekly window starts at the beginning of a calendar week (usually Monday, or Sunday). The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

size sets how many instances of type are included in the rolling window, for instance, the following example specifies a rolling window of 7 days.

{
  "rollingWindow": {
    "type": "DAILY",
    "size": 7
  }
}

The consecutiveDaysOffLimit object must include consecutiveDaysOffMin with the minimum number of consecutive days off.

RollingWindowRules can include or exclude shifts based on shift tags.

{
  "rollingWindowRules": [
    {
      "id": "2ConsecutiveDaysOffRollingWindow",
      "includeShiftTags": ["Part-time"],
      "rollingWindow": {
        "type": "DAILY",
        "size": 7
      }
    }
  ]
}

Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

The satisfiability of the rule can be REQUIRED or PREFERRED. If omitted, REQUIRED is the default.

2. Required consecutive days off in rolling windows

When the satisfiability of the rule is REQUIRED, the Consecutive days off in rolling window not in required range for employee hard constraint is invoked, which makes sure the number of consecutive days off is not below the limit specified in consecutiveDaysOffMin.

Shifts will be left unassigned if assigning them would break the Consecutive days off in rolling window not in required range for employee constraint.

In the following example, there are 7 shifts, 1 employee, and a rule that specifies employees must have 2 consecutive days off in a rolling window of 7 days.

5 shifts are assigned, 2 shifts are not assigned.

required consecutive days off in a rolling window

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Required consecutive days off in a rolling window example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "rollingWindowRules": [
          {
            "id": "2ConsecutiveDaysOffRollingWindow",
            "rollingWindow": {
              "type": "DAILY",
              "size": 7
            },
            "consecutiveDaysOffLimit":
            {
              "consecutiveDaysOffMin": 2
            },
            "satisfiability": "REQUIRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z"
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z"
      },
      {
        "id": "Sat",
        "start": "2027-02-06T09:00:00Z",
        "end": "2027-02-06T17:00:00Z"
      },
      {
        "id": "Sun",
        "start": "2027-02-07T09:00:00Z",
        "end": "2027-02-07T17:00:00Z"
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Required consecutive days off in a rolling window example",
    "submitDateTime": "2025-05-16T06:20:41.707423845Z",
    "startDateTime": "2025-05-16T06:20:53.468389286Z",
    "activeDateTime": "2025-05-16T06:20:53.667203752Z",
    "completeDateTime": "2025-05-16T06:21:24.559695611Z",
    "shutdownDateTime": "2025-05-16T06:21:24.727507073Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-2medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": "Ann"
      },
      {
        "id": "Wed",
        "employee": "Ann"
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": null
      },
      {
        "id": "Sat",
        "employee": null
      },
      {
        "id": "Sun",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 7,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 2,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "assignedShiftGroups": null,
    "unassignedShiftGroups": null,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned shifts and 2 consecutive days off.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 5,
  "unassignedShifts": 2,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 5
}

3. Preferred consecutive days off in rolling windows

When the satisfiability of the rule is PREFERRED, the Consecutive days off in rolling window not in preferred range for employee soft constraint is invoked.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "rollingWindowRules": [
        {
          "id": "2ConsecutiveDaysOffRollingWindow",
          "rollingWindow": {
            "type": "DAILY",
            "size": 7
          },
          "consecutiveDaysOffLimit":
          {
            "consecutiveDaysOffMin": 2
          },
          "satisfiability": "PREFERRED"
        }
      ]
    }
  ]
}

If there is no alternative, shifts will still be assigned to employees even if assigning the shifts breaks the Consecutive days off in rolling window not in preferred range for employee soft constraint and the employee doesn’t get the minimum number of consecutive days off. This constraint adds a soft penalty to the run score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

In the following example, there are 7 shifts, 1 employee, and a rule with a preferred satisfiability that states employees should have 2 consecutive days off in a rolling window of 7 days.

All 7 shifts are assigned, Ann does not get any days off in the rolling window, and a soft penalty is applied to the run score.

preferred consecutive days off in a rolling window

Input
Output