Shifts worked per period

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 shifts worked per period. A period can be defined as a week, month, or the entire schedule.

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 shifts worked per period rules

Period rules can define how many shifts employees work in a given period. For instance, a maximum of 4 shifts per week.

"Days worked rules" and "shifts worked rules" are similar, however, many industries schedule employees multiple shifts per day or spilt shifts.

Days worked rules are appropriate when employees are never assigned more than a single shift in a day, however, shifts worked rules are suitable when multiple shifts might be assigned on the same day.

Each employee must specify which contracts apply to them:

{
  "employees": [
    {
      "id": "Ann",
      "contracts": [
        "fullTimeContract"
      ]
    }
  ]
}

Period rules are configured in contracts:

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max4ShiftsPerWeek",
          "satisfiability": "REQUIRED",
          "period": "WEEK",
          "shiftsWorkedMax": 4
        }
      ]
    }
  ]
}

PeriodRules must include an ID.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

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

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way:

{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

shiftsWorkedMax sets the maximum number of shifts the employee can work in the specified period.

periodRules can include or exclude shifts based on shift tags.

{
  "periodRules": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max4ShiftsPerWeek",
          "satisfiability": "REQUIRED",
          "period": "WEEK",
          "shiftsWorkedMax": 4,
          "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.

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

2. Required shifts worked per period

When the satisfiability of the rule is REQUIRED, the Shifts worked per period not in required range for employee hard constraint is invoked, which makes sure the number of shifts worked does not exceed the limit specified in shiftsWorkedMax.

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

In the following example, there are 10 shifts and 2 employees. Ann and Beth both work a maximum of 4 shifts each. Ann is assigned 4 shifts, Beth is assigned 4 shifts, and 2 shifts are left unassigned to avoid breaking the Shifts worked per period not in required range for employee hard constrain.

required shifts worked per period

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 shifts worked per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Min2ShiftsMax4ShiftsPerWeek",
            "period": "WEEK",
            "satisfiability": "REQUIRED",
            "shiftsWorkedMax": 4
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      },
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T11:00:00Z"
      },
      {
        "id": "Mon PM",
        "start": "2027-02-01T15:00:00Z",
        "end": "2027-02-01T20:00:00Z"
      },
      {
        "id": "Tue AM",
        "start": "2027-02-02T06:00:00Z",
        "end": "2027-02-02T11:00:00Z"
      },
      {
        "id": "Tue PM",
        "start": "2027-02-02T15:00:00Z",
        "end": "2027-02-02T20:00:00Z"
      },
      {
        "id": "Wed AM",
        "start": "2027-02-03T06:00:00Z",
        "end": "2027-02-03T11:00:00Z"
      },
      {
        "id": "Wed PM",
        "start": "2027-02-03T15:00:00Z",
        "end": "2027-02-03T20:00:00Z"
      },
      {
        "id": "Thu AM",
        "start": "2027-02-04T06:00:00Z",
        "end": "2027-02-04T11:00:00Z"
      },
      {
        "id": "Thu PM",
        "start": "2027-02-04T15:00:00Z",
        "end": "2027-02-04T20:00:00Z"
      },
      {
        "id": "Fri AM",
        "start": "2027-02-05T06:00:00Z",
        "end": "2027-02-05T11:00:00Z"
      },
      {
        "id": "Fri PM",
        "start": "2027-02-05T15:00:00Z",
        "end": "2027-02-05T20: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": "Preferred shifts worked per period example",
    "submitDateTime": "2025-03-31T11:31:34.839626724Z",
    "startDateTime": "2025-03-31T11:31:45.574253759Z",
    "activeDateTime": "2025-03-31T11:31:45.699778641Z",
    "completeDateTime": "2025-03-31T11:36:46.699637795Z",
    "shutdownDateTime": "2025-03-31T11:36:46.907201752Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1920soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Mon PM",
        "employee": "Ann"
      },
      {
        "id": "Tue AM",
        "employee": "Beth"
      },
      {
        "id": "Tue PM",
        "employee": "Beth"
      },
      {
        "id": "Wed AM",
        "employee": "Ann"
      },
      {
        "id": "Wed PM",
        "employee": "Ann"
      },
      {
        "id": "Thu AM",
        "employee": "Beth"
      },
      {
        "id": "Thu PM",
        "employee": "Beth"
      },
      {
        "id": "Fri AM",
        "employee": "Ann"
      },
      {
        "id": "Fri PM",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 2,
    "shifts": 10,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 10,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 10,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann and Beth both assigned 4 shifts.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 10,
  "unassignedShifts": 0,
  "activatedEmployees": 2,
  "assignedMandatoryShifts": 10
}

