Period Distribution

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

Rule schema

object

Used to define targets and limits for the distribution of periods (like weekends, holidays, nights).

Show properties

string

required

Unique identifier for the rule.

array of string

Labels for the rule. Labels can be used to group rules together. For example, if multiple rules are related to the same shift type, they can all be labeled with the same label.

required

The importance of the rule. The higher the importance, the more it will be taking the rule into account. Under strict importance, the rule may never be violated.

object

Filters to determine the scope of the rule. Used to indicate what the rule should be applied to (which employees, which shifts, etc). Leaving this empty means that the rule always applies.

Show filters – properties

object

Filters entities by id and label.

Show employees – properties

array of string

Entity ids to match.

array of string

Entity labels to match.

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

Filters entities by id and label.

Show shifts – properties

array of string

Entity ids to match.

array of string

Entity labels to match.

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

required

Defines targets and limits on the distribution of worked periods.

Show targets – properties

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

Additional options for how the rule should be applied.

Show options – properties

object

Specifies overlap thresholds that a shift must meet with the rule’s periods in order for it to be counted as relevant for the rule.

Show overlapSettings – properties

integer

The minimum number of hours that a shift must overlap with the rule in order to be counted as relevant for this rule.

integer

The minimum percentage of the shift that must overlap with the rule in order to be counted as relevant for this rule.

object

List of periods in the schedule. Periods can be defined explicitly or through a recurrent definition (for example, to generate weeks).

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.

Show startDay – properties

string (date)

Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.

integer

Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.

object

Describes one day in the schedule.

Show endDay – properties

string (date)

Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.

integer

Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.

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.

Show startDay – properties

string (date)

Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.

integer

Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.

object

Describes one day in the schedule.

Show endDay – properties

string (date)

Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.

integer

Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.

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.

Explanation

Within the context of this rule, a period is considered ‘worked’ for an employee if they work any shift during that period, and ‘free’ if they do not. The rule allows you to set targets 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 rule 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 options.overlapSettings.To work with labels on periods, make sure you have defined the period label in the extensions.labeling part of the payload.

{
  "id": "pd-max-weekends",
  "importance": "MEDIUM",
  "targets": {
    "maxWorkedPeriods": 2
  },
  "options": {
    "overlapSettings": {
      "minOverlapHours": 6
    }
  },
  "periods": {
    "labels": ["WEEKENDS"]
  }
}

Minimum worked periods

Alternatively, the rule can be used to encourage a minimum amount of worked periods for an employee.

The rule 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",
  "targets": {
    "minWorkedPeriods": 3
  },
  "periods": {
    "labels": ["WEEKENDS"]
  }
}

Maximum consecutive worked periods

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

The rule 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",
  "importance": "STRICT",
  "targets": {
    "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 rule 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.

The rule 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",
  "importance": "STRICT",
  "targets": {
    "minSurroundingFreePeriods": 1
  },
  "periods": {
    "labels": ["WEEKENDS"]
  }
}

Metrics

The following status metrics are available for tracking on Period Distribution rules:

Metric key	Description
`PERIOD_DISTRIBUTION.WORKED_PERIODS`	Number of periods with at least one assignment.
`PERIOD_DISTRIBUTION.MISSING_WORKED_PERIODS`	Total number of required worked periods that are missing.
`PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS`	Total number of worked periods above configured maximums.
`PERIOD_DISTRIBUTION.MAX_CONSECUTIVE_VIOLATIONS`	Total amount by which consecutive worked-period groups exceed their maximum.
`PERIOD_DISTRIBUTION.MIN_SURROUNDING_VIOLATIONS`	Total number of required surrounding free periods that are missing.

Getting started

Entities

Concepts

Reasoning

Status updates

Rule schema

Explanation

Maximum worked periods

Minimum worked periods

Maximum consecutive worked periods

Minimum surrounding free periods

Metrics