Shifts

Shifts specify the different kinds of working hour assignments that employees may receive. In any solution produced by the solver, employees will only receive working hours by being assigned to any of the possible Shifts. This page will give some pointers on how to define Shifts in your payload.

Shift schema

object

Show properties

string

required

Unique identifier for the shift.

array of string

List of labels assigned to this shift. Labels can be used in constraints to group shifts.

boolean

If set to true, the shift will not be assigned by the solver. Read only shifts will not be used in new assignments by the solver, their use is limited to preassigned shifts. Read only shifts can still be used to cover demand. Default: false.

boolean

Only relevant for preassigned shifts. If set to false, assignments of this shift will not contribute towards demand coverage. Shifts that cannot cover demand will not be used in new assignments by the solver, their use is limited to preassigned shifts. Default: true.

object

List of days in the schedule. Days can be defined as an array of dates (in CALENDAR payloads), as an array of day indices (in RECURRING payloads), or as an array of weekdays (allowed in all payloads).

Show availableDays – properties

array of date (date)

List of dates in the schedule. Only allowed in CALENDAR payloads.

array of dayIndex

List of day indices in the schedule. Only allowed in RECURRING payloads.

array of dayOfWeek

List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.

array of object

required

List of intervals that this shift consists of. The maximum duration of a shift is 72 hours.

Show intervals – item structure

string (time)

required

TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.

string (time)

required

TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.

integer

required

Indicates which day this interval belongs to, relative to the day that the shift belongs to. -1 indicates the interval starts on the previous day, 0 on the same day, and 1 on the next day.

object

Show workload – properties

number

Factor by which the hours of this interval will be multiplied to calculate the total FTE hours of an employee. Default: 1.

string

Category of work carried out during the interval. Only relevant if using TIME_DEMAND.

integer

Minutes of break in this interval. The solver does not plan the break at any specific time, but the break minutes are subtracted from the total FTE for the shift. Default: 0.

string

Task id of the task that must be worked on during this interval. The task needs to be defined in the configuration part of the payload.

object

List of shifts that are connected to this shift on the previous day. If defined, this shift will always be preceded by one of the connected shifts the previous day.

Show connectedShiftsPreviousDay – properties

array of shiftId

List of ids of shifts that are connected to this shift.

array of string

List of ids of shift templates that are connected to this shift.

boolean

Whether the connected shift can be a day off. Default: false.

object

List of shifts that are connected to this shift on the next day. If defined, this shift will always be followed by one of the connected shifts the next day.

Show connectedShiftsNextDay – properties

array of shiftId

List of ids of shifts that are connected to this shift.

array of string

List of ids of shift templates that are connected to this shift.

boolean

Whether the connected shift can be a day off. Default: false.

array of object

List of requirements on the attributes that an employee needs to be eligible to work this Shift. If an employee does not meet all of the requirements, the employee can not work this Shift.

Show attributeRequirements – item structure

string

The category of the attribute.

array of string

The targeted values for this requirement.

string (enum: NONE | ANY | ALL)

Default: “ALL”.

By default, shifts may be used (assigned to employees) an unlimited amount of times in schedules produced by the solver. If you would like to specify exactly how many times the assignments of certain shifts is needed, see ShiftDemand.

Intervals

At its core, a shift is built up out of one or more intervals. Whenever a shift is assigned to an employee, that employee will work all of the intervals in the shift. Intervals must have a start- and end time that both fall within the same day, and the intervals of one shift must all fall within a maximum span of 72 hours (across no more than 3 distinct days). To specify that an interval is to take place a day before or a day after the day on which the shift is planned, the dayIndicator property can be used. The different intervals of a shift may not overlap one another.

Consider a 6-hour Shift that starts on 20:00 and lasts until 02:00. This can be covered using Shift Intervals in one of two ways:

The Shift contains an interval from 20:00-00:00 with dayIndicator -1, and an interval from 00:00-02:00 with dayIndicator 0. When planning any instances of this Shift, it will be considered to belong to the second day.
The Shift contains an interval from 20:00-00:00 with dayIndicator 0, and an interval from 00:00-02:00 with dayIndicator 1. When planning any instances of this Shift, it will be considered to belong to the first day.

Breaks

It is possible to specify the amount of breakMinutes any interval contains. The break is not considered to happen at any specific time, this is only used to correctly determine the employee’s FTE. A shift interval of 8 hours with a 1-hour break is considered to count for 7 worked hours.

Day assignments

In the schedules created by the solver, Shifts are assigned to employees on days within the planning period. Shift assignments are always considered to belong to one specific day, even if the Shift contains working hours on the previous or next day. It is possible to specify specific days in the planning period on which a Shift may be assigned to employees. By default, the entire planning period is allowed. Alternatively, it is possible to specify which weekdays are available for a Shift.

Consider the following example for a two-week planning period. shift-1 shifts may only be assigned on Mondays, Tuesdays, and Wednesdays, while shift-2 shifts may only be planned on the first three or the last three days of the period.

[
  {
    "id": "shift-1",
    "intervals": [...],
    "availableDays": {
      "daysOfWeek": ["MON", "TUE", "WED"]
    }
  },
  {
    "id": "shift-2",
    "intervals": [...],
    "availableDays": {
      "dayIndices": [0, 1, 2, 11, 12, 13]
    }
  }
]

Preassigned shifts

If there are certain shift assignments for employees that are already fixed, it is recommended to include these in the request. This way, the solver can take into account which hours an employee is already working and ensure the produced schedule is feasible given the already existing assignments. However, it can occur that this means you have to send in a Shift definition that you do not want to be used by the solver to make new assignments - only to explain what kind of shift the employee is working in the already fixed assignment. For this purpose, it is possible to mark a Shift as isReadOnly. The solver will then not use it to make new assignments.

An employee cannot be preassigned to multiple locked shifts on the same day, or to overlapping locked shifts.

Getting started

Concepts

Entities

Other

Shift schema

Intervals

Breaks

Day assignments

Preassigned shifts