Consecutive days worked

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 consecutive days worked per period, for instance, to limit the maximum number of consecutive days employees can be assigned shifts to work.

Prerequisites

Learn how to configure an API Key to run the examples in this guide:

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. 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 worked rules

Consecutive day worked rules are defined in contracts.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "consecutiveDaysWorkedRules": [
        {
          "id": "Max3Consecutive12HourShifts",
          "maximum": 3,
          "satisfiability": "REQUIRED"
        }
      ]
    }
  ]
}

A consecutiveDaysWorkedRules must include an ID.

maximum defines the maximum number of shifts on consecutive days an employee with this contract can work.

consecutiveDaysWorkedRules can include or exclude shifts based on shift tags.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "Max3Consecutive12HourShifts",
      "maximum": 3,
      "satisfiability": "REQUIRED",
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL"
    }
  ]
}
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.

shiftTypesTagCategories can be used to limit consecutive days worked on shifts with specific tags, for instance, shifts tagged with Day or Night.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "Max3Consecutive12HourShifts",
      "maximum": 3,
      "satisfiability": "REQUIRED",
      "shiftTypesTagCategories": [
        "Day", "Night"
      ]
    }
  ]
}

With the maximum set to 3 and shiftTypesTagCategories including the tags Day and Night, employees will not be assigned more than 3 consecutive day shifts or 3 consecutive night shifts. However, they could be assigned 3 consecutive day shifts followed by 3 consecutive night shifts, or vice versa.

Shifts can have the tag Day or Night but not both.

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

2. Required consecutive days worked

When the satisfiability of the rule is REQUIRED, the Consecutive days worked not in required range for employee hard constraint is invoked, which makes sure the number of shifts on consecutive days does not exceed the limit specified in maximum.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

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

In the following example, there are 4 shifts and 1 employee. Beth has a contract that allows her to work shifts on a maximum of 3 consecutive days.

Beth is assigned 3 consecutive shifts and 1 shift is left unassigned.

required consecutive days worked

  • 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 worked example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "consecutiveDaysWorkedRules": [
          {
            "id": "Max3Consecutive12HourShifts",
            "maximum": 3,
            "satisfiability": "REQUIRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T20:00:00Z"
      },
      {
        "id": "Tue",
        "start": "2027-02-02T08:00:00Z",
        "end": "2027-02-02T20:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T08:00:00Z",
        "end": "2027-02-03T20:00:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T08:00:00Z",
        "end": "2027-02-04T20: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>
{
  "metadata": {
    "id": "ID",
    "name": "Required consecutive days worked example",
    "submitDateTime": "2025-03-18T06:39:19.37242389Z",
    "startDateTime": "2025-03-18T06:39:30.34936678Z",
    "activeDateTime": "2025-03-18T06:39:30.58964911Z",
    "completeDateTime": "2025-03-18T06:44:31.318789334Z",
    "shutdownDateTime": "2025-03-18T06:44:31.541517086Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      },
      {
        "id": "Tue",
        "employee": "Beth"
      },
      {
        "id": "Wed",
        "employee": "Beth"
      },
      {
        "id": "Thu",
        "employee": null
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 4,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 3,
    "unassignedShifts": 1,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 3,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the employee schedule with Beth assigned 3 consecutive shifts.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 3,
  "unassignedShifts": 1
}

3. Preferred consecutive days worked

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

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s consecutiveDaysWorkedNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "consecutiveDaysWorkedNotInPreferredRangeForEmployeeWeight": 10 }

With a satisfiability of PREFERRED a minimum value can also be provided to set the minimum number of consecutive days an employee can be assigned shifts.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "consecutiveDaysWorkedRules": [
        {
          "id": "Min2Max3ConsecutiveShifts",
          "maximum": 3,
          "minimum": 2,
          "satisfiability": "PREFERRED"
        }
      ]
    }
  ]
}

If there is no alternative, shifts will still be assigned to employees even if assigning the shifts breaks the Consecutive days worked not in preferred range for employee soft constraint. This constraint adds a soft penalty to the dataset score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

This rule is more likely to be satisfied for employees with a higher employee priority.

In the following example, there are 4 shifts and 1 employee. Beth has a contract that allows her to work shifts on a preferred maximum of 3 consecutive days.

Beth is assigned all 4 consecutive shifts and a soft penalty is applied to the dataset score.

