Employee schema
object
Show properties
Show properties
string
required
Unique identifier for this employee.
array of string
List of labels assigned to this employee. Labels can be used in constraints 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
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 can have the values “marketing” and “finance” for an attribute with the id “department”.
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
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
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
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
Show startDay – properties
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
Show endDay – properties
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
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
Show startDay – properties
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
Show endDay – properties
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.
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
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
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 can have the values “marketing” and “finance” for an attribute with the id “department”.
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
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
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
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
Show startDay – properties
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
Show endDay – properties
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
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
Show startDay – properties
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
Show endDay – properties
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.
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
Show preassignedShifts – item structure
string
required
Unique identifier for the shift.
object
required
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 days – properties
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 the solver. 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 the solver 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 constraints 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 aredepartments, 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 inpreassignedShifts. 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 toisReadOnly 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]
}
}
]
}