Skip to main content

Period Distribution Constraint

Define rules to improve the distribution of inconvenient periods among employees.

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.


Period Distribution 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.

isStrict
boolean

If true, the constraint must be strictly followed and the solver will never consider solutions that would violate the constraint.

object (constraintFilters)

Filters to determine the scope of the constraint. Used to decide which employees and which shifts the constraint should be applied to. Filters use logical OR filtering - an employee or shift is included as long as it is targeted by any of the filters.

object (constraintFairness)

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

minWorkedPeriods
integer >= 0

The minimum amount of periods in which the employee should work. This is treated as a target instead of a strict limit.

maxWorkedPeriods
integer >= 0

The maximum amount of periods in which the employee can work.

maxConsecutiveWorkedPeriods
integer >= 1

The maximum amount of consecutive periods in which the employee can work.

minSurroundingFreePeriods
integer >= 0

The minimum amount of non-worked periods surrounding a worked period.

object (overlapRules)

Specify when a shift should count as working a period.

object (periods) = 1 properties

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.).

{
  • "id": "string",
  • "weight": {
    },
  • "isStrict": true,
  • "filters": {
    },
  • "fairness": {
    },
  • "minWorkedPeriods": 0,
  • "maxWorkedPeriods": 0,
  • "maxConsecutiveWorkedPeriods": 1,
  • "minSurroundingFreePeriods": 0,
  • "overlapRules": {
    },
  • "periods": {
    }
}

Maximum worked periods

An easy use case is to limit how many worked periods an employee can have.

Payload example

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",
"weight": 50,
"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.

Payload example

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

Alternitavely, the constraint can be used to limit how many undesirable periods an employee can work in succession.

Payload example

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": [
// Christmas
{
"startDay": {
"date": "2024-12-25"
},
"endDay": {
"date": "2024-12-26"
}
},
// New Year
{
"startDay": {
"date": "2024-12-31"
},
"endDay": {
"date": "2024-12-31"
}
},
// ... more holiday periods
]
}
}

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 the minSurroundingFreePeriods property in combination with the maxConsecutiveWorkedPeriods property.

Payload example

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"]
}
}