Employee Availability

This constraint can be used for three purposes, all related to which periods or shifts an employee should be considered available for:

Mark an employee as strictly unavailable for specific periods or shifts.
Mark an employee as available but undesirable for specific periods or shifts.
Mark an employee as available and desirable for specific periods or shifts.

Constraint schema

object

Used to indicate when employees are strictly or preferably available or unavailable to work.

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, it will be considered preferable for employees to work the shifts that this constraint applies to during the specified periods. If set to false, the solver will try to avoid assigning applicable shifts to employees during the specified periods. If importance is set to strict, this must be false.

object

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.

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

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

object

Defines filtering for specific work that the constraint should be applied to. For example, it can be used to apply the constraint only to work carried out in specific roles.

Show work – properties

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.

object

Used to apply the constraint only to work carried out with specific workload categories.

Show workloads – properties

array of string

If specified, the shift must have at least one of the workload categories specified in this list.

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.

object

Show options – properties

string (enum: PARTIAL | COMPLETE)

Used to indicate whether partial fulfillment per period is acceptable (PARTIAL) or not (COMPLETE). This setting can only be used for undesired constraints. Default: “PARTIAL”.

Strict unavailability

To define certain periods as strictly unavailable for an employee, simply specify the periods in the constraint. The solver will then never assign shifts to the employee during these periods.

The below constraint makes it strictly impossible for employee with id ‘employee-1’ to work on weekends.

{
  "id": "eac-weekends",
  "importance": "STRICT",
  "isDesired": false,
  "filters": {
    "employees": {
      "ids": ["employee-1"]
    }
  },
  "periods": {
    "labels": ["WEEKENDS"]
  }
}

Undesired availability

To mark that an employee would rather not work during certain periods, set the isDesired field to false and choose an importance level different than STRICT. The solver will try to avoid assigning shifts to the employee during these periods, but it is not strictly forbidden.

The below constraint makes it undesirable for employee with id ‘employee-1’ to work on Mondays or Thursdays.

{
  "id": "eac-undesired-mondays-thursdays",
  "importance": "HIGH",
  "isDesired": false,
  "filters": {
    "employees": {
      "ids": ["employee-1"]
    }
  },
  "periods": {
    "days": {
      "daysOfWeek": ["MON", "THU"]
    }
  }
}

Desired availability

To mark that an employee prefers working on certain periods or shifts, set the isDesired field to true and choose an importance level different than STRICT (STRICT is currently not supported on desired constraints).

The below constraint makes it preferred to assign shifts with shift label night to employee with id ‘employee-1’ on Mondays, Tuesdays or Wednesdays.

{
  "id": "eac-desired-night-shifts",
  "importance": "MEDIUM",
  "isDesired": true,
  "filters": {
    "employees": {
      "ids": ["employee-1"]
    },
    "shifts": {
      "labels": ["night"]
    }
  },
  "periods": {
    "days": {
      "daysOfWeek": ["MON", "TUE", "WED"]
    }
  }
}

Availability with work filters

You can also use work filters to target specific kinds of work. With role and workload filters, you can make the constraint apply only to work carried out in certain roles and with certain workload categories. It is also possible to apply role or workload filters separately.

The below constraint makes it undesirable for employee with id employee-1 to work shifts in role role-1 with workload category on_call on weekends. Work in other roles or with other workload categories is not targeted by this constraint.

{
  "id": "eac-undesired-weekend-role-1-oncall-workload",
  "importance": "HIGH",
  "isDesired": false,
  "filters": {
    "employees": {
      "ids": ["employee-1"]
    },
    "work": {
      "roles": {
        "ids": ["role_1"]
      },
      "workloads": {
        "categories": ["on_call"]
      }
    }
  },
  "periods": {
    "labels": ["WEEKENDS"]
  }
}

Getting started

Concepts

Entities

Other

Constraint schema

Strict unavailability

Undesired availability

Desired availability

Availability with work filters