Skip to main content

Consecutive Time Off Constraint

Soft constraint

Deprecated constraint

The Consecutive Time Off Constraint is being deprecated in favour of the PeriodicRestConstraint. You should no longer build a new integration with this constraint.

Defines a desired amount of time off on a weekly basis. One must set a minimum number of days off during a week, and a minimum number of weeks when this constraint should apply. The dayOffType can be set to 24_HOURS, which means that any break of 24 hours between two shifts counts as a day off, even if the shifts are scheduled on consecutive days. Alternatively, DAY_BETWEEN_SHIFTS means that the constraint only applies if there is a full calendar day off between two shifts.

See the payload example below to get started and check out the API reference for full configurability of the constraint.

Payload example

The following defines a wanted time off of three days per week for a total of ten weeks in the schedule period. There must be a minimum of 24 hours between the shifts for it to be counted as a day off. The solver should strive to apply this fairly to all employees regardless of employee FTE working time.

{
  "consecutiveTimeOffConstraints": [
    {
      "id": "ctoc-123",
      "weight": 100,
      "fairness": {
        "fairnessWeight": 100,
        "fteAdjustedFairness": false
      },
      "dayOffType": "24_HOURS",
      "minNumberOfDays": 3,
      "minNumberOfWeeks": 10
    }
  ]
}
Consecutive Time Off Constraint in the request payload
id
required
string (constraintId)

The id of the constraint should be UNIQUE in the context of constraint type.

weight
integer (constraintWeightPositive) [ 0 .. 100 ]

Describes how much the constraint is taken into account when solving the schedule. The higher the value, the more solver will penalize the constraint violation. None of the weight values make it a hard constraint - even when weight is set to 100 it is not guaranteed that the constraint will be satisfied. The weight value is relative to other constraints.

object (constraintFairness)

Describes how much fairness is taken into account for the constraint.

dayOffType
required
string
Enum: "24_HOURS" "DAY_BETWEEN_SHIFTS"

Defines what is considered as a day off. When 24_HOURS is used, the single day of time off counts as 1440 minutes. e.g. if the shift ends on day 1 at 14:00 and the next shift starts on day 2 at 14:00, that counts as a day off. When DAY_BETWEEN_SHIFTS is used, day counts as a day off if there is no shift allocated to the employee on that day. e.g. if the shift ends on day 1 at 14:00 and the next shift starts on day 2 at 14:00, the employee has no day off. To have have day of the first shift should end on day 1 at 14:00 and the next shift should start not earlier than on day 3 at 00:00.

minNumberOfDays
required
integer [ 1 .. 7 ]

Defines minimum number of days that employee(s) should have consecutive time off.

minNumberOfWeeks
required
integer >= 1

Defines minimum number of weeks where employee(s) should have consecutive time off. If number larger than week count in schedule is specified, total week count in schedule is used instead.

object

Period in which consecutive time off can happen. The period should be defined in a a scope of a week. For example, if the period is defined from Monday (1) to Friday (5), then the employee can have a free time block from Monday to Friday in any week. If the period is not defined, then the employee can have a free time block in any time period.

requiredWeekDaysOff
Array of integers[ items [ 1 .. 7 ] ]

List of week days that must be in consecutive days off. The requested week days off can be split in several free time blocks. For example, if the required week days are Monday, Wednesday and Sunday, then the employee can have a free time block that contains Monday and Wednesday and another free time block that contains Sunday. If field is not provided then then free time block doesn't have any week day restrictions and will be placed according to other parameters in this constraint.

employeeIds
Array of strings (constraintEmployeeIds) unique

List of employee ids for which the constraint applies. The employee ids must be present in the employee section. If not specified, the constraint will be applied to all employees.

{
  • "id": "string",
  • "weight": {
    },
  • "fairness": {
    },
  • "dayOffType": "24_HOURS",
  • "minNumberOfDays": 1,
  • "minNumberOfWeeks": 1,
  • "allowedTimeOff": {
    },
  • "requiredWeekDaysOff": {
    },
  • "employeeIds": {
    }
}