Constraint schema
object
Used to define targets and limits for the distribution of periods (like weekends, holidays, nights).
Show properties
Show properties
string
required
Unique identifier for the constraint.
array of string
Labels for the constraint. Labels can be used to group constraints together. For example, if multiple constraints are related to the same shift type, they can all be labeled with the same label.
string (enum: NONE | VERY_LOW | LOW | MEDIUM | HIGH | ...)
The importance of the constraint. The higher the importance, the more the solver will take the constraint into account. Under strict importance, the constraint may never be violated.
object
Filters to determine the scope of the constraint. Used to indicate what the constraint should be applied to (which employees, which shifts, etc). Leaving this empty means that the constraint always applies.
Show filters – properties
Show filters – properties
object
Used to filter which employees the constraint should be applied to. If not specified, the constraint applies to all employees.
Show employees – properties
Show employees – properties
array of string
List of employee ids that the constraint should be applied to.
array of string
List of employee labels that the constraint should be applied to.
object
Show matchTypes – properties
Show matchTypes – properties
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.
object
Used to filter which shifts the constraint should be applied to. If not specified, the constraint applies to all shifts.
Show shifts – properties
Show shifts – properties
array of string
List of shift ids that the constraint should be applied to.
array of string
List of shift labels that the constraint should be applied to.
object
Show matchTypes – properties
Show matchTypes – properties
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.
string (enum: NONE | ANY | ALL)
Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.
integer
The minimum amount of periods in which the employee should work. This is treated as a target instead of a strict limit.
integer
The maximum amount of periods in which the employee can work.
integer
The maximum amount of consecutive periods in which the employee can work.
integer
The minimum amount of non-worked periods both before and after a worked period.
object
Specifies overlap thresholds that a shift must meet with the constraint’s periods in order for it to be counted as relevant for the constraint.
Show overlapRules – properties
Show overlapRules – properties
object
List of periods in the schedule. Periods can either be defined explicitly using custom definitions, or through a recurrent definition. A recurrent definition can be used to easily generate a list of similar periods (such as weeks, months, etc.).
Show periods – properties
Show periods – properties
object
List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period.
Show days – properties
Show days – 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.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
array of object
List of custom period definitions. Each custom period definition defines one period in the schedule.
Show customDefinitions – item structure
Show customDefinitions – item structure
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show startDay – properties
Show startDay – properties
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show endDay – properties
Show endDay – properties
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
boolean
If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
object
A recurrent definition to easily create a set of similar periods.
Show recurrentDefinition – properties
Show recurrentDefinition – properties
integer
required
The number of days in each period.
integer
The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods.
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show startDay – properties
Show startDay – properties
object
Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads).
Show endDay – properties
Show endDay – properties
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
string (time)
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
boolean
If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
array of string
Provide labels to re-use periods that were defined in the configuration.
Explanation
Within the context of this constraint, a period is considered ‘worked’ for an employee if they work any shift during that period, and ‘free’ if they do not. The constraint allows you to set rules for how many periods an employee can work, how many they can work in succession, and how many free periods they must have surrounding a working period. Often seen use cases are the distribution of weekends, holidays, or other inconvenient periods among employees.Maximum worked periods
An easy use case is to limit how many worked periods an employee can have.The constraint specified below makes it undesirable for employees to work more than 2 weekends. Notice that working a shift is only considered
as working a period if it overlaps for at least 6 hours with the period, as configured in the
overlapRules.To work with labels on periods, make sure you have set a definition for the period label in the configuration part of the payload.{
"id": "pd-max-weekends",
"importance": "MEDIUM",
"maxWorkedPeriods": 2,
"overlapRules": {
"minOverlapHours": 6
},
"periods": {
"labels": ["WEEKENDS"]
}
}
Minimum worked periods
Alternatively, the constraint can be used to encourage a minimum amount of worked periods for an employee.The constraint specified below sets a target for the minimum number of weekends during which the employee works any shift.
minWorkedPeriods is never treated as a strict lower bound, but rather as a target that the solver will try to reach.{
"id": "pd-min-weekends",
"minWorkedPeriods": 3,
"periods": {
"labels": ["WEEKENDS"]
}
}
Maximum consecutive worked periods
Alternatively, the constraint can be used to limit how many undesirable periods an employee can work in succession.The constraint specified below makes it strictly forbidden for an employee to work 3 holidays in a row. Notice that with the way periods are defined,
working both days of Christmas still only counts as working one period. If the days of Christmas should count as working separate holidays,
you would need to define them as separate periods.
{
"id": "pd-max-consecutive-holidays",
"isStrict": true,
"maxConsecutiveWorkedPeriods": 2,
"periods": {
"customDefinitions": [
{
"startDay": {
"date": "2024-12-25"
},
"endDay": {
"date": "2024-12-26"
}
},
{
"startDay": {
"date": "2024-12-31"
},
"endDay": {
"date": "2024-12-31"
}
}
]
}
}
Minimum surrounding free periods
The constraint can also be used to enforce a minimum number of free periods surrounding a worked period. Note that it is currently not supported to use theminSurroundingFreePeriods property in combination with the maxConsecutiveWorkedPeriods property.
The constraint specified below makes it strictly required for an employee to have at least 1 free weekend surrounding each worked weekend.
{
"id": "pd-min-surrounding-free-weekends",
"isStrict": true,
"minSurroundingFreePeriods": 1,
"periods": {
"labels": ["WEEKENDS"]
}
}