3. Preferred shifts worked per period

When the satisfiability of the rule is PREFERRED, the Shifts worked per period not in preferred range for employee soft constraint is invoked.

With a satisfiability of PREFERRED a shiftsWorkedMin value can also be provided to set the preferred minimum number of shifts worked.

{
  "contracts": [
    {
      "id": "partTimeContract",
      "periodRules": [
        {
          "id": "Min2ShiftsMax4ShiftsPerWeek",
          "satisfiability": "PREFERRED",
          "period": "WEEK",
          "shiftsWorkedMin": 2,
          "shiftsWorkedMax": 4
        }
      ]
    }
  ]
}

This constraint adds a soft penalty to the run score when the number of assigned shifts is below the limit defined by shiftsWorkedMin or above the limit defined by shiftsWorkedMax, incentivizing Timefold to find an alternative solution.

In the following example, Ann and Beth both work a preferred minimum of 2 shifts and a preferred maximum of 4 shifts per week. There are 10 shifts over 5 days. Ann is assigned 6 shifts and Beth is assigned 4 shifts.

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 shifts worked per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Min2ShiftsMax4ShiftsPerWeek",
            "period": "WEEK",
            "satisfiability": "PREFERRED",
            "shiftsWorkedMin": 2,
            "shiftsWorkedMax": 4
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      },
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T11:00:00Z"
      },
      {
        "id": "Mon PM",
        "start": "2027-02-01T15:00:00Z",
        "end": "2027-02-01T20:00:00Z"
      },
      {
        "id": "Tue AM",
        "start": "2027-02-02T06:00:00Z",
        "end": "2027-02-02T11:00:00Z"
      },
      {
        "id": "Tue PM",
        "start": "2027-02-02T15:00:00Z",
        "end": "2027-02-02T20:00:00Z"
      },
      {
        "id": "Wed AM",
        "start": "2027-02-03T06:00:00Z",
        "end": "2027-02-03T11:00:00Z"
      },
      {
        "id": "Wed PM",
        "start": "2027-02-03T15:00:00Z",
        "end": "2027-02-03T20:00:00Z"
      },
      {
        "id": "Thu AM",
        "start": "2027-02-04T06:00:00Z",
        "end": "2027-02-04T11:00:00Z"
      },
      {
        "id": "Thu PM",
        "start": "2027-02-04T15:00:00Z",
        "end": "2027-02-04T20:00:00Z"
      },
      {
        "id": "Fri AM",
        "start": "2027-02-05T06:00:00Z",
        "end": "2027-02-05T11:00:00Z"
      },
      {
        "id": "Fri PM",
        "start": "2027-02-05T15:00:00Z",
        "end": "2027-02-05T20: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": "Preferred shifts worked per period example",
    "submitDateTime": "2025-03-31T11:31:34.839626724Z",
    "startDateTime": "2025-03-31T11:31:45.574253759Z",
    "activeDateTime": "2025-03-31T11:31:45.699778641Z",
    "completeDateTime": "2025-03-31T11:36:46.699637795Z",
    "shutdownDateTime": "2025-03-31T11:36:46.907201752Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1920soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Mon PM",
        "employee": "Ann"
      },
      {
        "id": "Tue AM",
        "employee": "Beth"
      },
      {
        "id": "Tue PM",
        "employee": "Beth"
      },
      {
        "id": "Wed AM",
        "employee": "Ann"
      },
      {
        "id": "Wed PM",
        "employee": "Ann"
      },
      {
        "id": "Thu AM",
        "employee": "Beth"
      },
      {
        "id": "Thu PM",
        "employee": "Beth"
      },
      {
        "id": "Fri AM",
        "employee": "Ann"
      },
      {
        "id": "Fri PM",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 2,
    "shifts": 10,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 10,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 10,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann and Beth assigned to shifts within the range of 2 to 4 shifts per week.

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

KPIs provides the KPIs for the output including:

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

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
See other options for managing employees' work hours: Work limits.

Shifts worked per period

Prerequisites

1. Define shifts worked per period rules

2. Required shifts worked per period

3. Preferred shifts worked per period

Next