preferred consecutive days worked

  • 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": "Preferred consecutive days worked example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "consecutiveDaysWorkedRules": [
          {
            "id": "Max3Consecutive12HourShifts",
            "maximum": 3,
            "satisfiability": "PREFERRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T20:00:00Z"
      },
      {
        "id": "Tue",
        "start": "2027-02-02T08:00:00Z",
        "end": "2027-02-02T20:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T08:00:00Z",
        "end": "2027-02-03T20:00:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T08:00:00Z",
        "end": "2027-02-04T20: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>
{
  "metadata": {
    "id": "ID7",
    "name": "Preferred consecutive days worked example",
    "submitDateTime": "2025-05-23T08:29:39.286257221Z",
    "startDateTime": "2025-05-23T08:29:56.095375304Z",
    "activeDateTime": "2025-05-23T08:29:56.254538641Z",
    "completeDateTime": "2025-05-23T08:30:26.999013804Z",
    "shutdownDateTime": "2025-05-23T08:30:27.289197001Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-960soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      },
      {
        "id": "Tue",
        "employee": "Beth"
      },
      {
        "id": "Wed",
        "employee": "Beth"
      },
      {
        "id": "Thu",
        "employee": "Beth"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 4,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Beth assigned all 4 shifts.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 4,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 4
}

4. Defining shift sequences

One or multiple shifts of the same type form a sequence. Such sequence can have days off in between the shifts.

Consider the following shifts:

  • Shift 1 morning: 1st Jan 2025

  • Shift 2 morning: 2nd Jan 2025

  • Shift 3 morning: 3rd Jan 2025

  • Shift 4 morning: 5th Jan 2025

  • Shift 5 afternoon: 8th Jan 2025

  • Shift 6 afternoon: 10th Jan 2025

  • Shift 7 afternoon: 11th Jan 2025

  • Shift 8 afternoon: 13th Jan 2025

There are two sequences:

  • Morning shift sequence between 1st Jan 2025 and 5th Jan 2025

  • Afternoon shift sequence between 8th Jan 2025 and 13th Jan 2025

Use shiftTypeTagCategories of consecutiveDaysWorkedRules to define the sequences. A shift must have at most one tag from shiftTypeTagCategories.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"]
    }
  ]
}

For example, the following shift matches the sequence category "morning".

{
  "shifts": [
  {
      "id": "shift-1",
      "start": "2025-01-01T09:00:00Z",
      "end": "2025-00-01T17:00:00Z",
      "tags": [
        "morning", "ICU"
      ]
    }
  ]
}

5. Required minimum time between different sequences

When the satisfiability of the rule is REQUIRED, the Required minimum time between different sequences not met for employee hard constraint is invoked, which makes sure there is enough time between two different sequences, for example morning and afternoon.

There are two ways to define the required time interval between the sequences:

5.1. Absolute duration

minDurationBetweenDifferentSequences: absolute duration (ISO 8601 format), for example 24 hours (PT24H).

In that case, the following sequence is required to start no sooner than in 24 hours. If the prior sequence ends on 1st Jan 2025, 16:00, the next sequence can start no sooner than 2nd Jan 2025, 16:00.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "minDurationBetweenDifferentSequences": "PT24H"
    }
  ]
}

5.2. Flexible delay

minDelayBetweenDifferentSequences: flexible function that allows you to specify a delay until a specific moment, for example next Monday, or in 2 full calendar days.

The function has 3 components:

minStartDateAdjuster The name of the adjuster function for the date part of the following sequence start.

The following functions are supported:

  • SAME_DAY

  • NEXT_DAY

  • NEXT_MONTH

  • NEXT_MONDAY

  • NEXT_TUESDAY

  • NEXT_WEDNESDAY

  • NEXT_THURSDAY

  • NEXT_FRIDAY

  • NEXT_SATURDAY

  • NEXT_SUNDAY

minStartDateAdjusterIncrement: the increment which determines how many times minStartDateAdjuster is applied. The default value is 1.

minStartTime: the time part (ISO 8601 local datetime) of the following sequence start (inclusive).

For example, the following sequence is required to start no sooner than in 1 full calendar day, plus the remaining part of the day, where the previous sequence ends. If the prior sequence ends on 1st Jan 2025, 16:00, the next sequence can start no sooner than 3rd Jan 2025, 00:00.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "minDelayBetweenDifferentSequences": {
        "minStartDateAdjuster": "NEXT_DAY",
        "minStartDateAdjusterIncrement": 2,
        "minStartTime": "00:00:00"
      }
    }
  ]
}

6. Preferred minimum time between different sequences

When the satisfiability of the rule is PREFERRED, the Preferred minimum time between different sequences not met for employee soft constraint is invoked, which makes sure there is enough time between two sequences of different type, for example morning and afternoon.

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s preferredMinimumTimeBetweenDifferentSequencesNotMetForEmployeeWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "preferredMinimumTimeBetweenDifferentSequencesNotMetForEmployeeWeight": 10 }

There are two ways to define the required time interval between the sequences:

6.1. Absolute duration

minDurationBetweenDifferentSequences - absolute duration (ISO 8601 format), for example 24 hours (PT24H).

In that case, the following sequence is required to start no sooner than in 24 hours. If the prior sequence ends on 1st Jan 2025, 16:00, the next sequence can start no sooner than 2nd Jan 2025, 16:00.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "minDurationBetweenDifferentSequences": "PT24H"
    }
  ]
}

6.2. Flexible delay

minDelayBetweenDifferentSequences - flexible function that allows to specify delay until a specific moment, for example next Monday, or in 2 full calendar days.

The function has 3 components:

minStartDateAdjuster The name of the adjuster function for the date part of the following sequence start.

