This document describes the data format used for ScheduleSolver problem instances.
As well as being read by the rostering engine, the format can also
be read by RosterViewer.
The data format is an XML based format and can be validated
against the format's schema.
To help get started a ScheduleSolver XML template file is also available.
Although instances can be created using an editor, in practice the XML
is normally generated dynamically by another application. This XML is then
passed to the rostering engine which solves the
problem and returns the solution. The solution is also encoded using an XML
format.
The data required to describe an employee scheduling problem instance can be split into five main sections:
The root element of the document is <ScheduleSolver>. This is the opening tag.
The root element of the document.
Attributes
Name | Required | Type | Description | Ver. |
ID | Optional | string | An ID used to identify the instance. | 1.0+ |
Elements
ScheduleSolver contains the following elements in any order:
Name | Required | Type | Description | Ver. |
<StartDate> | Required | date | The date of the first day in the scheduling horizon. Specified in the format : YYYY-MM-DD. | 1.0+ |
<EndDate> | Required | date | The date of the last day in the scheduling horizon. Specified in the format : YYYY-MM-DD. | 1.0+ |
<Tasks> | Optional | Tasks | The tasks to be assigned. | 1.7+ |
<ShiftTypes> | Optional | ShiftTypes | For some constraints it is necessary to categorise each shift as a certain type e.g. a 'Night Shift', 'Late Shift' or 'Early Shift' etc. The shifts can be categorised by their start times, end times and lengths. The shift types are defined here. | 1.0+ |
<Contracts> | Optional | Contracts | Each employee can have a different set of constraints for their work schedule. These are specified within contracts which are linked to each employee. | 1.0+ |
<Employees> | Optional | Employees | The employees to assign the tasks to. | 1.0+ |
<Expressions> | Optional | Expressions | Expressions are used to create customised constraints. | 2.0+ |
<FixedAssignments> | Optional | FixedAssignments | Tasks, time periods and days which must be assigned or not assigned (they are fixed in place and cannot be changed). | 1.0+ |
<Requests> | Optional | Requests | Employee requests for days on or off, or specific shift types on certain dates. | 1.2+ |
Example
<?xml version="1.0" encoding="UTF-8"?> <ScheduleSolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ScheduleSolver-1.0.xsd"> <StartDate>2018-10-07</StartDate> <EndDate>2018-10-13</EndDate> <Tasks> <Task ID="T1"> <Start>2018-10-07T06:00:00</Start> <End>2018-10-07T20:00:00</End> <Weight>1000000</Weight> </Task> <Task ID="T2"> <Start>2018-10-07T04:00:00</Start> <End>2018-10-07T16:00:00</End> <Weight>1000000</Weight> </Task> <Task ID="T3"> <Start>2018-10-07T20:00:00</Start> <End>2018-10-08T06:00:00</End> <Weight>1000000</Weight> </Task> </Tasks> <Employees> <Employee ID="0"> <ContractID>C1</ContractID> <ContractID>C2</ContractID> </Employee> <Employee ID="1"> <ContractID>C2</ContractID> </Employee> <Employee ID="2"> <ContractID>C2</ContractID> </Employee> <Employee ID="3"> <ContractID>C2</ContractID> </Employee> <Employee ID="4"> <ContractID>C2</ContractID> </Employee> </Employees> <Contracts> <Contract ID="C1"> <ShiftLengths> <Min> <Length>360</Length> <Label>Min 6h shifts</Label> <Weight function="Linear">1</Weight> </Min> <Max> <Length>750</Length> <Label>Max 12.5h shifts</Label> </Max> </ShiftLengths> </Contract> <Contract ID="C2"> <MinRestTime>660</MinRestTime> <MinRestInPeriod start="2018-10-07T00:00:00" end="2018-10-14T00:00:00" label="An unbroken rest period of 45 hours every week">2700</MinRestInPeriod> <DailyRest dayStart="03:00" label="Min 11 hours continuous rest in 24hrs">660</DailyRest> <ShiftLengths> <Min> <Length>510</Length> <Label>Min 8.5h shifts</Label> <Weight function="Linear">1</Weight> </Min> <Max> <Length>750</Length> <Label>Max 12.5h shifts</Label> </Max> </ShiftLengths> <Workload> <TimeUnits> <PeriodStart>2018-10-07</PeriodStart> <PeriodEnd>2018-10-13</PeriodEnd> <Max> <Count>2550</Count> <Label>Max 42.5 hrs</Label> </Max> </TimeUnits> </Workload> </Contract> </Contracts> <FixedAssignments> <Employee ID="0"> <NoShift> <Start>2018-10-07T08:00</Start> <End>2018-10-08T12:30</End> </NoShift> <NoShift> <Start>2018-10-09T14:00</Start> <End>2018-10-13T19:00</End> </NoShift> </Employee> <Employee ID="1"> <NoShift> <Start>2018-10-07T08:00</Start> <End>2018-10-13T19:00</End> </NoShift> <Task ID="T3"/> <NotTask ID="T2"/> </Employee> </FixedAssignments> </ScheduleSolver>
The tasks to be assigned. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in later versions).
Parents : ScheduleSolver
Attributes
None
Elements
0 or more Task or LinkedTask elements.
Name | Required | Type | Description | Ver. |
<Task> | Optional | Task | A task definition. | 1.7+ |
<LinkedTask> | Optional | LinkedTask | A group of tasks which much be assigned to the same person. | 2.0+ |
Example
<Tasks> <Task ID="L1"> <Start>2018-10-07T06:00:00</Start> <End>2018-10-07T20:00:00</End> <UnassignedWeight>1000000</UnassignedWeight> </Task> <Task ID="N1"> <Start>2018-10-07T08:00:00</Start> <End>2018-10-08T06:00:00</End> <UnassignedWeight>1000000</UnassignedWeight> </Task> <Task ID="E1"> <Start>2018-10-07T04:00:00</Start> <End>2018-10-07T16:00:00</End> <UnassignedWeight>1000000</UnassignedWeight> </Task> </Tasks>
A task definition. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in later versions).
Parents : Tasks
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | A unique ID for this task. | 1.7+ |
Elements
Task contains the following elements in any order:
Name | Required | Type | Description | Ver. |
<Start> | Required | DateTime | The task's start time. | 1.0+ |
<End> | Optional | DateTime | The tasks's end time. | 1.0+ |
<Worktime> | Optional | NonNegativeDouble | In minutes, the total time counted as working time. Since version 1.6+, Worktime can optionally have an attribute 'contract' to define the worktime for this task when it is assigned to an employee with the specified contract. | 1.2+ |
<UnassignedWeight> | Optional | NonNegativeDouble | The penalty if this task is not assigned. | 1.3+ |
<AssignedWeight> | Optional | NonNegativeDouble | The penalty if this task is assigned. | 1.3+ |
<Skills> | Optional | Skills | The skills, qualifications, experience, training, group etc required by employees for this task. | 1.4+ |
<ShiftType> | Optional | ID | The task's ShiftType. | 1.6+ |
<Resources> | Optional | Resources | Resource values associated with the Task. The Workload constraint can be applied to the resource values defined here instead of Worktime. | 1.10+ |
Example
<Task ID="E1"> <Start>2021-10-07T06:00:00</Start> <End>2021-10-07T16:00:00</End> <UnassignedWeight>1000000</UnassignedWeight> <Skills> <Skill>Skill1</Skill> <Skill>Skill2</Skill> </Skills> <ShiftType>EarlyShift</ShiftType> <Worktime contract="C1">600</Worktime> <Worktime contract="C2">540</Worktime> <Worktime>570</Worktime> </Task>
The skills, qualifications, experience, training, group etc required by employees for a task. Skills for each employee are defined in Employees.
Parents : Task
Attributes
None
Elements
Skills contains one or more <Skill> elements.
Name | Required | Type | Description | Ver. |
<Skill> | Required | string | A skill ID. | 1.4+ |
Example
<Skills> <Skill>Skill1</Skill> <Skill>Skill2</Skill> </Skills>
Resource values associated with a Task. The Workload constraint can be applied to the resource values defined here instead of Worktime.
Parents : Task
Attributes
None
Elements
Resources contains one or more <Resource> elements.
Name | Required | Type | Description | Ver. |
<Resource> | Required | Resource | A resource ID and value. | 1.10+ |
Example
<Resources> <Resource ID="R1">100</Resource> <Resource ID="R2">1000</Resource> </Resources>
A resource ID and value.
Parents : Resources
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | The resource ID. | 1.10+ |
Type
Example
<Resource ID="Resource1">1000</Resource>
A group of tasks which much be assigned to the same person.
Parents : Tasks
Attributes
Name | Required | Type | Description | Ver. |
ID | Optional | ID | A unique ID for this LinkedTask. | 2.0+ |
Elements
1 or more Task elements.
Name | Required | Type | Description | Ver. |
<Task> | Optional | Task | A task definition. | 2.0+ |
Example
<LinkedTask ID="LT1"> <Task ID="1"> <Start>2024-01-22T08:00:00</Start> <End>2024-01-22T17:00:00</End> <Worktime>540</Worktime> <UnassignedWeight>100000</UnassignedWeight> <ShiftType>D</ShiftType> </Task> <Task ID="2"> <Start>2024-01-23T08:00:00</Start> <End>2024-01-23T17:00:00</End> <Worktime>540</Worktime> <UnassignedWeight>100000</UnassignedWeight> <ShiftType>D</ShiftType> </Task> <Task ID="3"> <Start>2024-01-25T08:00:00</Start> <End>2024-01-25T17:00:00</End> <Worktime>540</Worktime> <UnassignedWeight>100000</UnassignedWeight> <ShiftType>D</ShiftType> </Task> </LinkedTask>
For some constraints it is necessary to categorise each shift as
a certain type e.g. a 'Night Shift', 'Late Shift' or 'Early Shift' etc. The shifts can be categorised by
their start times, end times and lengths. The shift types are defined here.
When categorising a shift the engine looks through the shift types defined here in the order they are
defined here and uses the first shift type definition it finds with a matching set of start time, end
time and length definitions. If no matching shift type is found then the last shift type in the list
is used by default. The start, end and length definitions are all optional.
Parents : ScheduleSolver
Attributes
None
Elements
0 or more Shift elements.
Name | Required | Type | Description | Ver. |
<Shift> | Optional | Shift | A shift type definition. | 1.0+ |
Example
<ShiftTypes> <Shift ID="N"> <Name>Night Shift</Name> <Label>N</Label> <MinEnd>23:00</MinEnd> <MaxEnd>1.08:00</MaxEnd> </Shift> <Shift ID="L"> <Name>Late Shift</Name> <Label>L</Label> <MinEnd>18:00</MinEnd> <MaxEnd>23:00</MaxEnd> </Shift> <Shift ID="E"> <Name>Early Shift</Name> <Label>E</Label> <MaxStart>06:00</MaxStart> </Shift> <Shift ID="D"> <Name>Day Shift</Name> <Label>D</Label> </Shift> </ShiftTypes>
A shift type definition.
Parents : ShiftTypes
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | A unique ID for this shift type. | 1.0+ |
Elements
Shift contains the following elements in any order:
Name | Required | Type | Description | Ver. |
<Name> | Optional | string | A name for this shift. | 1.0+ |
<Label> | Optional | string | A label for the shift when displaying schedules. The ID is used if this element is omitted. | 1.0+ |
<Color> | Optional | string | A colour for the shift when displaying schedules. Any valid HTML colour may be used. | 1.0+ |
<MinStart> | Optional | TimeOfDay | A shift must start at or after this time to be categorised as this shift type. | 1.0+ |
<MaxStart> | Optional | TimeOfDay | A shift must start before or at this time to be categorised as this shift type. | 1.0+ |
<MinEnd> | Optional | TimeSpan | A shift must end at or after this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. | 1.0+ |
<MaxEnd> | Optional | TimeSpan | A shift must end before or at this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. | 1.0+ |
<MinLength> | Optional | NonNegativeDouble | In minutes. A shift must be at least this length to be categorised as this shift type. | 1.0+ |
<MaxLength> | Optional | NonNegativeDouble | In minutes. A shift must be at most this length to be categorised as this shift type. | 1.0+ |
<Resources> | Optional | Resources | Resource values associated with the shift type. The Workload constraint can be applied to the resource values defined here instead of Worktime. | 1.10+ |
Example
<Shift ID="N"> <Name>Night Shift</Name> <Label>N</Label> <Color>SkyBlue</Color> <MinStart>00:00</MinStart> <MaxStart>23:59</MaxStart> <MinEnd>23:00</MinEnd> <MaxEnd>1.08:00</MaxEnd> <MinLength>15</MinLength> <MaxLength>1440</MaxLength> </Shift>
Resource values associated with a shift type. The Workload constraint can be applied to the resource values defined here instead of Worktime.
Parents : Shift
Attributes
None
Elements
Resources contains one or more <Resource> elements.
Name | Required | Type | Description | Ver. |
<Resource> | Required | Resource | A resource ID, resource value, and optionally, the days it applies to. | 1.10+ |
Example
<Resources> <Resource ID="R1">10000</Resource> <Resource ID="R2" date="2024-10-07">4</Resource> <Resource ID="R2" dayOfWeek="Sunday">4</Resource> <Resource ID="R2" dayOfWeek="Saturday">2</Resource> </Resources>
A resource ID, resource value, and optionally, the days it applies to.
Parents : Resources
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | The resource ID. | 1.10+ |
date | Optional | string | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used then the resource value only applies to shifts on this date in the planning period. | 1.10+ |
dayOfWeek | Optional | DayOfWeek | If this is used then the resource value only applies to shifts on these days in the planning period. | 1.10+ |
Type
Example
<Resource ID="R1">10000</Resource>
Shift types can be placed in groups which are used in some constraints.
Parents : ScheduleSolver
Attributes
None
Elements
ShiftGroups contains zero or more <ShiftGroup> elements.
Name | Required | Type | Description | Ver. |
<ShiftGroup> | Optional | ShiftGroup | A group of shift types. | 1.0+ |
Example
<ShiftGroups> <ShiftGroup ID="N"> <Shift>N1</Shift> <Shift>N2</Shift> </ShiftGroup> <ShiftGroup ID="L"> <Shift>L1</Shift> <Shift>L2</Shift> <Shift>L3</Shift> </ShiftGroup> <ShiftGroup ID="E"> <Shift>E1</Shift> <Shift>E2</Shift> <Shift>E3</Shift> </ShiftGroup> </ShiftGroups>
A group of shift types.
Parents : ShiftGroups
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | A unique ID for this group. | 1.0+ |
Elements
ShiftGroup contains one or more <Shift> elements.
Name | Required | Type | Description | Ver. |
<Shift> | Required | string | The ID of a shift type. Specified in Shift attribute 'ID'. | 1.0+ |
Example
<ShiftGroup ID="EN"> <Shift>E</Shift> <Shift>N</Shift> </ShiftGroup>
Contracts contain the constraints on the employees' work schedules.
Parents : ScheduleSolver
Attributes
None
Elements
Contracts contains zero or more <Contract> elements.
Name | Required | Type | Description | Ver. |
<Contract> | Optional | Contract | Contains the working preferences and requirements (constraints) for each employee with this contract. | 1.0+ |
Example
<Contracts> <Contract ID="C1"> <ShiftLengths> <Min> <Length>300</Length> <Label>Shift must not be less than 5h</Label> <Weight function="quadratic">100</Weight> </Min> <Max> <Length>480</Length> <Label>Shifts must be more than 8h</Label> <Weight function="quadratic">100</Weight> </Max> </ShiftLengths> </Contract> <Contract ID="C2"> <ShiftLengths> <Min> <Length>480</Length> <Label>Shift must not be less than 8h</Label> <Weight function="quadratic">100</Weight> </Min> <Max> <Length>540</Length> <Label>Shifts must be more than 9h</Label> <Weight function="quadratic">100</Weight> </Max> </ShiftLengths> </Contract> </Contracts>
The working preferences and requirements (constraints) for each employee assigned this contract. An employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee.
Parents : Contracts
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | A unique ID for this contract. | 1.0+ |
Elements
Contract contains zero or more of the following elements in any order.
Name | Required | Type | Description | Ver. |
<Label> | Optional | string | A label for this contract which is used when displaying solutions. | 1.0+ |
<MultipleTasksPerShift/> | Optional | MultipleTasksPerShift | By default an employee can be assigned a maximum of one task in each shift. If this tag is included though, then an employee's shifts can contain multiple tasks. | 1.7+ |
<MultipleShiftsPerDay> | Optional | MultipleShiftsPerDay | By default an employee can be assigned a maximum of one shift per day. If this tag is included though, then the employee can be assigned more than one shift on a single day. If multiple shifts are assigned on a day then the combined shifts are considered when calculating the start time, end time, shift length, shift type etc. | 1.0+ |
<MinRestTime> | Optional | NonNegativeDouble | A minimum amount of rest time (non-work time) required between two or more shifts. | 1.0+ |
<MinRestInPeriod> | Optional | MinRestInPeriod | A minimum amount of continuous rest (non-work) time required within a defined period. | 1.0+ |
<DailyRest> | Optional | DailyRest | A minimum amount of continuous rest (non-work) time required during 24 hours. | 1.0+ |
<Workload> | Optional | Workload | Minimum and maximum total working time between any two dates in the planning period. | 1.0+ |
<ShiftStartTimes> | Optional | ShiftStartTimes | Earliest and latest shift start times (optionally for each day). | 1.0+ |
<ShiftEndTimes> | Optional | ShiftEndTimes | Earliest and latest shift finish times (optionally for each day). | 1.0+ |
<ShiftStartEndTimes> | Optional | ShiftStartEndTimes | Valid combined start and finish times for shifts (optionally for each day). | 1.0+ |
<ShiftLengths> | Optional | ShiftLengths | Minimum and maximum shift lengths (optionally for each day). | 1.0+ |
<UseIfNeeded/> | Optional | UseIfNeeded | If this is used then employees with this contract will only be assigned shifts if they are needed. The constraint is given a weight and the employee will only be scheduled if doing so enables other constraints with higher weights to be satisfied. The constraint can be used to leave certain employees unscheduled if possible (for example, 'temporary' or 'dummy employees'). | 1.0+ |
<MaxTot/> | Optional | MaxTot | Used for modelling constraints such as a maximum number of days on or off or a maximum number of shifts of a particular type (optionally between two dates in the planning period). | 1.0+ |
<MinTot/> | Optional | MinTot | Used for modelling constraints such as a minimum number of days on or off or a minimum number of shifts of a particular type (optionally between two dates in the planning period). | 1.0+ |
<MaxSeq/> | Optional | MaxSeq | Used for modelling constraints such as a maximum number of consecutive days on or off or a maximum number of consecutive shifts of a particular type. | 1.0+ |
<MinSeq/> | Optional | MinSeq | Used for modelling constraints such as a minimum number of consecutive days on or off or a minimum number of consecutive shifts of a particular type. | 1.0+ |
<MaxTotWeekends/> | Optional | MaxTotWeekends | Maximum number of weekends worked. | 1.10+ |
<MinTotWeekends/> | Optional | MinTotWeekends | Minimum number of weekends worked. | 1.10+ |
<MaxSeqWeekends/> | Optional | MaxSeqWeekends | Maximum number of consecutive weekends worked. | 1.10+ |
<MinSeqWeekends/> | Optional | MinSeqWeekends | Minimum number of consecutive weekends worked. | 1.10+ |
<Sequence> | Optional | Sequence | A flexible constraint which can model a variety of rules on an employee's work schedule. | 1.2+ |
Example
<Contract ID="C1"> <MinRestTime>840</MinRestTime> <ShiftStartTimes> <Min> <Time>07:00</Time> <Label>Shifts must start after 7am</Label> <Weight>10</Weight> </Min> <Max> <Time>12:00</Time> <Label>Shifts must start before 12pm</Label> <Weight>10</Weight> </Max> </ShiftStartTimes> <ShiftLengths> <Min> <Length>480</Length> <Label>Shifts must not be less than 8h</Label> <Weight function="quadratic">100</Weight> </Min> <Max> <Length>720</Length> <Label>Shifts must not be more than 12h</Label> <Weight function="quadratic">100</Weight> </Max> </ShiftLengths> <Workload> <TimeUnits> <Max> <Count>2250</Count> <Label>Max 37.5 hours</Label> <Weight function="quadratic">1</Weight> </Max> <Min> <Count>2250</Count> <Label>Min 37.5 hours</Label> <Weight>1</Weight> </Min> </TimeUnits> </Workload> <MaxTot label="Max 6 shifts per week" value="6" shift="$" start="0" end="6" weight="100000"/> <MinTot label="Min 5 shifts per week" value="5" shift="$" start="0" end="6" weight="100000"/> <MaxTot label="Max 5 shifts per week (low priority)" value="5" shift="$" start="0" end="6" weight="100"/> <MinSeq label="Min 4 consecutive shifts" value="4" shift="$" weight="100000"/> <MaxSeq label="Max 6 consecutive shifts" value="6" shift="$" weight="100000"/> <MaxSeq label="Max 5 consecutive shifts (low priority)" value="5" shift="$" weight="100"/> <MinSeq label="Min 2 consecutive rest days (low priority)" value="2" shift="-" weight="100"/> <MaxSeq label="Max 3 consecutive rest days" value="3" shift="-" weight="100000"/> </Contract>
This constraint is used to specify earliest (minimum) and latest (maximum) shift start times. The constraint can be specified to apply to every day in the scheduling horizon or just a specific day in the horizon.
Parents : Contract
Attributes
None
Elements
ShiftStartTimes contains zero or more <Min> and/or <Max> elements (in any order).
Name | Required | Type | Description | Ver. |
<Min> | Optional | Min | The earliest a shift can start (soft constraint or hard constraint). | 1.0+ |
<Max> | Optional | Max | The latest a shift can start (soft constraint or hard constraint). | 1.0+ |
Example
<ShiftStartTimes> <Min> <Time>07:00</Time> <Label>Shift must start after 7am</Label> <Weight>10</Weight> </Min> <Min> <Time>08:00</Time> <Label>Ideally shift should start at 8am</Label> <Weight>1</Weight> </Min> <Max> <Time>08:00</Time> <Label>Ideally shift should start at 8am</Label> <Weight>1</Weight> </Max> <Max> <Time>12:00</Time> <Label>The latest the shift can start is 12pm</Label> <Weight>10</Weight> </Max> </ShiftStartTimes>
The earliest a shift can start.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a shift starts before the minimum time and the function type
specified is linear then the
penalty function value will be the difference in minutes between the shift's start time
and the minimum start time multiplied by the
weight. If the function is quadratic it will be the difference in minutes squared and then
multiplied by the weight.
Parents : ShiftStartTimes
Attributes
None
Elements
Min contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another earliest shift start time constraint for that day).
Name | Required | Type | Description | Ver. |
<Time> | Required | TimeOfDay | The earliest start time. | 1.0+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. | 1.0+ |
Example
<Min> <Time>07:00</Time> <Label>Shift must start after 7am</Label> <Weight>10</Weight> </Min>
The latest a shift can start.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a shift starts after the maximum time and the function type
specified is linear then the
penalty function value will be the difference in minutes between the shift's start time
and the maximum start time multiplied by the
weight. If the function is quadratic it will be the difference in minutes squared and then
multiplied by the weight.
Parents : ShiftStartTimes
Attributes
None
Elements
Max contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another latest shift start time constraint for that day).
Name | Required | Type | Description | Ver. |
<Time> | Required | TimeOfDay | The latest start time. | 1.0+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. | 1.0+ |
Example
<Max> <Time>12:00</Time> <Label>The latest the shift can start is 12pm</Label> <Weight>10</Weight> </Max>
This constraint is used to specify earliest (minimum) and latest (maximum) shift finish times. The constraint can be specified to apply to every day in the scheduling horizon or just a specific day in the horizon.
Parents : Contract
Attributes
None
Elements
ShiftEndTimes contains zero or more <Min> and/or <Max> elements (in any order).
Name | Required | Type | Description | Ver. |
<Min> | Optional | Min | The earliest a shift can end (soft constraint or hard constraint). | 1.0+ |
<Max> | Optional | Max | The latest a shift can end (soft constraint or hard constraint). | 1.0+ |
Example
<ShiftEndTimes> <Min> <Time>16:00</Time> <Label>Must finish at or after 16:00 on day 0</Label> <Weight>1000</Weight> <DayIndex>0</DayIndex> </Min> <Max> <Time>17:00</Time> <Label>Must finish at or before 17:00 on day 0</Label> <Weight>1000</Weight> <DayIndex>0</DayIndex> </Max> </ShiftEndTimes>
The earliest a shift can finish.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a shift ends before the minimum time and the function type
specified is linear then the
penalty function value will be the difference in minutes between the shift's end time
and the minimum end time multiplied by the
weight. If the function is quadratic it will be the difference in minutes squared and then
multiplied by the weight.
Parents : ShiftEndTimes
Attributes
None
Elements
Min contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another earliest shift end time constraint for that day).
Name | Required | Type | Description | Ver. |
<Time> | Required | TimeSpan | The earliest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. | 1.0+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. (The day is the day that the shift starts on). | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. (The day is the day that the shift starts on). | 1.0+ |
Example
<Min> <Time>16:00</Time> <Label>Must finish at or after 16:00 on day 0</Label> <Weight>1000</Weight> <DayIndex>0</DayIndex> </Min>
The latest a shift can finish.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a shift ends after the maximum time and the function type
specified is linear then the
penalty function value will be the difference in minutes between the shift's end time
and the maximum end time multiplied by the
weight. If the function is quadratic it will be the difference in minutes squared and then
multiplied by the weight.
Parents : ShiftEndTimes
Attributes
None
Elements
Max contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another latest shift end time constraint for that day).
Name | Required | Type | Description | Ver. |
<Time> | Required | TimeSpan | The latest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. | 1.0+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. (The day is the day that the shift starts on). | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. (The day is the day that the shift starts on). | 1.0+ |
Example
<Max> <Time>17:00</Time> <Label>Must finish at or before 17:00 on day 0</Label> <Weight>1000</Weight> <DayIndex>0</DayIndex> </Max>
This constraint is used to define valid start and end time combinations for shifts. In other words, for a person with this contract, the solver can only create shifts that satisfy at least one of the start and end time combinations defined here. This is a hard constraint.
Parents : Contract
Attributes
None
Elements
ShiftStartEndTimes contains zero or more <Shift> elements.
Name | Required | Type | Description | Ver. |
<Shift> | Optional | Shift | A valid start and end time combination for a shift. | 1.0+ |
Example
<ShiftStartEndTimes> <Shift> <MinStart>06:00</MinStart> <MaxStart>06:00</MaxStart> <MinEnd>14:00</MinEnd> <MaxEnd>14:00</MaxEnd> </Shift> <Shift> <MinStart>14:00</MinStart> <MaxStart>14:00</MaxStart> <MinEnd>20:00</MinEnd> <MaxEnd>20:00</MaxEnd> </Shift> <Shift> <MinStart>20:00</MinStart> <MaxStart>20:00</MaxStart> <MinEnd>1.06:00</MinEnd> <MaxEnd>1.06:00</MaxEnd> </Shift> </ShiftStartEndTimes>
A valid start and end time combination for a shift.
Parents : ShiftStartEndTimes
Attributes
Name | Required | Type | Description | Ver. |
date | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. This is the day that the shift starts on. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. | 1.0+ |
day | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. This is the day that the shift starts on. The first day in the scheduling horizon is day zero. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. | 1.0+ |
startDate | Optional | date | The start date for a range of days that this constraint applies to. Specified in the format : YYYY-MM-DD. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. | 1.0+ |
endDate | Optional | date | The end date for a range of days that this constraint applies to. Specified in the format : YYYY-MM-DD. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. | 1.0+ |
Elements
Shift contains in any order a <MinStart>, <MaxStart>, <MinEnd> and a <MaxEnd> element (all optional).
Name | Required | Type | Description | Ver. |
<MinStart> | Optional | TimeOfDay | The earliest start time. | 1.0+ |
<MaxStart> | Optional | TimeOfDay | The latest start time. | 1.0+ |
<MinEnd> | Optional | TimeSpan | The earliest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. | 1.0+ |
<MaxEnd> | Optional | TimeSpan | The latest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. | 1.0+ |
Example
<Shift startDate="2018-11-12" endDate="2018-11-19"> <MinStart>06:00</MinStart> <MaxStart>06:00</MaxStart> <MinEnd>14:00</MinEnd> <MaxEnd>14:00</MaxEnd> </Shift>
This constraint is used to specify minimum and maximum shift lengths. The constraint can be specified to apply to every day in the scheduling horizon or just a specific day in the horizon.
Parents : Contract
Attributes
None
Elements
ShiftLengths contains zero or more <Min> and/or a <Max> elements (in any order).
Name | Required | Type | Description | Ver. |
<Min> | Optional | Min | The minimum shift length. | 1.0+ |
<Max> | Optional | Max | The maximum shift length. | 1.0+ |
Example
<ShiftLengths> <Min> <Length>480</Length> <Label>Shift must not be less than 8h</Label> <Weight function="quadratic">100</Weight> </Min> <Min> <Length>540</Length> <Label>Try and assign shifts of length 9h</Label> <Weight function="quadratic">1</Weight> </Min> <Max> <Length>540</Length> <Label>Try and assign shifts of length 9h</Label> <Weight function="quadratic">1</Weight> </Max> <Max> <Length>720</Length> <Label>Shifts must be less than 12h</Label> <Weight function="quadratic">100</Weight> </Max> </ShiftLengths>
A minimum shift length.
The <Weight> element can optionally have an
attribute function to indicate how to calculate the penalty function value.
For example if a shift is shorter than the minimum length and the function type
specified is linear then the penalty function value will be the difference in
minutes between the shift's length and the minimum shift length multiplied by the
weight. If the function is quadratic it will be the difference in minutes
squared and then multiplied by the weight.
Parents : ShiftLengths
Attributes
None
Elements
Min contains in any order a <Length> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another minimum shift length constraint for that day).
Name | Required | Type | Description | Ver. |
<Length> | Required | NonNegativeDouble | The minimum shift length in minutes. | 1.0+ |
<Weight> | Required | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. | 1.0+ |
Example
<Min> <Length units="ShiftLength">480</Length> <Label>Shift must not be less than 8h</Label> <Weight function="quadratic">100</Weight> </Min>
A maximum shift length.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to indicate how to calculate the penalty function value.
For example if a shift is longer than the maximum length and the function type
specified is linear then the penalty function value will be the difference in
minutes between the shift's length and the maximum shift length multiplied by the
weight. If the function is quadratic it will be the difference in minutes
squared and then multiplied by the weight.
Parents : ShiftLengths
Attributes
None
Elements
Max contains in any order a <Length> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another minimum shift length constraint for that day).
Name | Required | Type | Description | Ver. |
<Length> | Required | NonNegativeDouble | The maximum shift length in minutes. | 1.0+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ |
<Label> | Optional | string | A label for the constraint used when displaying a solution. | 1.0+ |
<DayIndex> | Optional | NonNegativeInteger | The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. | 1.0+ |
<Date> | Optional | date | The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. | 1.0+ |
Example
<Max> <Length units="ShiftLength">720</Length> <Label>Shifts must be less than 12h</Label> <Weight function="quadratic">100</Weight> </Max>
By default, an employee can be assigned a maximum of one shift per day. Use this element to allow
multiple shifts per day.
If the element is empty, then any combination of shifts are allowed.
If one or more ValidGroup elements are provided, then only the shift combinations defined
in the groups may be assigned.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
on | Optional | Boolean | Set as true to allow multiple shifts per day and false to restrict to a maximum of one shift per day. | 1.7+ |
Elements
MultipleShiftsPerDay contains zero or more ValidGroup elements.
If the element is empty, then any combination of shifts are allowed.
If one or more ValidGroup elements are provided, then only the shift combinations defined
in the groups may be assigned.
Name | Required | Type | Description | Ver. |
<ValidGroup> | Optional | ValidGroup | A combination of shifts that can be assigned on the same day. | 1.10+ |
Example
<MultipleShiftsPerDay on="true"/>
A combination of shifts that can be assigned on the same day.
Parents : MultipleShiftsPerDay
Elements
ValidGroup contains one or more Shift elements.
Name | Required | Type | Description | Ver. |
<Shift> | Required | ID | A shift type ID defined in ShiftTypes. | 1.10+ |
Example
<MultipleShiftsPerDay> <ValidGroup> <Shift>E</Shift> <Shift>L</Shift> </ValidGroup> </MultipleShiftsPerDay>
By default an employee can be assigned a maximum of one task in each shift. If this tag is included though, then an employee's shifts can contain multiple tasks.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
on | Optional | Boolean | Set as true to allow multiple tasks per shift and false to restrict to a maximum of one task per shift. | 1.7+ |
Example
<MultipleTasksPerShift on="true"/>
Employees with this constraint will not be assigned shifts unless doing so enables other
constraints to be satisfied. The constraint is given a weight and the employee will only
be scheduled if doing so enables other constraints with higher weights to be
satisfied. The constraint can be used to leave certain employees unscheduled if possible
(for example, 'temporary' or 'dummy employees').
The weight is the penalty that will be added to the solution if this
employee is assigned one or more shifts. The weight should be less than the weight for
constraints which if are not already satisfied in a solution but can be
satisifed by including this employee, then the employee should be assigned shifts.
For example, say employees can only work a maximum of four night shifts but
it is not possible to satisfy cover demands without assigning five night
shifts to one employee. If the constraint has a weight of 1000 but there
is an employee with can be used if required but with a weight of 999
then instead of assigning the five night shifts to one employee (at a
penalty of 1000) instead the extra night shift will be assigned to the
"use if needed" employee at a penalty of 999.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
weight | Required | NonNegativeDouble | The weight. The employee will only be assigned shifts if doing so reduces the solution's penalty by more than this value. | 1.0+ |
start | Optional | NonNegativeInteger | A day index in the planning period specified as an integer (the planning period starts on day zero). If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or after this day in the planning period. This can be useful if the end of the previous planning period is included in this planning period. | 1.0+ |
startDate | Optional | date | A day index in the planning period given as a date. Specified in the format : YYYY-MM-DD. If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or after this day in the planning period. This can be useful if the end of the previous planning period is included in this planning period. | 1.0+ |
end | Optional | NonNegativeInteger | A day index in the planning period specified as an integer (the planning period starts on day zero). If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or before this day in the planning period. | 1.0+ |
endDate | Optional | date | A day index in the planning period given as a date. Specified in the format : YYYY-MM-DD. If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or before this day in the planning period. | 1.0+ |
label | Optional | string | A label for the constraint. The label is only used in visualisations such as RosterViewer. | 1.0+ |
shiftGroup | Optional | string |
If this is used then the employee will only be considered as being scheduled if they
receive one or more shift types from this group. For example, if there was a 'vacation' shift
and the shift type group did not include the 'vacation' shift type then the employee
would not be considered as being scheduled if they had only 'vacation' shift types.
The ID is defined in ShiftGroups. It is also possible to specify a shift type group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
1.0+ |
shift | Optional | string |
If this is used then the employee will only be considered as being scheduled if they
receive one or more of this shift type. The ID is defined in ShiftTypes. It is also possible to specify a shift type group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
1.0+ |
Example
<UseIfNeeded weight="99999" label="Only use this employee if needed" startDate="2014-03-10"/>
<MaxTot>, <MinTot>, <MaxSeq>, <MinSeq>
<MaxTot> and <MinTot>
are used to model maximum and minimum total numbers of days on or off or
a particular shift type.
<MaxSeq> and <MinSeq>
are used to model maximum and minimum consecutive numbers of days on or off or
a particular shift type.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. | ||||||||||||
value | Required | NonNegativeInteger | The maximum or minimum. | 1.0+ | ||||||||||||
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.0+ | ||||||||||||
function | Optional | string | The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.0+ | ||||||||||||
shift | Optional | string |
Indicates whether the constraint applies to days on, days off or specific shift types.
Possible values are :
It is also possible to specify a shift type group as a comma separated list of shift type ID's (e.g. "E,D,L,N"). |
1.0+ | ||||||||||||
start | Optional | NonNegativeInteger or Date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used then the constraint only applies on or after the this date in the planning period. | 1.0+ | ||||||||||||
end | Optional | NonNegativeInteger or Date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used then the constraint only applies on or before this date in the planning period. | 1.0+ | ||||||||||||
label | Optional | string | A label for the constraint. The label is only used in visualisations such as RosterViewer. | 1.0+ |
Example
<MaxTot label="Max 4 night shifts" value="4" shift="N" weight="100000"/> <MaxTot label="Max 6 shifts in week one" value="6" shift="$" start="2014-03-10" end="2014-03-16" weight="100000"/> <MinTot label="Min 4 shifts in week one" value="4" shift="$" start="2014-03-10" end="2014-03-16" weight="100000"/> <MinSeq label="Min 2 consecutive shifts" value="2" shift="$" weight="1000"/> <MaxSeq label="Max 5 consecutive shifts" value="5" shift="$" weight="100000"/> <MinSeq label="Min 2 consecutive days off" value="2" shift="-" weight="100"/>
<MaxTotWeekends>, <MinTotWeekends>, <MaxSeqWeekends>, <MinSeqWeekends>
<MaxTotWeekends> and <MinTotWeekends>
are used to model the maximum and minimum number of weekends worked within a period.
<MaxSeqWeekends> and <MinSeqWeekends>
are used to model the maximum and minimum number of consecutive weekends worked within a period.
Weekends are defined by a start time and day and an end time and day.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
value | Required | NonNegativeInteger | The maximum or minimum. | 1.10+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.10+ |
function | Optional | string | The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.10+ |
startTime | Required | TimeOfDay | The weekend start time. | 1.10+ |
startDay | Required | DayOfWeek | The weekend start day. | 1.10+ |
endTime | Required | TimeOfDay | The weekend end time. | 1.10+ |
endDay | Required | DayOfWeek | The weekend start time. | 1.10+ |
restShifts | Optional | string | A shift specified using an ID defined in ShiftTypes,
or a shift group specified using an ID defined in ShiftGroups.
These shifts are not considered as work.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
1.10+ |
periodStart | Optional | NonNegativeInteger or Date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used, then the constraint only applies on or after the this date in the planning period. | 1.10+ |
periodEnd | Optional | NonNegativeInteger or Date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used, then the constraint only applies on or before this date in the planning period. | 1.10+ |
previousSeq | Optional | NonNegativeInteger | The previous number of consecutive weekends worked before the start of this scheduling period. | 1.10+ |
shiftStartOnly | Optional | Boolean | If true then a shift must start within the weekend definition for it to be considered as a working weekend. For example, if this is set as true and if the weekend is defined as starting at 00:00 on Saturday, and there is a shift on Friday from 20:00 to 08:00 on Saturday, then this is not considered a worked weekend because the shift starts before 00:00 on Saturday. (False, if not set). | 1.10+ |
label | Optional | string | A label for the constraint. The label is only used in visualisations such as RosterViewer. | 1.10+ |
Example
<MaxTotWeekends startDay="Friday" startTime="22:00" endDay="Monday" endTime="00:00" value="0" weight="1000" restShifts="V" label="Max 0 weekend shifts"/> <MaxSeqWeekends startDay="Saturday" startTime="00:00" endDay="Monday" endTime="00:00" value="2" weight="1000" restShifts="V" previousSeq="1" label="Max 2 weekends in a row"/>
This constraint is used to model the requirements of min/max total working time between any two dates in the planning period.
Parents : Contract
Attributes
None
Elements
Workload contains one or more <TimeUnits> elements.
Name | Required | Type | Description | Ver. |
<TimeUnits> | Required | TimeUnits | TimeUnits specifies a minimum and/or maximum total amount of work time that can be assigned to the employee between any two dates in the planning period. | 1.0+ |
Example
<Workload> <TimeUnits> <Max> <Count>2100</Count> <Label>Max 2100 mins</Label> <Weight function="quadratic">100</Weight> </Max> <Min> <Count>2100</Count> <Label>Min 2100 mins</Label> <Weight>100</Weight> </Min> </TimeUnits> </Workload>
TimeUnits specifies a minimum and/or maximum total amount
of work time that can be assigned to the employee between any two dates in the planning period.
The dates can be specified using the day number in the planning horizon or actual dates. The
first day in the planning period is day zero. A day starts at midnight (00:00).
A shift which starts before but finishes after the period start date is not counted in the total work time for a period.
A shift which starts within the period but finishes after the period end date is counted in its entirety in the total work time for a period.
That is, the total work time for a period is the sum of the shifts which start
within the period.
Parents : Workload
Attributes
None
Elements
Workload contains a <Min> and/or a <Max> element (in either order) and a <PeriodStart> and <PeriodEnd> (both also optional).
The default start day is day zero if <PeriodStart> is omitted. The default end day is the last day in the planning horizon if <PeriodEnd> is omitted.
Name | Required | Type | Description | Ver. |
<Min> | Optional | Min | The minimum number of minutes worked. | 1.2+ |
<Max> | Optional | Max | The maximum number of minutes worked. | 1.2+ |
<PeriodStart> | Optional | string | The first day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. | 1.2+ |
<PeriodEnd> | Optional | string | The last day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. | 1.2+ |
Example
<TimeUnits> <Max> <Count>2250</Count> <Label>Max 37.5 hours</Label> <Weight>1</Weight> </Max> <Min> <Count>2250</Count> <Label>Min 37.5 hours</Label> <Weight>1</Weight> </Min> </TimeUnits>
A minimum number of minutes to work.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a minimum is not satisfied and the function type specified is linear then the
penalty function value will be the minimum value minus the value provided in the solution
then multiplied by the
weight. If the function is quadratic it will be minimum value minus the value
provided in the solution then squared and then
multiplied by the weight.
Parents : TimeUnits
Attributes
None
Elements
Min contains the following elements in any order.
Name | Required | Type | Description | Ver. |
<Count> | Required | NonNegativeDouble | The minimum number of minutes to work. | 1.2+ |
<Weight> | Required | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.2+ |
<Label> | Optional | string | A label for the constraint for when displaying a solution. | 1.2+ |
<Resource> | Optional | string | The resource ID that the constraint applies to. Resource values are defined in Tasks and ShiftTypes. | 1.10+ |
Example
<Min> <Count>2100</Count> <Label>Min 2100 mins per week</Label> <Weight>100</Weight> </Min>
A maximum number of minutes to work.
If the <Weight> element is not used then it is a hard constraint.
The <Weight> element can optionally have an
attribute function to set how to calculate the penalty function value.
For example if a maximum is exceeded and the function type specified is linear then the
penalty function value will be the value provided in the solution minus the
maximum value then multiplied by the
weight. If the function is quadratic it will be the value provided in the
solution minus the maximum value then squared and then
multiplied by the weight.
Parents : TimeUnits
Attributes
None
Elements
Max contains the following elements in any order.
Name | Required | Type | Description | Ver. |
<Count> | Required | NonNegativeDouble | The maximum number of minutes to work. | 1.2+ |
<Weight> | Optional | NonNegativeDouble | A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.2+ |
<Label> | Optional | string | A label for the constraint for when displaying a solution. | 1.2+ |
<Resource> | Optional | string | The resource ID that the constraint applies to. Resource values are defined in Tasks and ShiftTypes. | 1.10+ |
Example
<Max> <Count>2250</Count> <Label>Max 37.5 hours</Label> <Weight>1</Weight> </Max>
A minimum amount of rest time (non-work time) required between two or more shifts. The time is in minutes. This is a hard constraint. The constraint can be set multiple times for each contract. For example, different minimum rest times can be set depending on whether the rest is spread over one rest period or two rest periods ore more.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
restPeriods | Optional | NonNegativeInteger | The number of consecutive rest periods the rest time can be spread over. For example, if the minimum rest time can be spread over two consecutive rest periods, then set this value as two. The default value is one if this attribute is not used. | 2.3+ |
restShifts | Optional | string | A shift specified using an ID defined in ShiftTypes,
or a shift group specified using an ID defined in ShiftGroups.
These shifts are not considered as work.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
2.3+ |
Elements
The minimum rest time required in minutes.
Example
<!-- 8 hours rest between shifts --> <MinRestTime restShifts="RestShifts">480</MinRestTime> <!-- 22 hours of rest time in two consecutive rest periods --> <MinRestTime restPeriods="2" restShifts="RestShifts">1320</MinRestTime>
A minimum amount of consecutive rest
required within a defined period.
If the <Weight> element is not used then it is a hard constraint.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
start | Required | DateTime | The start of the period the rest is required in. | 1.0+ |
end | Required | DateTime | The end of the period the rest is required in. | 1.0+ |
weight | Optional | NonNegativeDouble | The weight for the constraint. If the constraint is not satisfied then the weight is multiplied by the difference in minutes between the longest rest provided and the minimum rest required. | 1.0+ |
label | optional | string | A label for the constraint when displaying a solution. | 1.0+ |
splitShiftRest | optional | Boolean | If true then the time between split-shifts is considered as rest. False if omitted. | 1.0+ |
restShifts | Optional | string | A shift specified using an ID defined in ShiftTypes,
or a shift group specified using an ID defined in ShiftGroups.
These shifts are not considered as work.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
1.10+ |
Elements
The minimum consecutive rest required in minutes.
Example
<MinRestInPeriod start="2017-05-22T00:00:00" end="2017-05-30T00:00:00" weight="1000" label="At least one period of 24hr consecutive rest per week">1440</MinRestInPeriod>
A minimum amount of continuous rest (non-work) time, in minutes, required within 24 hours.
Parents : Contract
Attributes
Name | Required | Type | Description | Ver. |
dayStart | Optional | TimeOfDay | The time of day that the 24 hour period starts. If this attribute is omitted then the default value is 00:00. | 1.0+ |
weight | Optional | NonNegativeDouble | A value to represent this constraint's priority. If this attribute is omitted then the constraint is considered to be a hard constraint. | 1.0+ |
label | Optional | string | A label for this constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML). | 1.0+ |
restShifts | Optional | string | A shift specified using an ID defined in ShiftTypes
or a shift group specified using an ID defined in ShiftGroups.
Rest shifts are considered rest (non-work) time.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). |
1.10+ |
nextDayExceptions | Optional | string |
If the shift specified here is assigned on the next day then the DailyRest is
always satisfied. "-" (hyphen) can also be used to specify a day off.
A shift is specified using an ID defined in ShiftTypes or a shift group specified using an ID defined in ShiftGroups. It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N") and "-" for a day off. |
1.10+ |
Type
Example
<DailyRest dayStart="03:00" label="Min 11hrs continuous rest in 24hrs" weight="10000">660</DailyRest> <DailyRest dayStart="02:00" label="Min 12hrs continuous rest in 24hrs" weight="10000" restShifts="V">720</DailyRest>
This is a general and flexible constraint which can model a wide variety of rules in an employee's schedule.
Sequence specifies a minimum and/or maximum total number of matches of particular sequences of shift types between two dates in the planning period. The dates can be specified using the day index in the planning horizon or actual dates (the first day in the horizon is day zero). A sequence is only matched if it is found entirely between the start and end date.
A sequence is specified using a pattern which matches one of the following for each day in the pattern :
A pattern can optionally also include a start day or date which restricts the pattern to starting on that day. Many scheduling requirements can be modelled using this constraint. Examples of the different requirements that can be modelled using this constraint can be found in the example instances.
Parents : Contract
Attributes
None
Elements
Sequence contains a <Min> and/or a <Max> element (in either order) a <PeriodStart> a <PeriodEnd> and one or more <Pattern> elements.
The default start day is day zero if <PeriodStart> is omitted. The default end day is the last day in the planning horizon if <PeriodEnd> is omitted.
Name | Required | Type | Description | Ver. |
<Min> | Optional | Min | The minimum number of matches of the pattern(s). | 1.2+ |
<Max> | Optional | Max | The maximum number matches of the pattern(s). | 1.2+ |
<PeriodStart> | Optional | string | The first day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. | 1.2+ |
<PeriodEnd> | Optional | string | The last day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. | 1.2+ |
<Pattern> | Required | Pattern | A a sequences of shift types and/or days off. | 1.2+ |
Example
<Sequence> <Max count="3" weight="1000" label="Max three working Sundays"/> <Pattern> <Start>Sunday</Start> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="14" weight="1000" label="Max 14 shifts"/> <Pattern> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="4" weight="1000" label="Max four nights"/> <Pattern> <Shift>N</Shift> </Pattern> </Sequence> <Sequence> <Max count="0" weight="10" label="Min two consecutive days off"/> <Pattern> <Start>0</Start> <Shift>-</Shift> <Shift>$</Shift> </Pattern> <Pattern> <Shift>$</Shift> <Shift>-</Shift> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="0" weight="1000" label="Max six consecutive days"/> <Pattern> <Shift>$</Shift> <Shift>$</Shift> <Shift>$</Shift> <Shift>$</Shift> <Shift>$</Shift> <Shift>$</Shift> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="0" weight="1000" label="Work both days of the weekend, or have both days off"/> <Pattern> <Start>Saturday</Start> <Shift>$</Shift> <Shift>-</Shift> </Pattern> <Pattern> <Start>Saturday</Start> <Shift>-</Shift> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="0" weight="1000" label="No night shift before a weekend off"/> <Pattern> <Start>Friday</Start> <Shift>N</Shift> <Shift>-</Shift> <Shift>-</Shift> </Pattern> </Sequence> <Sequence> <Max count="0" weight="1000" label="At least two free days after a night shift"/> <Pattern> <Shift>N</Shift> <Shift>-</Shift> <Shift>$</Shift> </Pattern> </Sequence> <Sequence> <Max count="2" weight="1000" label="Max two consecutive weekends on"/> <PeriodStart>5</PeriodStart> <PeriodEnd>20</PeriodEnd> <Pattern> <Start>Saturday</Start> <Shift>$</Shift> <Shift>-</Shift> </Pattern> <Pattern> <Start>Saturday</Start> <Shift>-</Shift> <Shift>$</Shift> </Pattern> <Pattern> <Start>Saturday</Start> <Shift>$</Shift> <Shift>$</Shift> </Pattern> </Sequence>
Pattern is a sequence of shift types and days off.
Parents : Sequence
Attributes
None
Elements
Pattern contains any number of <Start>, or <StartExcludes> elements (all optional) followed by one or more <Shift> and/or <NotShift> elements (in any order).
If neither <Start> or <StartExcludes> is used then the pattern will be matched when it starts on any day in the planning period.
Name | Required | Type | Description | Ver. | ||||||||||||
<Start> | Optional | string | The pattern is only matched if it starts on this day in the planning period. The day can be specified as an index in the horizon as a NonNegativeInteger, or as a date, in the format YYYY-MM-DD, or as a day of the week, as 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', or 'Sunday'. A comma-separated list of values can also be used to represent multiple possible start days. | 1.2+ | ||||||||||||
<StartExcludes> | Optional | string | The pattern is only matched if it starts on any day in the planning period except the days, dates and days of the week specified. The day can be specified as an index in the horizon as a NonNegativeInteger, or as a date, in the format YYYY-MM-DD, or as a day of the week, as 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', or 'Sunday'. A comma-separated list of values can also be used to represent multiple possible start days. | 1.2+ | ||||||||||||
<Shift> | Optional | string |
Possible values are :
|
1.2+ | ||||||||||||
<NotShift> | Optional | string | Match anything but this shift type
(including a day without a shift). The shift type is
specified using an ID defined in ShiftTypes.
It is also possible to specify a shift type group as a comma-separated list of shift type ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID, meaning match anything but one of the shift types in this group of shift types (including a day without a shift). |
1.2+ |
Example
<Sequence> <Max count="3" weight="1000" label="Max 3 working Sundays"/> <Pattern> <Start>Sunday</Start> <Shift>$</Shift> </Pattern> </Sequence>
Specifies a minimum or maximum value for a constraint.
Parents : Sequence
Attributes
Name | Required | Type | Description | Ver. |
count | Required | NonNegativeInteger | The maximum or minimum. | 1.2+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.2+ |
function | Optional | string | The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. | 1.2+ |
label | Optional | string | A label for the constraint. The label is only used in visualisations such as RosterViewer. | 1.2+ |
Example
<Min count="1" weight="1000" label="Min 1..."/> <Max count="0" weight="1000" label="Max 0..." function="quadratic"/>
The employees.
Parents : ScheduleSolver
Attributes
None
Elements
0 or more Employee elements.
Name | Required | Type | Description | Ver. |
<Employee> | Required | Employee | An employee. | 1.0+ |
Example
<Employees> <Employee ID="E1"> <ContractID>ContractA</ContractID> </Employee> <Employee ID="E2"> <ContractID>ContractB</ContractID> </Employee> <Employee ID="E3"> <ContractID>ContractB</ContractID> </Employee> </Employees>
An employee in the roster.
Parents : Employees
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | ID | A unique ID for this employee. | 1.0+ |
Elements
Employee contains the following elements in any order.
More than one <ContractID> element can be included. If more than one <ContractID> is included
then all the constraints in each contract apply to the employee.
Name | Required | Type | Description | Ver. |
<ContractID> | Optional | string | The ID of the Contract which contains the work regulations and preferences (constraints) for this employee. An employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee. | 1.0+ |
<Name> | Optional | string | A label for the employee when displaying the solution. The ID is used if this element is omitted. | 1.0+ |
<Skills> | Optional | Skills | The skills, qualifications, experience, training, group etc this employee has/belongs to. A task that has skills defined cannot be asigned to this employee unless the employee has all the required skills for the task (see Task). A skill can also have a penalty associated with it if the skill is used or not used for a task. | 1.4+ |
Example
<Employee ID="E1"> <ContractID>C1</ContractID> <ContractID>C2</ContractID> <Skills> <Skill>Skill1</Skill> <Skill>Skill2</Skill> </Skills> </Employee>
The skills, qualifications, experience, training, group etc this employee has/belongs to. A task that has skills defined cannot be asigned to this employee unless the employee has all the required skills for the task (see Task). A skill can also have a penalty associated with it if the skill is used or not used for a task.
Parents : Employee
Attributes
Attributes
Name | Required | Type | Description | Ver. |
penaltyForUsing | Optional | NonNegativeDouble | The penalty if a task requiring this skill is assigned to this employee. | 1.9+ |
penaltyForNotUsing | Optional | NonNegativeDouble | The penalty if a task does not require this skill but the task is assigned to this employee. | 1.9+ |
Elements
Skills contains one or more <Skill> elements.
Name | Required | Type | Description | Ver. |
<Skill> | Required | string | A skill ID. | 1.4+ |
Example
<Skills> <Skill penaltyForNotUsing="1" penaltyForUsing="0">Cashier</Skill> <Skill penaltyForUsing="0.25">Greeting</Skill> <Skill penaltyForUsing="0.5">Filling</Skill> </Skills>
Expressions are used to create customised constraints. Expressions consist of boolean and numerical operators, boolean and numerical constants, functions and variables. The variables correspond to shift assignments in a solution. Expressions evaluate to boolean or numerical values. If a boolean expression evaluates to false, then the solution incurs the penalty value returned by the associated numerical expression.
Operators
Boolean: ==, !=, !, &&, || Numerical: ==, !=, >, <, >=, <=, +, *, -, /
The precedence and associativity of the operators is the same as in most
programming languages, including C#. Default operator associativity and
precedence can be overridden using parentheses.
(In XML elements, the characters '<' and '&' must be escaped using
< and & respectively, or CDATA used).
Constants
Boolean: true, false (case sensitive) Numerical: Integer or decimal values e.g. 0, 1, 1.234, -1, -1.234
Functions
Abs(x) - Returns the absolute value of the number x. Ceiling(x) - Returns the smallest integral value greater than or equal to the number x. Floor(x) - Returns the largest integral value less than or equal to the number x. Max(x,y) - Returns the larger of the two numbers x and y. Min(x,y) - Returns the smaller of the two numbers x and y. Pow(x,y) - Returns x raised to the power y. Round(x) - Returns x rounded to the nearest integral value. Rounds midpoint values to the nearest even number. Sign(x) - Returns -1 if x is less than zero. Returns 0 if x is equal to zero. Returns 1 if x is greater than zero.
Variables
Variables are defined using the identifier 'sum' followed by three or four sets of square brackets. For example:
sum["A"][0..1]["N"]
The first set of square brackets contains one or more Employee IDs, Contract IDs or Skill IDs. Each ID is in double quotes and multiple IDs can be listed, separated by commas. If a contract ID is used, then it represents the set of employees with that contract ID. A skill ID represents the set of employees with that skill.
The second set of brackets contains one of more integer values or ranges of integer values. The values represent days in the scheduling period. Ranges are defined using the .. operator. The left operand is inclusive, and the right operand is exclusive. For example, 0..2 represents days 0 and 1. The first day in the scheduling period is zero. Multiple days and ranges can be listed, separated by commas.
The third set of brackets contains one or more ShiftType IDs or ShiftGroup IDs. Each ID is in double quotes and multiple IDs can be listed, separated by commas. If a ShiftGroup ID is used, then it represents the set of shift types in that ShiftGroup.
The variable's value equals the total sum of all the shift types assigned on all the days to the all the employees listed within the variable. For example, the variable:
sum["A"][0]["N"]
has a value of 1 if employee A has an N shift assigned on day zero. It has a value of 0 if an N shift is not assigned on day zero to employee A.
The variable:
sum["A", "B"][0]["N"]
has a value of 2 if both employee A and employee B have N shifts on day zero. It has a value of 1 if only A or only B has an N shift on day zero. It has a value of 0 if neither A nor B have an N shift on day zero.
The variable:
sum["A"][0..2]["D"]
has a value of 2 if employee A has a D shift on day zero and day one. It has a value of 1 if employee A has a D shift on only day zero or only day one. It has a value of 0 if employee A has a D shift on neither day zero nor day one.
If the employee's contract allows multiple shifts per day, then all the shifts assigned on each day are counted towards the variable's value. For example, for the variable:
sum["A"][0]["E", "L"]
if employee A has both an E shift and an L shift on day zero, then the variable's value is 2.
A fourth set of square brackets may optionally be used. It contains a resource ID defined in ShiftTypes. If it is used, then the variable's value equals the total sum of the resource values for each shift type assigned.
Parents : ScheduleSolver
Attributes
None
Elements
0 or more Expr elements.
Name | Required | Type | Description | Ver. |
<Expr> | Optional | Expr | A boolean expression and an associated numerical expression. | 2.0+ |
Example
See Expr for examples.
Parents : Expressions
Attributes
Name | Required | Type | Description | Ver. |
ID | Optional | string | An ID for this expression. | 2.0+ |
Elements
Expr contains <Label>, <Constraint> and <Penalty> elements in any order. <Label> is used in RosterViewer when displaying and highlighting violations. It is also returned when using the API to look up and retrieve solution violations. The ID attribute will also be returned by the API when querying solution violations.
The <Constraint> element contains an expression which must return a boolean value. The <Penalty> element contains an expression which must return a numerical value. If the Constraint expression evaluates to false in a solution, then the solution incurs a penalty value equal to the Penalty expression's evaluation.
Name | Required | Type | Description | Ver. |
<Constraint> | Optional | string | A boolean expression which should evaluate to true in the solution. | 2.0+ |
<Penalty> | Optional | string | A numerical expression. If the Constraint expression evaluates to false then this expression's value is added to the solution's total penalty. | 2.0+ |
<Label> | Optional | string | A label for the expression. | 2.0+ |
Example
<Expressions> <Expr> <Label>At least 5 L shifts must be assigned to employees A, B and C</Label> <Constraint>sum["A","B","C"][0..28]["L"] >= 5</Constraint> <Penalty>1000</Penalty> </Expr> <Expr> <Label>At most 4 N shifts assigned to employees A, B and C on day zero (quadratic penalty)</Label> <Constraint>sum["A","B","C"][0]["N"] <= 4</Constraint> <Penalty>((sum["A","B","C"][0]["N"] - 4) * (sum["A","B","C"][0]["N"] - 4)) * 100</Penalty> </Expr> <Expr> <Label>Person A must not work more than 144 hours in 4 weeks</Label> <Constraint>((sum["A"][0..28]["E"] * 8) + (sum["A"][0..28]["L"] * 8) + (sum["A"][0..28]["N"] * 12)) <= 144</Constraint> <Penalty>(((sum["A"][0..28]["E"] * 8) + (sum["A"][0..28]["L"] * 8) + (sum["A"][0..28]["N"] * 12)) - 144) * 1000</Penalty> </Expr> <Expr> <Label>Person A must not have any N shifts if they have have E and L shifts"</Label> <Constraint>sum["A"][0..28]["E"] == 0 || sum["A"][0..28]["L"] == 0 || sum["A"][0..28]["N"] == 0</Constraint> <Penalty>1000</Penalty> </Expr> <Expr> <Label>If person A works an N shift on day zero then persons B and C must not work E or D shifts on day one</Label> <Constraint>sum["A"][0]["N"] == 0 || sum["B","C"][1]["E","D"] == 0</Constraint> <Penalty>1</Penalty> </Expr> <Expr> <Label>Assign 10 D shifts to employee A over weeks one and three (linear penalty function)</Label> <Constraint>sum["A"][0..7, 14..21]["D"] == 10</Constraint> <Penalty>abs(10 - sum["A"][0..7, 14..21]["D"]) * 1000</Penalty> </Expr> <Expr> <Label>If Person A works more than 4 night shifts then they must not work more than 36 hours</Label> <Constraint>sum["A"][0..7]["N"] <= 4 || sum["A"][0..7]["GroupAll"]["WorkHours"] <= 36</Constraint> <Penalty>(sum["A"][0..7]["GroupAll"]["WorkHours"] - 36) * 1000</Penalty> </Expr> </Expressions>
Requests for specific days on or off, or for specific shift types on or off.
Parents : ScheduleSolver
Attributes
None
Elements
Contains zero or more <OffDay>, <OnDay>, <OffShiftType>, <OnShiftType> elements in any order.
Name | Required | Type | Description | Ver. |
<OffDay> | Optional | OffDay | A day off constraint. | 1.2+ |
<OnDay> | Optional | OnDay | A day on constraint. | 1.2+ |
<OffShiftType> | Optional | OffShiftType | A shift type off constraint. (Pre version 1.7 this element was named <OffShift> but <OffShift> can still be used in later versions). | 1.7+ |
<OnShiftType> | Optional | OnShiftType | A shift type on constraint. (Pre version 1.7 this element was named <OnShift> but <OnShift> can still be used in later versions). | 1.7+ |
Example
<Requests> <OffDay weight="1000" employee="A" date="2018-02-18"/> <OffDay weight="1000" employee="A" date="2"/> <OnDay weight="1000" employee="B" date="2018-02-18"/> <OnDay weight="1000" employee="B" date="2"/> <OffShiftType weight="1000" employee="C" date="2018-02-18" shift="E"/> <OffShiftType weight="1000" employee="C" date="2" shift="L"/> <OnShiftType weight="1000" employee="D" date="2018-02-17" shift="E"/> <OnShiftType weight="1000" employee="D" date="0" shift="E,L,D"/> <OnShiftType weight="1000" employee="D" date="1" shift="Grp1"/> </Requests>
A day off constraint. The employee must not have any shifts on this day.
Parents : Requests
Attributes
Name | Required | Type | Description | Ver. |
employee | Required | string | An Employee ID. | 1.2+ |
date | Required | NonNegativeInteger or date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). | 1.2+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.2+ |
Example
<OffDay weight="1000" employee="A" date="2018-02-18"/>
A day on constraint. The employee must be working on this day.
Parents : Requests
Attributes
Name | Required | Type | Description | Ver. |
employee | Required | string | An Employee ID. | 1.2+ |
date | Required | NonNegativeInteger or date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). | 1.2+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.2+ |
Example
<OnDay weight="1000" employee="B" date="2018-02-18"/>
A shift type off constraint. The employee must not be assigned the specified shift type. (Pre version 1.7 this element was named <OffShift> but <OffShift> can still be used in later versions).
Parents : Requests
Attributes
Name | Required | Type | Description | Ver. |
employee | Required | string | An Employee ID. | 1.2+ |
shift | Required | string |
A ShiftType ID,
or, since version 2.5, a shift type group as a comma separated list of shift ID's (e.g. "E,D,L,N"), or a ShiftGroup ID. |
1.2+ |
date | Required | NonNegativeInteger or date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). | 1.2+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.2+ |
Example
<OffShiftType weight="1000" employee="C" date="2018-02-18" shift="E"/>
A shift type on constraint. The employee must be assigned the specified shift type or one of several shift types. (Pre version 1.7 this element was named <OnShift> but <OnShift> can still be used in later versions).
Parents : Requests
Attributes
Name | Required | Type | Description | Ver. |
employee | Required | string | An Employee ID. | 1.2+ |
shift | Required | string |
A ShiftType ID,
or a shift type group as a comma separated list of shift ID's (e.g. "E,D,L,N"), or a ShiftGroup ID. |
1.2+ |
date | Required | NonNegativeInteger or date | A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). | 1.2+ |
weight | Required | NonNegativeDouble | The weight for the constraint. | 1.2+ |
Example
<OnShiftType weight="1000" employee="D" date="2018-02-17" shift="E"/>
These are task assignments (or off assignments) which must be in the solution.
Parents : ScheduleSolver
Attributes
None
Elements
FixedAssignments contains zero or more <Employee> elements.
Name | Required | Type | Description | Ver. |
<Employee> | Optional | Employee | Contains assignments which must be in an employee's schedule in the solution. | 1.0+ |
Example
<FixedAssignments> <Employee ID="E1"> <NoShift> <Start>2019-11-16T08:00</Start> <End>2019-11-16T12:30</End> </NoShift> <NoShift> <Start>2019-11-17T14:00</Start> <End>2019-11-17T19:00</End> </NoShift> </Employee> <Employee ID="E2"> <NoShift> <Start>2019-11-19T08:00</Start> <End>2019-11-19T19:00</End> </NoShift> </Employee> </FixedAssignments>
These are task assignments (or off assignments) which must be in an employee's schedule in the solution.
Parents : FixedAssignments
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | string | The ID of the employee the assignments belong to. | 1.0+ |
Elements
Employee contains zero or more <NoShift>, <Task> and/or <NotTask> elements.
Name | Required | Type | Description | Ver. |
<NoShift> | Optional | NoShift | A time period during which the employee must have no shifts assigned. | 1.0+ |
<Task> | Optional | Task | A pre-assigned task which must be assigned in the solution. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in later versions). | 1.7+ |
<NotTask> | Optional | NotTask | A task which must not be assigned to this employee. (Pre version 1.7 this element was named <NotShift> but <NotShift> can still be used in later versions). | 1.7+ |
Example
<Employee ID="1"> <Task ID="T1" shiftID="S1"/> <Task ID="T2" shiftID="S1"/> <Task ID="T3" shiftID="S2"/> <Task ID="T4" shiftID="S2"/> <NotTask ID="T5"/> <NotTask ID="T6"/> </Employee>
An employee must have no shifts assigned during this time period.
Parents : Employee
Attributes
None
Elements
NoShift contains a <Start> and <End> element.
Name | Required | Type | Description | Ver. |
<Start> | Required | DateTime | The start of the time period during which the employee must not have any shift assignments. | 1.0+ |
<End> | Required | DateTime | The end of the time period during which the employee must not have any shift assignments. | 1.0+ |
Example
<NoShift> <Start>2019-11-19T08:00</Start> <End>2019-11-19T19:00</End> </NoShift>
A pre-assigned task which must be assigned in the solution. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in later versions).
Parents : Employee
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | string | The task ID (defined in Tasks). | 1.0+ |
shiftID | Optional | string | Tasks with an identical shiftID will be assigned in the same shift. The shiftID defined here will also be used in the solution XML to identify this shift. | 1.7+ |
Elements
None
Example
<Employee ID="1"> <Task ID="T1" shiftID="S1"/> <Task ID="T2" shiftID="S1"/> <Task ID="T3" shiftID="S2"/> <Task ID="T4" shiftID="S2"/> </Employee>
A task which must not be assigned to this employee. (Pre version 1.7 this element was named <NotShift> but <NotShift> can still be used in later versions).
Parents : Employee
Attributes
Name | Required | Type | Description | Ver. |
ID | Required | string | The task ID (defined in Tasks). | 1.0+ |
Elements
None
Example
<Employee ID="1"> <NotTask ID="T5"/> <NotTask ID="T6"/> </Employee>
Boolean is one of the values {true, false, 1, 0}.
Date specifies a date in the format YYYY-MM-DD where
YYYY (year) ranges from 0 to 9999
MM (month) ranges from 1 to 12
DD (day) ranges from 1 to 31.
The corresponding DateTime output format in C# is: yyyy-MM-dd.
DateTime specifies a date and time.
it must be in the format YYYY-MM-DDThh:mm[:ss] where
items in square brackets are optional and where
YYYY (year) ranges from 0 to 9999
MM (month) ranges from 1 to 12
DD (day) ranges from 1 to 31
T is the character 'T' used to denote the time component
hh (hours) ranges from 00 to 23,
mm (minutes) ranges from 00 to 59
and ss (seconds) ranges from 00 to 59.
Examples are: 2024-04-30T12:34:56, 2024-04-30T12:34.
The corresponding DateTime output format in C# is: yyyy-MM-dd'T'HH:mm:ss.
Valid values are: 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', or 'Sunday'.
A hard constraint is a rule or requirement which must be satisfied. In other words, it cannot be broken. A constraint which can be relaxed and sometimes broken is called a soft constraint.
ID is a string which can contain only the characters A to Z (upper and lower case), 0 to 9, period (.) and underscore (_).
Integer is a positive or negative whole number (e.g. ..,-2,-1,0,1,2,..). The + sign is optional for positive numbers. E.g. 1 and +1 are both valid values.
NonNegativeDouble is a number greater than or equal to zero which may also be fractional. That is, it can have a decimal component. For example 0, 1, 1.333, 1.5, 10.25, 1000 are all valid values.
NonNegativeInteger is a whole number greater than or equal to zero (e.g. 0,1,2,..).
PositiveDouble is a number greater than zero which may also be fractional. That is, it can have a decimal component. For example 0.1, 1, 1.333, 1.5, 10.25, 1000 are all valid values.
A soft constraint is an objective or a target. This means the engine will try and satisfy the constraint as closely as possible but it may create a solution which deviates slightly from the target. If the solution does deviate from the target then a penalty score is incurred. The penalty is proportional to the size of the deviation and the weight that is associated with the soft constraint. For example, if there is a soft constraint that a shift must start at 08:00AM (with a weight of 10) but the engine decides that in order to better satisfy some other soft constraints the shift should start at 07:45AM then a penalty of 15*10=150 (deviation*weight) is incurred. The overall penalty value for a solution is the sum of all penalties due to soft constraint violations. The engine produces a solution with a minimum overall penalty value. A constraint which cannot be broken is called a hard constraint.
TimeOfDay specifies a time in the day ranging from
00:00:00 to 23:59:59. It
must be in the format hh:mm:ss or hh:mm where
hh (hours) ranges from 0 to 23,
mm (minutes) ranges from 0 to 59
and ss (seconds) ranges from 0 to 59.
The corresponding DateTime output format in C# is: HH:mm:ss or HH:mm.
TimeSpan specifies a time in the day or a time span
which may be longer than 24 hours. It must be in the format [d.]hh:mm[:ss] where
items in square brackets are optional and where
d (days) ranges from 0 to 9999999
hh (hours) ranges from 0 to 23,
mm (minutes) ranges from 0 to 59
and ss (seconds) ranges from 0 to 59.
For example to represent a time span of 24 hours use 1.00:00 or to represent
the time 08:00AM on the next day use 1.08:00.