Employees

Employees form the foundation for all schedules produced by the solver. The primary objective for all produced schedules is to assign employees to shifts in such a way that they can optimally cover all demand for labour.

Employee schema

object

Show properties

string

required

Unique identifier for this employee.

array of string

List of labels assigned to this employee. Labels can be used in rules to group employees.

array of object

List of attributes that this employee has. Shifts, demands and tasks can have requirements on the attributes that an employee has.

Show attributes – item structure

string

The category of the attribute.

array of string

required

The values that the employee has for this attribute. For example, an employee could have the values “marketing” and “finance” for an attribute with the category “department”.

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.

array of object

Optional list of roles that this employee can work. Each role can have additional attributes that the employee has when working that role.

Show roles – item structure

string

Unique identifier for this role.

array of object

List of additional attributes this employee has when they work in this role.

Show attributes – item structure

string

The category of the attribute.

array of string

required

The values that the employee has for this attribute. For example, an employee could have the values “marketing” and “finance” for an attribute with the category “department”.

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

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

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.

array of object

List of assignments that are pre-assigned to this employee.

Show preassignedShifts – item structure

string

required

Unique identifier for the shift.

object

required

List of days in the schedule.

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.

boolean

Whether the shift is locked. Locked shifts cannot be changed by us. For read-only employees, all shifts are automatically considered locked. Default: false.

string

The role id of the role that the employee has when working this shift. Needs to match a role id from the employee’s list of roles.

boolean

If set to true, the employee will only work their preassigned shifts. These will not be altered, and we will not assign new shifts to this employee. Default: false.

Attributes

Employee attributes provide a flexible way to specify custom characteristics for each employee. These attributes can be used to determine eligibility for shifts, demands, or tasks. In addition, some rules can be configured to apply to all employees that meet certain attribute requirements. Some good examples of characteristics where it might make sense to use attributes are departments, competences, or personnel-groups. Each attribute must have its own unique category indicating what kind of attribute it is. An employee can have multiple values for the same attribute. Here’s an example of how to specify attributes for an employee:

The following example shows an employee that is part of the departments finance and hr, and has the competences manager and accountant. Finally, they are part of the personnel group group-1.

{
  "id": "employee-1",
  "attributes": [
    {
      "category": "department",
      "values": ["finance", "hr"]
    },
    {
      "category": "competence",
      "values": ["manager", "accountant"]
    },
    {
      "category": "personnel-group",
      "values": ["group-1"]
    }
  ]
}

Preassigned shifts

It is possible to start the solver from a partially filled schedule where employees already have some shifts assigned to them. These are specified in preassignedShifts. If these pre-assignments are set to isLocked, the solver will never change them. The solver therefore considers unlocked preassigned shifts as suggestions.

The following example shows an employee that is preassigned to work shift-1 shifts on each of the first four days of the schedule. These assignments are set as isLocked and will not be changed by the solver.

{
  "id": "employee-1",
  "preassignedShifts": [
    {
      "shiftId": "shift-1",
      "isLocked": true,
      "days": {
        "dayIndices": [0, 1, 2, 3]
      }
    }
  ]
}

Read-only employees

You can set an employee to isReadOnly to indicate that the solver should only use their preassigned shifts and not assign them to any new shifts. This is useful when you want to preserve certain employee assignments while allowing the solver to optimize the rest of the schedule. When an employee is marked as isReadOnly, the solver will:

Use all their preassigned shifts (regardless of whether they are locked or unlocked)
Not assign the employee to any additional shifts beyond their preassigned ones

The following example shows an employee that is set to read-only. The solver will only use their preassigned shifts and will not assign them to any new shifts.

{
  "id": "employee-1",
  "isReadOnly": true,
  "preassignedShifts": [
    {
      "shiftId": "shift-1",
      "days": {
        "dayIndices": [0, 1, 2, 3]
      }
    }
  ]
}

Getting started

Entities

Concepts

Employee schema

Attributes

Preassigned shifts

Read-only employees

Employee schema

​Attributes

​Preassigned shifts

​Read-only employees

Attributes

Preassigned shifts

Read-only employees