Skip to main content

Shift Utilization Constraint

Soft constraint *

Deprecated constraint

The Shift Utilization Constraint is being deprecated in favour of the EmployeeUtilizationConstraint. You should no longer build a new integration with this constraint.

* with possibility for hard constraint

Set a minimum and/or maximum number of times a shift should be used. This can be applied to any number of employees, and one can specify shiftIds, shiftTypeIds or workTypeIds to which the constraint should apply. In addition, one can specify a minimum and/or maximum duration of the shift for it to count towards the constraint.

If the weight of this constraint is set to a value below 100, the solver will try to avoid planning less shifts than the min occurrence and more shifts than the max occurrence for an employee, but it is possible. (soft constraint)
If the weight of this constraint is set to 100, it is impossible for the solver to assign more shifts than the maxOccurrence. (hard constraint)

Fairness​

It is possible to use fairness on this constraint to encourage the solver to distribute violations of the min and max occurrence fairly across employees.
fairness works when the weight of the constraint is lower than 100: the solver aims for all employees to have the same number of shifts missing from the min occurrence or exceeding the max occurrence.

Example: in the case of a minOccurrence = 0 and maxOccurrence = 5, the solver will prefer assigning 6 shifts to both employees over assigning 5 shifts to one employee and 7 shifts to another.

Note that fairness is not applied when employees are assigned a number of shifts within the min and max occurrence. So in the previous example, 3 shift assignments for one employee and 5 shifts for the other is considered fine.

fairness tip

If you're sending in a ShiftUtilization constraint and would like the shift assignments to be fairly distributed regardless of the min and max occurrence, it is recommended you do so by sending in a separate ShiftUtilization constraint for this.
(So this is for e.g. the example above with minOccurrence = 0 and maxOccurrence = 5: if you prefer two employees with 4 shift assignments over one with 3 and one with 5.)

This constraint should be specified with a maxOccurrence of 0; this way the solver will work towards all employees having the same number of shifts assigned.
It is recommended to set the weight of this constraint to 0. If you were to provide a higher weight, all this will do is enforce the soft constraint of preferring 0 shift assignments for the employees.

So, it is possible to send in a ShiftUtilization constraint with weight 0 and fairness defined on it. This will have the effect of only the fairness being enforced, the solver won't act on the min/maxOccurrence.

Payload​

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 that employees 1, 2 and 3 should work at least one shift of work type ID 1. This does not include shifts of work type ID 1 that lasts shorter than four hours.

{
  "shiftUtilizationConstraints": [
    {
      "id": "suc-123",
      "weight": 50,
      "occurrenceMin": 1,
      "durationMin": {
        "hours": 4
      },
      "workTypeIds": ["1"],
      "employeeIds": ["1", "2", "3"]
    }
  ]
}
Shift Utilization 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.

occurrenceMin
integer >= 0
Default: 0

The minimum number of times the shifts can be used within the scheduling period.

occurrenceMax
integer >= 0

The maximum number of times the shifts can be used within the scheduling period. If the weight is set to 100, occurrenceMax will work as a hard constraint.

object (duration) non-empty

Filter shifts to only apply constraint to shifts with a longer duration than durationMin.

object (duration) non-empty

Filter shifts to only apply constraint to shifts with a shorter duration than durationMax.

shiftIds
Array of strings (constraintShiftIds) unique

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

shiftTypeIds
Array of strings (constraintShiftTypeIds) unique

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

workTypeIds
Array of strings (constraintWorkTypeIds) unique

List of workType IDs for which the constraint applies. The workTypeIds should be present in workType section. If work type ids are not specified, the constraint will be applied to all work types.

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.

object (periods) = 1 properties

List of periods in which the constraint should apply. Note - on ShiftUtilization, a period's startTime and endTime are not taken into account. Periods on this constraint are only used to define the days on which the constraint applies.

object (scheduleDaysWithoutWeekDays) = 1 properties
Deprecated

Defines the days in the planning horizon. Either dayIndexes or dates must be specified. If the schedule type is RECURRING, then dayIndexes must be specified, and if the schedule type is CALENDAR, then dates must be specified.

{
  • "example_1": {
    }
}