Skip to main content

Pattern Constraint

Pattern Constraint can be used to allow you to specify patterns that are desired or undesired for the employee to follow in the produced roster. Both possible use cases are discussed separately below.

Pattern Constraint in the request payload
id
required
string (constraintId)

Unique identifier for the constraint.

importance
required
string (importanceWithStrict)
Enum: "NONE" "VERY_LOW" "LOW" "MEDIUM" "HIGH" "VERY_HIGH" "STRICT"

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.

isDesired
required
boolean

If set to true, the solver will try to make employees follow the specified patterns. Else, it will try to avoid making employees follow any of the specified patterns.

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

Defines the periods in which a pattern should be followed. Periods may not overlap, and are not applicable for undesired patterns. For desired patterns, the solver will try to make each employee follow exactly one of the available patterns in each period. Therefore, the patterns should be defined such that each instance of a pattern is always entirely within a single period.

required
Array of objects
{
  • "id": "string",
  • "importance": "NONE",
  • "isDesired": true,
  • "employeeIds": {
    },
  • "periods": {
    },
  • "patterns": [
    ]
}

Undesired patterns​

For undesired patterns, simply define the patterns that you would not want employees to follow. By default, the solver will try to never assign shifts to employees that would make them follow the undesired patterns. However, if you so desire you can use the startDays field on a specific pattern to specify that the pattern should only be avoided at specific times. For example, some patterns might be fine to follow during the week, but only become undesired during the weekend.

Payload example

The constraint specified below makes it undesirable for employees to work the night shift on both Saturday and Sunday.

{
  "id": "spc-weekend-patterns",
  "importance": "MEDIUM",
  "isDesired": false
  "patterns": [
    {
      "startDays": {
        "daysOfWeek": ["SAT"]
      },
      "patternDays": [
        {
          "shiftIds": ["night-shift"]
        },
        {
          "shiftIds": ["night-shift"]
        }
      ]
    }
  ]
}

When the importance of a pattern constraint is set to Strict, the solver will never make an employee follow the specified pattern. Since this cannot be guaranteed with respect to days off, it is not allowed to use the keyword DAY_OFF within a strict undesired constraint's pattern.

Desired patterns​

The desired version of this constraint works in a similar way. Define the patterns that you would like employees to follow. By default, the solver will try to assign shifts to employees that would make them follow the desired patterns.

However, if there are multiple patterns that you would like the solver to choose from, some further configuration is needed. In this case, it is required to define periods on the constraint. Within each defined period, the solver will then try to make the employees follow exactly one of the specified patterns. If you do then do not define startDays on a pattern, it will default to starting on the first day of each period. If you do choose to define startDays, each instance of the pattern must fall fully within exactly one period. Desired pattern constraints with only one defined pattern do not need to define periods.

Payload example

In the following constraint, the employees may only work shifts if they are in accordance with either of the two patterns. The periods are defined as each weekend (Friday-Sunday). The first pattern is 3 days long and does not define startDays - it therefore starts on each Friday. Meanwhile, the second pattern is 2 days long and only starts on Saturdays. When the solver follows the second pattern for some weekend, it is therefore allowed to plan whatever it wants on the Friday of that weekend.

{
  "patternConstraints": [
    {
      "id": "spc-strict-weekends",
      "importancee": "STRICT",
      "isDesired": true,
      "periods": {
        "recurrentPeriodDefinition": {
          "daysPerPeriod": 3,
          "daysBetweenStarts": 7
        }
      }
      "patterns": [
        {
          "patternDays": [
            {
              "shiftIds": ["shift_1"]
            },
            {
              "shiftIds": ["shift_1"]
            },
            {
              "shiftIds": ["shift_1"]
            }
          ]
        },
        {
          "startDays": {
            "daysOfWeek": ["SAT"]
          }
          "patternDays": [
            {
              "shiftIds": ["shift_2"]
            },
            {
              "shiftIds": ["shift_2"]
            }
          ]
        }
      ]
    }
  ]
}

Empty day behaviour​

In some cases, it can be desirable to allow a pattern to 'skip over' days if it will be impossible for an employee to follow the pattern on that day. In particular, days where an employee is not available for work or days where no demand is defined can be configured to be skipped over. These two types of empty day behaviour can be configured separately through the dayOffBehaviour and dayWithoutDemandBehaviour fields on each pattern itself.

The current list of constraint types that a fairness constraint can apply to is as follows:

Empty day behaviourImpact
INCLUDEDays are always included in the pattern (never skipped over), regardless of whether it is an empty day or not.
EXCLUDEDays are always excluded from the pattern (always skipped over), regardless of whether it is an empty day or not.
MATCHDays are included in the pattern as long as the pattern can be matched with a day off on that day.

In order for a day to qualify as a day without demand, there must be no demands defined on that day. In order for a day to qualify as a day off, the employee must be configured to be unavailable for work on that day. This can be done through one of the following constraints:

  • EmployeeAvailability: The employee is strictly unavailable for work on the entire day.
  • EmployeeUtilization: The employee has a strict maximum of 0 hours or shifts on the day.
  • PeriodDistribution: The employee may work a maximum of 0 periods (which includes the day).