Employee schema
Show properties
Show properties
Unique identifier for this employee.
List of labels assigned to this employee. Labels can be used in constraints to group employees.
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
The category of the attribute.
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”.
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
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
List of dates in the schedule. Only allowed in CALENDAR payloads.
List of day indices in the schedule. Only allowed in RECURRING payloads.
List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
List of custom period definitions. Each custom period definition defines one period in the schedule.
Show customDefinitions – item structure
Show customDefinitions – item structure
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
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
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
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.
A recurrent definition to easily create a set of similar periods.
Show recurrentDefinition – properties
Show recurrentDefinition – properties
The number of days in each period.
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.
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
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
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
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.
Provide labels to re-use periods that were defined in the configuration.
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
Unique identifier for this role.
List of additional attributes this employee has when they work in this role.
Show attributes – item structure
Show attributes – item structure
The category of the attribute.
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”.
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
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
List of dates in the schedule. Only allowed in CALENDAR payloads.
List of day indices in the schedule. Only allowed in RECURRING payloads.
List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
List of custom period definitions. Each custom period definition defines one period in the schedule.
Show customDefinitions – item structure
Show customDefinitions – item structure
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
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
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
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.
A recurrent definition to easily create a set of similar periods.
Show recurrentDefinition – properties
Show recurrentDefinition – properties
The number of days in each period.
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.
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
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
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
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.
Provide labels to re-use periods that were defined in the configuration.
List of assignments that are pre-assigned to this employee.
Show preassignedShifts – item structure
Show preassignedShifts – item structure
Unique identifier for the shift.
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
List of dates in the schedule. Only allowed in CALENDAR payloads.
List of day indices in the schedule. Only allowed in RECURRING payloads.
List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
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.
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.
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]
}
}
]
}