FILL request

Filling in pre-defined shifts with employees according to contractual agreements that enforce fair and cost efficient rosters. The input requires you to make up:

• open shifts
• available employees

Additionally, you can customise the solver behaviour by also changing the weights and priority of the constraints

This FILL request schema is used for solving a Shift Filling Problem. It consists of shifts, employees, options and weights.

Name	Type	Required	Description
shifts	[Shift]	true	List of Shifts
employees	[Employee]	true	List of Employees
rules	[Rule]	false	List of Rules
requirements	[Requirement]	false	List of Requirements
fairnessBuckets	[FairnessBucket]	false	List of Fairness buckets
rests	[Rest]	false	List of Rests
patterns	[Pattern]	false	List of Patterns
demands	[Demand]	false	List of Demands
assignments	[Assignment]	false	List of Assignments
options	Options	false	Options for solver configuration
weights	Weights	false	Weighting the constraints
hook	string(uri)	false	Webhook for getting notified after request is solved.

​

Shifts

The shifts represent the demand. These shifts need to be filled in with employees. A shift in its simplest form can be defined by a shift start time (from) and an end time (to). Shifts are uniquely identified by a name and require a specific skill. You can define the number of employees that need to be assigned to this shift with the minimum min to the maximum max.

Property	Type	Description
name	string	Unique id of the shift
from	string (datetime)	Starting time of the shift
to	string (datetime)	End time of the shift
skills	array of strings	Skill requirements references
cost	number	Financial cost related to this shift. Will be minimised when partialPlanning.
min	number	Minimum number of employees that should be assigned to this shift
max	number	Maximum number of employees that should be assigned to this shift
priority	number	Forces a priority constraint on this shift with 1 being highest priority and 10 being the lowest.
tags	array of ShiftTag	Shift tags. Used to identify groups of shifts in rules.
blocklist	array of string	List of employees that cannot do this shift.
rests	array of ShiftRest	Shift rests can define required idle/rest time after the shift.

​

ShiftTag

A shift tag can group shifts together under the same class. For instance: EARLY and NIGHT shifts are typical groups.

Name	Type	Description
name	string	Name of the tag.

​

Employees

Define the resources or employees with whom you want to fill up the shifts.

Property	Type	Description
name	string	Unique identifier for this employee
contract	string	Reference to contract for this employee.
skills	array of string	List of skill references.
lastRestDate	string (date)	The last date on which the employee had a rest before the planning period.
availability	array of string	Available date-time range of employee.
preference	array of string	Preference towards certain shifts. (shift name)
periodRules	array of PeriodRule	List of Period Rule

​

Period Rule

A shift rule for an employee that applies to a period of time. Labor rules such as max hours working.

Property	Type	Description
period	PlanningPeriod	Planning period for this period rule.
maxWorkingDays	integer	Maximum number of total days working in planning period.
minWorkingDays	integer	Minimum number of total days working in planning period.
minWorkingDuration	string	Minimum duration to work in the planning period.
maxWorkingDuration	string	Maximum duration to work in the planning period.
minRestDurationBetweenShiftsSameDay	string	Minimum duration between two shifts on the same day in this planning period.
minRestDuration	string	Minimum duration between any two shifts in this planning period.

​

Rule

Name	Type	Description
constraint	string	Type of constraint. Counter or Sequence. A counter counts the number of occurances and the constraint
type	type	Type of rule. Counter or Series.
period	period	Period in which this rule applies
min	Integer	Minimum number of employees necessary to fill these shifts.
max	Integer	Maximum number of employees necessary to fill these shifts. If min=max then you’ll get that exact amount of employees.
shifts	List	Shift tags to filter this rule by. For example only shifts with the tag `EARLY`.
then	Rule	Consequential rule.

​

Requirements

Governing skill requirements on certain shifts. For instance, on these specific shifts, we need to have at least 4 employees with skill x.

Name	Type	Description
shifts	list of string	List of shifts that the requirement applies to
skill	string	The skill this requirement applies to
value	number	The number of shared resources required for this skill.

​

Fairness

For a select group of employees and shifts you can require fair distribution of shifts per planning period. The planning period can be the entire planning period or a subset of it.

Name	Type	Description
period	Period
employees	list	The employees in the fairness bucket
shifts	list	The shifts in the fairness bucket
target	string (duration ISO8601)	The target value of workload per employee

​

Period

Define a planning period for which the fairness holds with from and to dates.

Name	Type	Description
from	string (date)	Start of the period
to	string (date)	End of the period

​

Pattern

Patterns define preferred, prohibited or unpreferred sequences of shifts.

Name	Type	Description
type	string	SINGLE_DAY (spanning shifts in a single days) or MULTI_DAY (spanning shifts accross days)
satisfy	string	(PREFERRED, PROHIBITED, or UNPREFERRED)
elements	PatternElement	List of Pattern Elements describing ON/OFF for several shifts
weight	Integer	Importance (weight) of the Pattern

​

PatternElement

A single element defining an entire pattern. The element can define to be ON/OFF for a certain shift (tag).

Name	Type	Description
type	string	ON (doing that shift) or OFF (not doing that shift)
tags	list of string	List of shift tags to include

​

Rest

Rests are periods of idle time defined throughout the entire period or either before/after a shift.

​

Assignment

If you want to set the current schedule, you can set the assignments. That is a list of shift and employee with optionally to lock it.

Name	Type	Description
shift	string	Name of the shift
employee	string	Name of the employee
locked	boolean	If the shift is locked. Locked shifts cannot be touched by the solver

​

Options

Custom solver options.

Name	Type	Description
hardAvailability	boolean	Whether to enforce availability constraints
hardSkill	boolean	Whether to enforce skill constraints
hardBlacklist	boolean	Whether to enforce blacklist constraints
partialPlanning	boolean	Partial planning. Whether to fill all shifts or not. Default is false
penaliseZeroHours	boolean	Whether to penalise employees with zero hours
useAvailabilityLocations	boolean	Whether to use availability locations
alwaysScoreSharedSkills	boolean	Whether to always score shared skills
explanation	Explanation	Explanation
idleWeekend	IdleWeekend	Idle weekend definition

​

ExplanationOptions

Name	Type	Description
enabled	boolean	Whether to enable explanation post processing
filterHardConstraints	boolean	Whether to filter hard constraint violated solutions in the alternatives response

​

IdleWeekendDefinition

How weekends are defined at the organization level.

Name	Type	Description
fromDayOfWeek	DayOfWeek	Day of the week on which the weekend officially starts.
fromTime	String	Time of day on which the weekend officially starts.
toDayOfWeek	DayOfWeek	Day of the week on which the weekend officially ends.
toTime	String	Time of day on which the weekend officially ends.
restTime	String (ISO8601 duration)	The amount of consecutive idle seconds required between the start and end of the above defined period for it to be considered a free weekend.