Pattern

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.

Constraint schema

object

Used to define patterns of shifts that employees should follow or avoid.

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.

required

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.

boolean

required

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.

object

Filters to determine the scope of the constraint. Used to decide which employees the constraint should be applied to.

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

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

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

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

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

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

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

string (date)

Date is specified in ISO8601 format YYYY-MM-DD. Can only be used when schedule type is CALENDAR.

integer

Day index relative to the first day of the period (starts at 0). Can only be used when schedule type is RECURRING.

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

string (date)

Date is specified in ISO8601 format YYYY-MM-DD. Can only be used when schedule type is CALENDAR.

integer

Day index relative to the first day of the period (starts at 0). Can only be used when schedule type is RECURRING.

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

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

string (date)

Date is specified in ISO8601 format YYYY-MM-DD. Can only be used when schedule type is CALENDAR.

integer

Day index relative to the first day of the period (starts at 0). Can only be used when schedule type is RECURRING.

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

string (date)

Date is specified in ISO8601 format YYYY-MM-DD. Can only be used when schedule type is CALENDAR.

integer

Day index relative to the first day of the period (starts at 0). Can only be used when schedule type is RECURRING.

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

array of string

Provide labels to re-use periods that were defined in the configuration.

array of object

required

Show patterns – item structure

array of object

required

Defines the pattern that should be followed. Each element in the array represents a day in the pattern. Note that DAY_OFF is not allowed on strict undesired pattern constraints.

Show patternDays – item structure

object

Used to filter which shifts the constraint should be applied to. If not specified, the constraint applies to all shifts.

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

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

string (enum: DAY_OFF | ANY_SHIFT | ANY)

A keyword to represent that a day must be a day off (DAY_OFF), must be a worked day (ANY_SHIFT), or that there are no requirements on this day (ANY).

object

List of days in the schedule. Days can be defined as an array of dates (in CALENDAR payloads), as an array of day indices (in RECURRING payloads), or as an array of weekdays (allowed in all payloads).

Show startDays – 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.

object

Used to apply the constraint only to work carried out in specific roles.

Show roles – properties

array of string

List of relevant role ids.

boolean

If set to true, each instance of the pattern will be repeated from its start day until the end of the period that the instance falls within. Otherwise, the pattern is not repeated. Default: false.

integer

The offset that the pattern may start with on the start day. If set to 0, the pattern must start with the first pattern day on each start day. If set to 1, the pattern may start from any of its pattern days on the start day. If set to 7 (for example), the pattern may start with every 7th pattern day on the start day. The pattern is then continued as usual. Default: 0.

object

Describes whether the pattern should skip over days that could be considered irrelevant for the pattern.

Show emptyDayBehaviours – properties

string (enum: INCLUDE | EXCLUDE | MATCH)

Describes whether the pattern counts days outside the schedule period as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). Takes priority over the dayWithoutDemand and dayOff properties. Default: “INCLUDE”.

string (enum: INCLUDE | EXCLUDE | MATCH)

Describes whether the pattern counts days without demand as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). Default: “INCLUDE”.

string (enum: INCLUDE | EXCLUDE | MATCH)

Describes whether the pattern counts days off as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). Default: “INCLUDE”.

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.

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": [
        {
          "shifts": { "ids": ["night-shift"] }
        },
        {
          "shifts": { "ids": ["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.

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",
      "importance": "STRICT",
      "isDesired": true,
      "periods": {
        "recurrentDefinition": {
          "daysPerPeriod": 3,
          "daysBetweenStarts": 7
        }
      },
      "patterns": [
        {
          "patternDays": [
            {
              "shifts": { "ids": ["shift_1"] }
            },
            {
              "shifts": { "ids": ["shift_1"] }
            },
            {
              "shifts": { "ids": ["shift_1"] }
            }
          ]
        },
        {
          "startDays": {
            "daysOfWeek": ["SAT"]
          },
          "patternDays": [
            {
              "shifts": { "ids": ["shift_2"] }
            },
            {
              "shifts": { "ids": ["shift_2"] }
            }
          ]
        }
      ]
    }
  ]
}

Patterns with role filters

You can use role filters to make a pattern apply only when an employee works in one of those roles.

The constraint specified below makes it undesirable for employees to work the night shift on both Saturday and Sunday when they are working in role 1 or role 2.

{
  "id": "spc-weekend-roles",
  "importance": "MEDIUM",
  "isDesired": false,
  "patterns": [
    {
      "startDays": {
        "daysOfWeek": ["SAT"]
      },
      "patternDays": [
        {
          "shifts": { "ids": ["night-shift"] }
        },
        {
          "shifts": { "ids": ["night-shift"] }
        }
      ],
      "roles": {
        "ids": ["role_1", "role_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 empty day behaviours is as follows:

Empty day behaviour	Impact
INCLUDE	Days are always included in the pattern (never skipped over), regardless of whether it is an empty day or not.
EXCLUDE	Days are always excluded from the pattern (always skipped over), regardless of whether it is an empty day or not.
MATCH	Days 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).

Getting started

Concepts

Entities

Other

Constraint schema

Undesired patterns

Desired patterns

Patterns with role filters

Empty day behaviour