Days worked in a rolling window

There are different techniques for managing employees' working hours.

For different scenarios see Work limits.

This guide shows you how to manage employees' hours with days worked in a rolling window. Rolling windows can be defined as hourly, daily, or weekly.

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 days worked in a rolling window rules

Rolling window rules are defined in contracts:

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "rollingWindowRules": [
        {
          "id": "max5DaysRollingWindow",
          "rollingWindow": {
            "type": "DAILY",
            "size": 7
          },
          "daysWorkedLimit":
          {
            "daysWorkedMax": 5
          },
          "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 daysWorkedLimit object must include daysWorkedMax with the maximum number of days to work in the rolling window.

RollingWindowRules can include or exclude shifts based on shift tags.

{
  "rollingWindowRules": [
    {
      "id": "max5DaysRollingWindow",
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL",
      "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 days worked in a rolling window

When the satisfiability of the rule is REQUIRED, the Days worked in rolling window not in preferred range for employeee hard constraint is invoked, which makes sure the number of days worked is not above the limit specified in daysWorkedMax.

Shifts will be left unassigned if assigning them would break the Days worked in rolling window not in preferred range for employee constraint.

In the following example, there are 7 shifts, 1 employee, and a rule with a required satisfiability that states the employee cannot work more than 5 days in a 7-day rolling window.

5 shifts are assigned and 2 shifts are left unassigned to avoid breaking the Days worked in rolling window not in preferred range for employee hard constraint.

required days worked 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 days worked in a rolling window example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "rollingWindowRules": [
          {
            "id": "max5DaysRollingWindow",
            "rollingWindow": {
              "type": "DAILY",
              "size": 7
            },
            "daysWorkedLimit":
            {
              "daysWorkedMax": 5
            },
            "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 days worked in a rolling window example",
    "submitDateTime": "2025-05-22T06:50:37.011064392Z",
    "startDateTime": "2025-05-22T06:50:48.634288335Z",
    "activeDateTime": "2025-05-22T06:50:48.821105774Z",
    "completeDateTime": "2025-05-22T06:51:19.750252527Z",
    "shutdownDateTime": "2025-05-22T06:51:20.01893995Z",
    "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": "Ann"
      },
      {
        "id": "Sat"
      },
      {
        "id": "Sun"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 7,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 2,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to shifts that do not exceed 5 days.

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 days worked in a rolling window

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

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "rollingWindowRules": [
        {
          "id": "max5DaysRollingWindow",
          "rollingWindow": {
            "type": "DAILY",
            "size": 7
          },
          "daysWorkedLimit":
          {
            "daysWorkedMax": 5
          },
          "satisfiability": "PREFERRED"
        }
      ]
    }
  ]
}

If there is no alternative, shifts will still be assigned to employees even if assigning the shifts breaks the days worked per period not in preferred range for employee soft constraint and the employee is assigned to work more days than defined in daysWorkedMax. 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 the employee cannot work more than 5 days in a 7-day rolling window.

All 7 shifts are assigned, the employee works more than 5 days and a soft penalty is applied to the run score.

preferred days worked in a rolling window

Input
Output