The following functions are supported:

  • SAME_DAY

  • NEXT_DAY

  • NEXT_MONTH,

  • NEXT_MONDAY

  • NEXT_TUESDAY

  • NEXT_WEDNESDAY

  • NEXT_THURSDAY

  • NEXT_FRIDAY

  • NEXT_SATURDAY

  • NEXT_SUNDAY

minStartDateAdjusterIncrement: the increment which determines how many times minStartDateAdjuster is applied. The default value is 1.

minStartTime: the time part (ISO 8601 local datetime) of the following sequence start (inclusive).

For example, the following sequence to start no sooner than in 1 full calendar day, plus the remaining part of the day, where the previous sequence ends. If the prior sequence ends on 1st Jan 2025, 16:00, the next sequence can start no sooner than 3rd Jan 2025, 00:00.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "minDelayBetweenDifferentSequences": {
        "minStartDateAdjuster": "NEXT_DAY",
        "minStartDateAdjusterIncrement": 2,
        "minStartTime": "00:00:00"
      }
    }
  ]
}

7. Required sequence start day

The Required sequence start day not met for employee hard constraint is invoked when the end of the previous sequence prevents the start of the following sequence on one of the configured allowed days.

The constraint is automatically enabled when allowedSequenceStartDays is configured in consecutiveDaysWorkedRules.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "allowedSequenceStartDays": ["MONDAY"]
    }
  ]
}

Consider the following example that uses allowedSequenceStartDays set to MONDAY.

  • Shift 1 morning 2025-01-01 (Wednesday)

  • Shift 2 morning 2025-01-02 (Thursday)

  • Shift 3 morning 2025-01-03 (Friday)

  • Shift 4 morning 2025-01-04 (Saturday)

  • Shift 5 morning 2025-01-06 (Monday)

  • Shift 6 afternoon 2025-01-07 (Tuesday)

In this example, the morning sequence ends on Monday, effectively blocking the afternoon shift from starting because the next sequence cannot start until the following Monday.

A possible remedy of the violation would be to start the afternoon shift the next week:

  • Shift 1 morning 2025-01-01 (Wednesday)

  • Shift 2 morning 2025-01-02 (Thursday)

  • Shift 3 morning 2025-01-03 (Friday)

  • Shift 4 morning 2025-01-04 (Saturday)

  • Shift 5 morning 2025-01-06 (Monday)

  • Shift 6 afternoon 2025-01-13 (Monday)

Note, when the solver plans no shifts on allowedSequenceStartDays and the previous sequence ends before those days, the constraint is not violated. In the following example the previous sequence ends on 2025-01-04 (Saturday) and the next sequence starts on 2025-01-08 (Wednesday).

  • Shift 1 morning 2025-01-01 (Wednesday)

  • Shift 2 morning 2025-01-02 (Thursday)

  • Shift 3 morning 2025-01-03 (Friday)

  • Shift 4 morning 2025-01-04 (Saturday)

  • Shift 5 afternoon 2025-01-08 (Wednesday)

8. Preferred sequence start day

The Preferred sequence start day met for employee soft constraint is invoked when a sequence starts on one of the configured allowed days. The constraint adds a soft reward when this happens.

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s sequenceEndsOnAllowedSequenceStartDayForEmployeeWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "sequenceEndsOnAllowedSequenceStartDayForEmployeeWeight": 10 }

The constraint is automatically enabled when allowedSequenceStartDays is configured in consecutiveDaysWorkedRules.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "allowedSequenceStartDays": ["MONDAY"]
    }
  ]
}

9. Sequence ends on allowed sequence start day

The Sequence ends on allowed sequence start day for employee soft constraint is invoked when a sequence ends on one of the configured allowed days. The idea is to keep these days open to possibly start a new sequence. This constraint adds a soft penalty to the dataset score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s sequenceEndsOnAllowedSequenceStartDayForEmployeeWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "sequenceEndsOnAllowedSequenceStartDayForEmployeeWeight": 10 }

The constraint is automatically enabled when allowedSequenceStartDays is configured in consecutiveDaysWorkedRules.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "allowedSequenceStartDays": ["MONDAY"]
    }
  ]
}

10. Employee works compact sequence

The Employee works compact sequence soft constraint is invoked when two shifts of the same type (for example morning) are planned on consecutive days. The constraint adds a soft reward for such pairs. This keeps the sequences compact and minimizes the gaps in such sequences.

By default, every constraint has a weight of 1, meaning that all constraints are equally important.

Learn about changing the weight of this constraint:

Use the constraint configuration’s employeeWorksCompactSequenceWeight attribute to update the weight of the constraint. 0 disables the constraint. A constraint weight of 10, means the constraint is 10 times more important than a constraint with a weight of 1.

"overrides": { "employeeWorksCompactSequenceWeight": 10 }

The constraint is automatically enabled when rewardCompactSequences is set to true in consecutiveDaysWorkedRules.

{
  "consecutiveDaysWorkedRules": [
    {
      "id": "sequenceExample",
      "shiftTypeTagCategories": ["morning", "afternoon"],
      "rewardCompactSequences": true
    }
  ]
}

Next