ShiftSolver problem data

XML format for ShiftSolver problem instances

This document describes the data format used for ShiftSolver 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 so can be created and edited using any text editor. An XML aware editor is recommended to allow the data to be validated against the format's schema as it is edited. Many XML editors also provide other useful features such as tag suggestion and auto-completion.

To help get started a ShiftSolver XML template file is also available.

Although instances can be created by hand 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.

Throughout this document, a number of terms such as 'shifts', 'tasks', 'scheduling period', 'index' are frequently used. The figure below shows an annotated example roster to help explain some commonly used terms. In this example there are three tasks labelled 't', 'u' and 'b' ('b' represents a break).

The data required to describe an employee scheduling problem instance can be split into five main sections:

• The planning horizon. The planning horizon (sometimes called the scheduling period) is defined using the tags <StartDate> and <EndDate>. The time interval length that each day is split up into is specified using the tag <IntervalLength> (in the example shown above the time interval is 15 minutes).
• Tasks. The tasks that can be assigned during each time interval in a schedule. These are specified within the tag <Tasks>.
• Employees. The employees available for assigning the tasks to are specified within the tag <Employees>.
• Schedule constraints. The schedules (sometimes called work patterns) that each employee can work are usually subject to a large number of constraints. For example constraints related to the min/max amount of work, shift start times and durations, breaks, night shifts etc.
  
  These constraints are entered within the tag <Contracts>. Each employee can have their own contract but it is common for employees to have the same constraints so contracts may also be shared by two or more employees.
  
  The schedule for each employee in the current planning period is clearly also affected by the employee's schedule in the previous planning period. To model this there are two options:
  
  1. Include the previous planning period (or as much of it as is relevant) in the current planning period (by making the start date earlier) and then fix all these assignments in place using <FixedAssignments> so they cannot be changed.
  2. The second option is to enter constraints (in the contracts) which are based on the assignments made in the previous schedules. For example, if a night shift can only followed by a night shift or a day off and the last day of the previous schedule has a night shift, then enter a constraint (e.g. using <Match>) in this scheduling horizon which ensures that only a night shift or day off is assigned on the first day.
  
  The second method is slightly more efficient for the solver but may be more effort to model. An effective compromise is to include some of the previous roster (fixed in place) and then add additional constraints for the ones which would require long sections of the previous schedule.
• Cover constraints. Cover constraints describe the min and max numbers of employees that must be working each day. The cover is specified per task. The cover can be further split up by skill levels or requirements for specific groups of employees.

Examples of instances modelled using the format can be found in the example instances section. See also the FAQs for examples of how to model some of the more common constraints.

The root element of the document is <SchedulingHorizon>. This is the opening tag.

<SchedulingHorizon>

The root element of the document.

Attributes

Name	Required	Type	Description
ID	Optional	string	An ID used to identify the instance.

Elements

SchedulingHorizon 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+
<IntervalLength>	Required	NonNegativeInteger	The length in minutes of the time intervals that the scheduling horizon is split into.	1.0+
<DayRanges>	Optional	DayRanges	By default each day runs from 00:00 (midnight) to 00:00 the next day. Using DayRanges the problem can be made smaller (and faster to solve) by defining a shorter time range for each day during which shifts can be assigned. For example, if it is known that shifts can only be assigned between 07:00 and 20:00 then each day can be compacted to a scheduling range of 07:00-20:00 each day using DayRanges.	1.0+
<SkillGroups>	Optional	SkillGroups	Skills can be grouped together and cover specified for different skill groups. The groups are defined here.	1.0+
<Tasks>	Optional	Tasks	The tasks to assign during a shift.	1.0+
<TaskGroups>	Optional	TaskGroups	Some constraints require task types to be grouped together (for example for cover constraints). The task groups are defined here.	1.0+
<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+
<ShiftGroups>	Optional	ShiftGroups	Some constraints require shift types to be grouped together (for example a group of night shifts). The groups 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 shifts to.	1.0+
<CoverRequirements>	Optional	CoverRequirements	The minimum and maximum numbers of employees required (and/or preferred) to cover tasks at certain times in the scheduling horizon.	1.0+
<Requests>	Optional	Requests	Employee requests for days on or off, or specific shifts on certain dates.	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+
<FixedShiftTasks>	Optional	FixedShiftTasks	Tasks which must appear at defined points and durations within a shift if a shift is assigned on the defined day to the defined employee.	1.29+

Example

<?xml version="1.0" encoding="UTF-8"?>
<SchedulingHorizon ID="DemoProblem1"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:noNamespaceSchemaLocation="SchedulingHorizon-1.0.xsd">
  <StartDate>2011-11-13</StartDate>
  <EndDate>2011-11-19</EndDate>
  
  <IntervalLength>15</IntervalLength>
  
  <Tasks>
    <Task ID="w">
      <Name>Work</Name>
      <Label>w</Label>
    </Task>
  </Tasks>
  
  <Contracts>
    <Contract ID="Contract1">
      <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>
      <Workload>
        <TimeUnits>
          <Max>
            <Count>2400</Count>
            <Label>Max 40 hours</Label>
            <Weight function="quadratic">1</Weight>
          </Max>
          <Min>
            <Count>2160</Count>
            <Label>Min 36 hours</Label>
            <Weight>1</Weight>
          </Min>
        </TimeUnits>
      </Workload>
    </Contract>
  </Contracts>
  
  <Employees>
    <Employee ID="E1">
      <ContractID>Contract1</ContractID>
      <Name>E1</Name>
    </Employee>
    <Employee ID="E2">
      <ContractID>Contract1</ContractID>
      <Name>E2</Name>
    </Employee>
  </Employees>
  
  <CoverRequirements>
    <CoverRequirement>
      <Start>2011-11-13T10:00</Start>
      <End>2011-11-13T10:15</End>
      <Cover>
        <Task>w</Task>
        <Min weight="1000">2</Min>
        <Max function="quadratic" weight="1">2</Max>
      </Cover>
    </CoverRequirement>
    <CoverRequirement>
      <Start>2011-11-13T10:15</Start>
      <End>2011-11-13T10:30</End>
      <Cover>
        <Task>w</Task>
        <Min weight="1000">2</Min>
        <Max function="quadratic" weight="1">2</Max>
      </Cover>
    </CoverRequirement>
  </CoverRequirements>

</SchedulingHorizon>

<DayRanges>

By default each day runs from 00:00 (midnight) to 00:00 the next day. Using DayRanges the problem can be made smaller (and faster to solve) by defining a shorter time range for each day during which shifts can be assigned. For example, if it is known that shifts can only be assigned between 07:00 and 20:00 then each day can be shortened to a scheduling range of 07:00-20:00 each day using DayRanges.

Note that the <StartTime> in a DayRange also affects the shift start times on that day. For example if the <StartTime> is 09:00 and the <IntervalLength> for the instance is 15 minutes then the shifts can start at 09:00, 09:15, 09:30, 09:45 etc. If however the start time was set as 09:01 then the shifts will start at 09:01, 09:16, 09:31, 09:46 etc.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more DayRange elements.

Name	Required	Type	Description
<DayRange>	Optional	DayRange	A start and end time for a day. Assignments can only be made within this time range.

Example

<DayRanges>
  <DayRange>
    <Date>2011-11-13</Date>
    <StartTime>07:00</StartTime>
    <EndTime>17:30</EndTime>
  </DayRange>
  <DayRange>
    <Date>2011-11-14</Date>
    <StartTime>07:00</StartTime>
    <EndTime>20:30</EndTime>
  </DayRange>
  <DayRange>
    <Date>2011-11-15</Date>
    <StartTime>07:00</StartTime>
    <EndTime>20:30</EndTime>
  </DayRange>
</DayRanges>

<DayRange>

A start and end time for a day. Assignments can only be made within this time range.

Parents : DayRanges

Attributes

None

Elements

DayRange contains a <Date> or <Day> element, a <StartTime> and an <EndTime> element (all optional).

If neither the <Date> or <Day> elements are used then the <StartTime> and/or <EndTime> are considered the default for all days for which there is not a DayRange specified. In other words if neither the <Date> or <Day> elements are used then it is considered a default DayRange.

Name	Required	Type	Description
<Date>	Optional	date	The date in the scheduling horizon this range applies to. Specified in the format : YYYY-MM-DD.
<Day>	Optional	NonNegativeInteger	The day in the scheduling horizon this range applies to. The scheduling horizon starts on day zero.
<StartTime>	Optional	TimeOfDay	The range start time. Default value is 00:00:00.
<EndTime>	Optional	TimeSpan	The range end time. Default value is 1.00:00:00

Example

<DayRange>
  <Date>2011-11-13</Date>
  <StartTime>07:00</StartTime>
  <EndTime>17:30</EndTime>
</DayRange>

<SkillGroups>

Skills can be placed in groups for use in cover constraints. They skill groups are defined here.

Parents : SchedulingHorizon

Attributes

None

Elements

SkillGroups contains zero or more <SkillGroup> elements.

Name	Required	Type	Description
<SkillGroup>	Optional	SkillGroup	A group of skills.

Example

<SkillGroups>
  <SkillGroup ID="AorB">
    <Skill>A</Skill>
    <Skill>B</Skill>
  </SkillGroup>
</SkillGroups>

<SkillGroup>

A group of skills.

Parents : SkillGroups

Attributes

Name	Required	Type	Description
ID	Required	ID	A unique ID for this group.

Elements

SkillGroup contains one or more <Skill> elements.

Name	Required	Type	Description
<Skill>	Required	string	A skill ID.

Example

<SkillGroup ID="123">
  <Skill>1</Skill>
  <Skill>2</Skill>
  <Skill>3</Skill>
</SkillGroup>

<Tasks>

The tasks to be assigned during shifts.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more Task elements.

Name	Required	Type	Description
<Task>	Optional	Task	A task definition.

Example

<Tasks>
  <Task ID="T1">
    <Label>1</Label>
  </Task>
  <Task ID="T2">
    <Label>2</Label>
  </Task>
  <Task ID="T3">
    <Label>3</Label>
  </Task>
</Tasks>

<Task>

A task definition.

Parents : Tasks

Attributes

Name	Required	Type	Description	Ver.
ID	Required	ID	A unique ID for this task.	1.0+

Elements

Task contains the following elements in any order:

Name	Required	Type	Description	Ver.
<Name>	Optional	string	A name for this task.	1.0+
<Label>	Optional	string	A label for the task when displaying schedules. The ID is used if this element is omitted.	1.0+
<Color>	Optional	string	A colour for the task when displaying schedules. Any valid HTML colour may be used.	1.0+
<AutoAllocate>	Optional	Boolean	If false then this task will not be assigned by the solver unless it is pre-assigned in the FixedAssignments. If this tag is omitted the default value is true.	1.0+
<Break>	Optional	Boolean	Set this as true to indicate that this task is to be used as the break task. If this tag is omitted the default value is false. If a break task is not defined then a default break task is created with the ID '$b'. Only one break task can be defined.	1.23+

Example

<Task ID="T1">
  <Name>Task1</Name>
  <Label>t</Label>
  <Color>LightBlue</Color>
</Task>

<TaskGroups>

Task types can be placed in groups which are then used in some constraints.

Parents : SchedulingHorizon

Attributes

None

Elements

TaskGroups contains zero or more <TaskGroup> elements.

Name	Required	Type	Description
<TaskGroup>	Optional	TaskGroup	A group of task types.

Example

<TaskGroups>
  <TaskGroup ID="Grp1">
    <Task>t1</Task>
    <Task>t2</Task>
  </TaskGroup>
  <TaskGroup ID="Grp2">
    <Task>t3</Task>
    <Task>t4</Task>
  </TaskGroup>
</TaskGroups>

<TaskGroup>

A group of task types.

Parents : TaskGroups

Attributes

Name	Required	Type	Description
ID	Required	ID	A unique ID for this group.

Elements

TaskGroup contains one or more <Task> elements.

Name	Required	Type	Description
<Task>	Required	string	The ID of a task type. Specified in Task attribute 'ID'.

Example

<TaskGroup ID="Grp1">
  <Task>t1</Task>
  <Task>t2</Task>
  <Task>t3</Task>
</TaskGroup>

<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.

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 : SchedulingHorizon

Attributes

None

Elements

0 or more Shift elements.

Name	Required	Type	Description
<Shift>	Optional	Shift	A shift type definition.

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>

<Shift>

A shift type definition.

Parents : ShiftTypes

Attributes

Name	Required	Type	Description
ID	Required	ID	A unique ID for this shift type.

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.33+
<MaxStart>	Optional	TimeOfDay	A shift must start before or at this time to be categorised as this shift type.	1.33+
<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.33+
<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.33+
<MinLength>	Optional	NonNegativeDouble	In minutes. A shift must be at least this length to be categorised as this shift type.	1.33+
<MaxLength>	Optional	NonNegativeDouble	In minutes. A shift must be at most this length to be categorised as this shift type.	1.33+
<EndsAfter>	Optional	TimeSpan	This element is obsolete. It is recommended to use <MinStart>, <MaxStart>, <MinEnd> and <MaxEnd> instead for more control. If a shift starts before or at this time and ends after this time it will 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+

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>

<Resources>

Resources contains resource ID's and numerical values. Resource values may also be specified to be used only on certain days in the planning period.

Parents : Shift

Attributes

None

Elements

Resources contains zero or more <Resource> elements.

Name	Required	Type	Description	Ver.
<Resource>	Optional	Resource	A resource ID and quantity.	1.47+.

Example

<Shift ID="D1">
  <Resources>
   <Resource ID="ShiftUnits">2</Resource>
   <Resource ID="TimeUnits">10</Resource>
  </Resources>
</Shift>

<Resource>

Resource contains an ID attribute and a NonNegativeDouble value. A resource value may also be specified to be used only on certain days in the planning period using the attributes below. If none of these attributes are used then the resource value applies to all days in the planning period.

Parents : Resources

Attributes

Name	Required	Type	Description	Ver.
ID	Required	string	The ID for the resource.	1.47+
Day	Optional	NonNegativeInteger	If this attribute is used then the value specified for this resource only applies on this day in the planning period (the first day is day zero).	1.47+
Date	Optional	Date	If this attribute is used then the value specified for this resource only applies on this date in the planning period. Specified in the format : YYYY-MM-DD.	1.47+
DayOfWeek	Optional	string	If this attribute is used then the value specified for this resource only applies on these days of the week, in the planning period. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.	1.47+

Element

Each <Resource> element is a NonNegativeDouble defining the quantity/value for this resource.

Name	Required	Type	Description	Ver.
<Resource>	Optional	NonNegativeDouble	A quantity/value for the specified resource ID.	1.47+

Example

<Shift ID="D1">
  <Resources>
   <Resource ID="TimeUnits">8</Resource>
   <Resource ID="TimeUnits" DayOfWeek="Monday">12</Resource>
   <Resource ID="R1" Date="2010-09-14">100</Resource>
   <Resource ID="R1" Date="2010-09-15">100</Resource>
   <Resource ID="R1" Date="2010-09-16">100</Resource>
  </Resources>
</Shift>

<ShiftGroups>

Shift types can be placed in groups which are used in some constraints.

Parents : SchedulingHorizon

Attributes

None

Elements

ShiftGroups contains zero or more <ShiftGroup> elements.

Name	Required	Type	Description
<ShiftGroup>	Optional	ShiftGroup	A group of shift types.

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>

<ShiftGroup>

A group of shift types.

Parents : ShiftGroups

Attributes

Name	Required	Type	Description
ID	Required	ID	A unique ID for this group.

Elements

ShiftGroup contains one or more <Shift> elements.

Name	Required	Type	Description
<Shift>	Required	string	The ID of a shift type. Specified in Shift attribute 'ID'.

Example

<ShiftGroup ID="EN">
  <Shift>E</Shift>
  <Shift>N</Shift>
</ShiftGroup>

<Contracts>

Contracts contain the constraints on the employees' work schedules.

Parents : SchedulingHorizon

Attributes

None

Elements

Contracts contains zero or more <Contract> elements.

Name	Required	Type	Description
<Contract>	Optional	Contract	Contains the working preferences and requirements (constraints) for each employee with this contract.

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>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract. Since version 1.36 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
ID	Required	ID	A unique ID for this contract.

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+
<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.52+
<ShiftLengths>	Optional	ShiftLengths	Minimum and maximum shift lengths (optionally for each day).	1.0+
<TaskLengths>	Optional	TaskLengths	Minimum and maximum amount of time the employee can work consecutively on a single task.	1.0+
<BreakDefinitions>	Optional	BreakDefinitions	The number of, length of and position of breaks. How many, how long and where the breaks should be positioned can be specified according to the shift length, shift start time and shift end time.	1.0+
<Workload>	Optional	Workload	Minimum and maximum total working time between any two dates in the planning period.	1.0+
<AllowTaskTransfers>	Optional	Boolean	If false then the employee will only be assigned one task type during a shift (apart from breaks), that is, they will not transfer between tasks during a shift. If this tag is omitted the default value is true, that is, by default tasks transfers are allowed during a shift.	1.9+
<SplitShifts>	Optional	SplitShifts	If this is used then split-shifts can be assigned to the employee. Split-shifts are shifts which have durations where the employee is not at work. For example an employee may work from 09:00-12:00 then go home for five hours and then return to complete the shift from 17:00-22:00.	1.16+
<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.36+
<MinRestTime>	Optional	NonNegativeDouble	The minimum amount of rest time (non-work time) required between shifts. The time is in minutes. This is a hard constraint.	1.37+
<MinRestInPeriod>	Optional	MinRestInPeriod	A minimum amount of consecutive rest required within a defined period.	1.59+
<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.37+
<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.37+
<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.37+
<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.37+
<FixedDependentTasks>	Optional	FixedDependentTasks	FixedDependentTasks are tasks which are added to the end of any assignment of a specific task. For example, there may be a task such as a Cashier that must always have a 15 minute Cashing-up task immediately afterwards. This constraint is a hard constraint and will always be satisfied in a solution	1.72+
<Sequence>	Optional	Sequence	A flexible constraint which can model a variety of rules on an employee's work schedule.	2.0+

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>
  <TaskLengths>
    <Min>
      <Task>T1</Task>
      <Length>60</Length>
      <Label>Min 60 consecutive mins of task T1</Label>
      <Weight>10</Weight>
    </Min>
    <Min>
      <Task>T2</Task>
      <Length>60</Length>
      <Label>Min 60 consecutive mins of task T2</Label>
      <Weight>10</Weight>
    </Min>
  </TaskLengths>
  <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>
  <BreakDefinitions>
    <BreakDefinition>
      <MinShiftLength>270</MinShiftLength>
      <MaxShiftLength>480</MaxShiftLength>
      <MinWorkLength>120</MinWorkLength>
      <MaxWorkLength>300</MaxWorkLength>
      <Break>
        <Length>30</Length>
      </Break>
    </BreakDefinition>
    <BreakDefinition>
      <MinShiftLength>495</MinShiftLength>
      <MaxShiftLength>720</MaxShiftLength>
      <MinWorkLength>120</MinWorkLength>
      <MaxWorkLength>360</MaxWorkLength>
      <Break>
        <Length>30</Length>
      </Break>
      <Break>
        <Length>30</Length>
      </Break>
    </BreakDefinition>
  </BreakDefinitions>
  <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>

<FixedDependentTasks>

FixedDependentTasks are tasks which are added to the end of any assignment of a specific task. For example, there may be a task such as a Cashier that must always have a 15 minute Cashing-up task immediately afterwards. This constraint is a hard constraint and will always be satisfied in a solution.

See also the DependentTasks constraint. DependentTasks differs by being a weighted soft constraint. Using DependentTasks, the dependent task can also be required before or following a defined task, but the dependent task will only ever be inserted at the start or end of a shift. Whereas using FixedDependentTasks the dependent task will only be inserted after a defined task but after every period of the dependent task. DependentTasks is useful for modelling scenarios such as including traveling times to specific work locations

Parents : Contract

Attributes

None

Elements

FixedDependentTasks contains zero or more <Task> elements.

Name	Required	Type	Description	Ver.
<Task>	Required	Task	A dependent task.	1.72+

Example

<FixedDependentTasks>
  <Task taskID="cashier" taskIDAfter="cashingup" durationAfter="15"/>
  <Task taskID="task1" taskIDAfter="task2" durationAfter="30"/>
</FixedDependentTasks>

<Task>

FixedDependentTasks are tasks which are added to the end of any assignment of a specific task. For example, there may be a task such as a Cashier that must always have a 15 minute Cashing-up task immediately afterwards. This constraint is a hard constraint and will always be satisfied in a solution.

Parents : FixedDependentTasks

Attributes

Name	Required	Type	Description	Ver.
taskID	Required	ID	The ID of the task with dependent tasks. This cannot be the break task.	1.72+
taskIDAfter	Required	string	The ID of the task that will be added after this task. The ID is used to identify the dependent task in the solution XML.	1.72+
durationAfter	Required	NonNegativeInteger	The length of time in minutes of the dependent task after this task.	1.72+

Example

<FixedDependentTasks>
  <Task taskID="cashier" taskIDAfter="cashingup" durationAfter="15"/>
  <Task taskID="task1" taskIDAfter="task2" durationAfter="30"/>
</FixedDependentTasks>

<ShiftStartTimes>

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>, <Max> and/or <Range> elements (in any order).

Name	Required	Type	Description	Ver.
<Min>	Optional	Min	The earliest a shift can start (soft constraint).	1.0+
<Max>	Optional	Max	The latest a shift can start (soft constraint).	1.0+
<Range>	Optional	Range	The earliest and/or latest a shift can start (hard constraint). If more than one <Range> elements are present then shifts can start within any of the Ranges defined.	1.35+

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>

<Min>

The earliest a shift can start.

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
<Time>	Required	TimeOfDay	The earliest start time.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Min>
  <Time>07:00</Time>
  <Label>Shift must start after 7am</Label>
  <Weight>10</Weight>
</Min>

<Max>

The latest a shift can start.

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
<Time>	Required	TimeOfDay	The latest start time.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Max>
  <Time>12:00</Time>
  <Label>The latest the shift can start is 12pm</Label>
  <Weight>10</Weight>
</Max>

<Range>

The earliest and/or latest a shift can start. This is a hard constraint. If more than one Range are defined then a shift can start within any of the defined Ranges.

Parents : ShiftStartTimes

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. If neither the date attribute nor the day attribute are used then the constraint applies to every day in the planning horizon.	1.35+
day	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. If neither the date attribute nor the day attribute are used then the constraint applies to every day in the planning horizon.	1.35+

Elements

Range contains in any order a <Min> and a <Max> element (both optional).

Name	Required	Type	Description	Ver.
<Min>	Optional	TimeOfDay	The earliest start time.	1.35+
<Max>	Optional	TimeOfDay	The latest start time.	1.35+

Example

<Range>
  <Min>07:00</Min>
  <Max>09:00</Max>
</Range>

<ShiftEndTimes>

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>, <Max> and/or <Range> elements (in any order).

Name	Required	Type	Description	Ver.
<Min>	Optional	Min	The earliest a shift can end (soft constraint).	1.0+
<Max>	Optional	Max	The latest a shift can end (soft constraint).	1.0+
<Range>	Optional	Range	The earliest and/or latest a shift can end (hard constraint). If more than one <Range> elements are present then shifts can end within any of the Ranges defined.	1.35+

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>

<Min>

The earliest a shift can finish.

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
<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.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<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).
<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).

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>

<Max>

The latest a shift can finish.

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
<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.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<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).
<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).

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>

<Range>

The earliest and/or latest a shift can finish. This is a hard constraint. If more than one Range are defined then a shift can finish within any of the defined Ranges.

Parents : ShiftEndTimes

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 attribute nor the day attribute are used then the constraint applies to every day in the planning horizon.	1.35+
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 attribute nor the day attribute are used then the constraint applies to every day in the planning horizon.	1.35+

Elements

Range contains in any order a <Min> and a <Max> element (both optional).

Name	Required	Type	Description	Ver.
<Min>	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.35+
<Max>	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.35+

Example

<Range>
  <Min>22:00</Min>
  <Max>1.02:00</Max>
</Range>

<ShiftStartEndTimes>

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.52+

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>

<Shift>

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.52+
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.52+
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.68+
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.68+

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.52+
<MaxStart>	Optional	TimeOfDay	The latest start time.	1.52+
<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.52+
<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.52+

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>

<ShiftLengths>

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
<Min>	Optional	Min	The minimum shift length.
<Max>	Optional	Max	The maximum shift length.

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>

<Min>

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.

The <Length> element can optionally have an attribute units to indicate whether the constraint is for the shift's length measured as the difference in minutes between the shift's start and finish time or its length measured as the actual amount of time considered as work. For example it is possible to specify that some breaks should not be counted as work time (see Break).

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
<Length>	Required	NonNegativeDouble	The minimum shift length in minutes. Length can optionally also have an attribute : units which can have the value "ShiftLength", or "WorkTime" (case-insensitive). The default value is "WorkTime" if the attribute is not used.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Min>
  <Length units="ShiftLength">480</Length>
  <Label>Shift must not be less than 8h</Label>
  <Weight function="quadratic">100</Weight>
</Min>

<Max>

A maximum 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 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.

The <Length> element can optionally have an attribute units to indicate whether the constraint is for the shift's length measured as the difference in minutes between the shift's start and finish time or its length measured as the actual amount of time considered as work. For example it is possible to specify that some breaks should not be counted as work time (see Breaks).

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
<Length>	Required	NonNegativeDouble	The maximum shift length in minutes. Length can optionally also have an attribute : units which can have the value "ShiftLength", or "WorkTime" (case-insensitive). The default value is "WorkTime" if the attribute is not used.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Max>
  <Length units="ShiftLength">720</Length>
  <Label>Shifts must be less than 12h</Label>
  <Weight function="quadratic">100</Weight>
</Max>

<TaskLengths>

Minimum and maximum amount of time the employee can work consecutively on a single task.

Parents : Contract

Attributes

None

Elements

TaskLengths contains zero or more <Min> and/or a <Max> elements (in any order).

Name	Required	Type	Description
<Min>	Optional	Min	The minimum length of a consecutive sequence of task assignments of the same type.
<Max>	Optional	Max	The maximum length of a consecutive sequence of task assignments of the same type.

Example

<TaskLengths>
  <Min>
    <Task>T1</Task>
    <Length>60</Length>
    <Label>Min 60 consecutive mins of task T1</Label>
    <Weight>10</Weight>
  </Min>
  <Min>
    <Task>T2</Task>
    <Length>60</Length>
    <Label>Min 60 consecutive mins of task T2</Label>
    <Weight>10</Weight>
  </Min>
</TaskLengths>

<Min>

A minimum length of a consecutive sequence of task assignments.

The <Weight> element can optionally have an attribute function to indicate how to calculate the penalty function value. For example if a consecutive sequence of task assignments 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 task sequence length and the minimum 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 : TaskLengths

Attributes

None

Elements

Min contains in any order a <Task>, <Length> and <Weight> element (all 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 task length constraint for that day).

Name	Required	Type	Description
<Task>	Required	string	The task this constraint applies to. The task is specified using a ID defined in Tasks
<Length>	Required	NonNegativeDouble	The minimum sequence length in minutes.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Min>
  <Task>T1</Task>
  <Length>60</Length>
  <Label>Min 60 consecutive mins of task T1</Label>
  <Weight>10</Weight>
</Min>

<Max>

A maximum length of a consecutive sequence of task assignments.

The <Weight> element can optionally have an attribute function to indicate how to calculate the penalty function value. For example if a consecutive sequence of task assignments 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 task sequence length and the maximum 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 : TaskLengths

Attributes

None

Elements

Max contains in any order a <Task>, <Length> and <Weight> element (all 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 maximum task length constraint for that day).

Name	Required	Type	Description
<Task>	Required	string	The task this constraint applies to. The task is specified using a ID defined in Tasks
<Length>	Required	NonNegativeDouble	The maximum sequence length in minutes.
<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.
<Label>	Optional	string	A label for the constraint used when displaying a solution.
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero.
<Date>	Optional	date	The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD.

Example

<Max>
  <Task>T1</Task>
  <Length>180</Length>
  <Label>Max 180 consecutive mins of task T1</Label>
  <Weight>10</Weight>
</Max>

<SplitShifts>

If <SplitShifts> is used then split-shifts can be assigned to the employee. Split-shifts are shifts which have durations where the employee is not at work. For example an employee may work from 09:00-12:00 then go home for five hours and then return to complete the shift from 17:00-22:00.

For all the constraints except BreakDefinitions, split-shifts are treated as normal, non-split-shifts. The start time is considered as the start time of the first shift and the end time is the end time of the last shift within the split-shift. Time during the split-shift where the employee is not assigned a task or break (i.e. where the employee is not at work) is not counted as work time. BreakDefinition rules are applied to each shift within the split-shift.

Parents : Contract

Attributes

None

Elements

SplitShifts contains the following elements in any order (all optional) : <MinShiftLength>, <MaxShiftLength>, <MinSplitLength>, <MaxSplitLength>.

Name	Required	Type	Description	Ver.
<MinShiftLength>	Optional	NonNegativeDouble	The minimum length (in minutes) of each shift within the split-shift.	1.16+
<MaxShiftLength>	Optional	NonNegativeDouble	The maximum length (in minutes) of each shift within the split-shift.	1.16+
<MinSplitLength>	Optional	NonNegativeDouble	The minimum length of time (in minutes) between shifts in the split-shift.	1.16+
<MaxSplitLength>	Optional	NonNegativeDouble	The maximum length of time (in minutes) between shifts in the split-shift.	1.16+

Example

<SplitShifts>
  <MinShiftLength>120</MinShiftLength>
  <MaxShiftLength>480</MaxShiftLength>
  <MinSplitLength>180</MinSplitLength>
  <MaxSplitLength>300</MaxSplitLength>
</SplitShifts>

<UseIfNeeded>

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.

Internally it creates a sequence constraint to say no shifts should be assigned to this employee with a 'constant' penalty function. However, the constant function will mean that if a shift is assigned to the employee then the penalty will only increase by the weight no matter how many shifts are assigned to the employee. For example if the weight is 1000 and the employee has one shift then the penalty will be 1000, if two shifts then still only 1000, if three shifts then still only 1000 and so on. The effect of this is that this employee will only be used if it decreases the overall penalty by more than this weight. For example, if there is a minimum cover constraint with a weight of 1000 and which is not satisfied by 1 (i.e. 1 more employee is required at that time) then there will be a penalty of 1000. If this employee is not used and the weight is less than 1000 then this employee will then be assigned a shift to satisfy the cover constraint and improve the overall solution penalty.

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.36+
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.36+
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.36+
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.36+
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.36+
label	Optional	string	A label for the constraint. The label is only used in visualisations such as RosterViewer.	1.36+
shiftGroup	Optional	string	If this is used then the employee will only be considered as being scheduled if they receive one or more shifts from this group. For example, if there was a 'vacation' shift and the shift group did not include the 'vacation' shift then the employee would not be considered as being scheduled if they had only 'vacation' shifts. The ID is defined in ShiftGroups. Since version 1.42 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.36+
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. The ID is defined in ShiftTypes. Since version 1.42 it is also possible to specify a shift group as a co-arated list of ShiftType ID's (e.g. "E,D,L,N").	1.36+

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.37+
weight	Required	NonNegativeDouble	The weight for the constraint.	1.37+
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.37+
shift	Optional	string	Indicates whether the constraint applies to days on, days off or specific shifts. Possible values are : $     Working days (a day with a shift starting on it). -     Days off (a day without a shift starting on it). A shift ID     Specified using an ID defined in ShiftTypes. A shift group ID     Specified using an ID defined in ShiftGroups. Since version 1.39 it is also possible to specify a shift group as a comma-separated list of shift ID's (e.g. "E,D,L,N").	1.37+
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.37+
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.37+
label	Optional	string	A label for the constraint. The label is only used in visualisations such as RosterViewer.	1.37+

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"/>

<BreakDefinitions>

Breaks are added to shifts based on the properties of the shift such as its shift type, start time, finish time and length. A BreakDefinition contains a set of these properties and one or more break positions and lengths. If a shift assigned to an employee matches the shift properties defined in a BreakDefinition then it must also contain breaks according to the positions and break lengths also defined.
For example a break definition could be: "If a shift is between eight and twelve hours long then there should be two thirty minute breaks and the employee should not work less than two hours or more than four hours without a break". Or alternatively: "If a shift is a night shift then there should be a fifteen minute break followed by a thirty minute break followed by a fifteen minute break and the employee should not work more than two hours without a break". The breaks can also be restricted to be taken within specified time windows within the shift.

Parents : Contract

Attributes

None

Elements

BreakDefinitions contains zero or more <BreakDefinition> elements.

Name	Required	Type	Description	Ver.
<BreakDefinition>	Optional	BreakDefinition	If a shift matches the properties defined within a BreakDefinition then it must also contain the break(s) defined within.	1.0+

Example

<BreakDefinitions>
  <BreakDefinition>
    <MinShiftLength>270</MinShiftLength>
    <MaxShiftLength>480</MaxShiftLength>
    <MinWorkLength>120</MinWorkLength>
    <MaxWorkLength>300</MaxWorkLength>
    <Break>
      <Length>30</Length>
    </Break>
  </BreakDefinition>
  <BreakDefinition>
    <MinShiftLength>495</MinShiftLength>
    <MaxShiftLength>720</MaxShiftLength>
    <MinWorkLength>120</MinWorkLength>
    <MaxWorkLength>360</MaxWorkLength>
    <Break>
      <Length>30</Length>
    </Break>
    <Break>
      <Length>30</Length>
    </Break>
  </BreakDefinition>
</BreakDefinitions>

<BreakDefinition>

If a shift matches the properties defined within a BreakDefinition then it must also contain the break(s) defined within. A shift can be matched by its shift type, start time, end time and length.

Parents : BreakDefinitions

Attributes

Name	Required	Type	Description	Ver.
ID	Optional	string	An ID that can be used to identify this break definition in shifts in the solution XML. If this attribute is used then in the solution XML returned by the engine all shifts which use this break rule will have this value in their BreakDefID attribute (see the Solution documentation).	1.51+

Elements

BreakDefinition contains in any order <MinShiftLength>, <MaxShiftLength>, <MinShiftStart>, <MaxShiftStart>, <MinShiftEnd>, <MaxShiftEnd>, <MinWorkLength>, <MaxWorkLength>, <Shift>, <DayIndex> and <Date> elements (all optional) and zero or more <Break> elements.

Name	Required	Type	Description	Ver.
<MinShiftLength>	Optional	NonNegativeDouble	The minimum shift length in minutes. The shift's length must be greater than or equal to this value.	1.0+
<MaxShiftLength>	Optional	NonNegativeDouble	The maximum shift length in minutes. The shift's length must be less than or equal to this value.	1.0+
<MinShiftStart>	Optional	TimeSpan	The shift must start at or after this time.	1.0+
<MaxShiftStart>	Optional	TimeSpan	The shift must start at or before this time.	1.0+
<MinShiftEnd>	Optional	TimeSpan	The shift must finish at or after this time. For shifts which finish on the next day or later use the day prefix for the 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+
<MaxShiftEnd>	Optional	TimeSpan	The shift must finish at or before this time. For shifts which finish on the next day or later use the day prefix for the 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+
<Shift>	Optional	string	A shift type ID defined in <ShiftTypes>. The shift must match this shift type. Since version 1.35 more than one <Shift> tag is allowed here, meaning that the shift must match at least one of the shift types defined.	1.33+
<MinWorkLength>	Optional	NonNegativeDouble	The minimum length of work in minutes that can be assigned before a break or the end of the shift.	1.0+
<MaxWorkLength>	Optional	NonNegativeDouble	The maximum length of work in minutes that can be assigned without a break.	1.0+
<DayIndex>	Optional	NonNegativeInteger	The day in the scheduling horizon that this break definition applies to. The first day in the scheduling horizon is day zero. If neither <DayIndex> or <Date> is used then this break definition applies to every day in the scheduling horizon.	1.0+
<Date>	Optional	date	The day in the scheduling horizon that this break definition applies to. Specified in the format : YYYY-MM-DD. If neither <DayIndex> or <Date> is used then this break definition applies to every day in the scheduling horizon.	1.0+
<Break>	Optional	Break	A break length optionally with a time window within which it must be placed. The breaks within the shift are placed in the order they are defined in the XML. For example if the XML lists a 15 minute break followed by a 30 minute break followed by a 15 minute break then the breaks will be placed in the shift in that order (15, 30, 15).	1.0+

Example

<BreakDefinition>
  <MinWorkLength>120</MinWorkLength>
  <MaxWorkLength>210</MaxWorkLength>
  <Break>
    <Length>15</Length>
  </Break>
  <Break>
    <Length>15</Length>
  </Break>
</BreakDefinition>

<Break>

A break to fit within a shift.

For some constraints it is necessary to know whether a break should count as work or not. If a break should not count as work use the <WorkLength> element with a value of zero to indicate that the break should not be counted as work.

Parents : BreakDefinition

Attributes

None

Elements

Break contains in any order <Length> (required) and <MinStart>, <MaxEnd>, <WorkLength>, <MinWorkBefore>, <MaxWorkBefore>, <MinWorkAfter> and <MaxWorkAfter> (all optional) elements.

Name	Required	Type	Description	Ver.
<Length>	Required	PositiveDouble	The break's length in minutes. If the length is less than (or not a multiple) of the problem's IntervalLength then the length is rounded upwards to the nearest whole multiple of the interval length.	1.0+
<MinStart>	Optional	TimeSpan	The break must start at or after this time. For shifts which finish on the next day or later use the day prefix for the 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 break must finish at or before this time. For shifts which finish on the next day or later use the day prefix for the 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+
<WorkLength>	Optional	NonNegativeDouble	The amount of time in minutes to count this break as work. If this tag is omitted then the WorkLength is assumed to be the same as the break's length (i.e. the break counts as work).	1.0+
<MinWorkBefore>	Optional	NonNegativeDouble	The minimum length of work in minutes that must be assigned before the break. In other words, the employee must work at least this length of time before the break. If this tag is not used and there is no previous break with a MinWorkAfter constraint then the <MinWorkLength> in the parent <BreakDefinition> is used instead.	1.42+
<MaxWorkBefore>	Optional	NonNegativeDouble	The maximum length of work in minutes that can be assigned before the break. In other words, the employee must work no longer than this length of time before the break. If this tag is not used and there is no previous break with a MaxWorkAfter constraint then the <MaxWorkLength> in the parent <BreakDefinition> is used instead.	1.42+
<MinWorkAfter>	Optional	NonNegativeDouble	The minimum length of work in minutes that must be assigned after the break. In other words, the employee must work at least this length of time after the break. If this tag is not used and there is no following break with a MinWorkBefore constraint then the <MinWorkLength> in the parent <BreakDefinition> is used instead.	1.42+
<MaxWorkAfter>	Optional	NonNegativeDouble	The maximum length of work in minutes that can be assigned after the break. In other words, the employee must work no longer than this length of time after the break. If this tag is not used and there is no following break with a MaxWorkBefore constraint then the <MaxWorkLength> in the parent <BreakDefinition> is used instead.	1.42+

Example

<Break>
  <Length>30</Length>
</Break>

<Workload>

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
<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.

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>

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 index 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.	2.0+
<Max>	Optional	Max	The maximum number of minutes worked.	2.0+
<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.	2.0+
<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.	2.0+

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>

<Min>

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.

The <Count> element can optionally have an attribute units to indicate whether the constraint should measure workload as the total shifts' lengths measured as the difference in minutes between shift start and finish times or shifts' lengths measured as the actual amount of time considered as work. For example it is possible to specify that some breaks should not be counted as work time (see Break).

Parents : TimeUnits

Attributes

None

Elements

Min contains the following elements in any order.

Name	Required	Type	Description
<Count>	Required	NonNegativeDouble	The minimum number of minutes to work. Count can optionally also have an attribute : units which can have the value "ShiftLength", or "WorkTime" (case-insensitive). The default value is "WorkTime" if the attribute is not used. Count can also have an optional attribute : byShiftEndTime which can have the boolean value "true", or "false" (version 1.56+). If this attribute is used and the value is set to "true" then a shift is only included in the workload for a time-window (defined by PeriodStart and PeriodEnd) if the shift ends within the window. If this attribute is not used, then by default, all shifts which start within a window are included, even if they finish outside the window.
<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.
<Label>	Optional	string	A label for the constraint for when displaying a solution.

Example

<Min>
  <Count>2100</Count>
  <Label>Min 2100 mins per week</Label>
  <Weight>100</Weight>
</Min>

<Max>

A maximum 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 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.

The <Count> element can optionally have an attribute units to indicate whether the constraint should measure workload as the total shifts' lengths measured as the difference in minutes between shift start and finish times or shifts' lengths measured as the actual amount of time considered as work. For example it is possible to specify that some breaks should not be counted as work time (see Break).

Parents : TimeUnits

Attributes

None

Elements

Max contains the following elements in any order.

Name	Required	Type	Description
<Count>	Required	NonNegativeDouble	The maximum number of minutes to work. Count can optionally also have an attribute : units which can have the value "ShiftLength", or "WorkTime" (case-insensitive). The default value is "WorkTime" if the attribute is not used. Count can also have an optional attribute : byShiftEndTime which can have the boolean value "true", or "false" (version 1.56+). If this attribute is used and the value is set to "true" then a shift is only included in the workload for a time-window (defined by PeriodStart and PeriodEnd) if the shift ends within the window. If this attribute is not used, then by default, all shifts which start within a window are included, even if they finish outside the window.
<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.
<Label>	Optional	string	A label for the constraint for when displaying a solution.

Example

<Max>
  <Count>2250</Count>
  <Label>Max 37.5 hours</Label>
  <Weight>1</Weight>
</Max>

<MinRestInPeriod>

A minimum amount of consecutive rest required within a defined period.

Parents : Contract

Attributes

Name	Required	Type	Description	Ver.
start	Required	DateTime	The start of the period the rest is required in.	1.59+
end	Required	DateTime	The end of the period the rest is required in.	1.59+
weight	Required	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.59+
label	optional	string	A label for the constraint when displaying a solution.	1.59+
splitShiftRest	optional	Boolean	If true then the time between split-shifts is considered as rest. False if omitted.	1.59+

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>

<Sequence>

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 shifts 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 specific shift type
• Any shift type
• A day off (a day without a shift)
• Anything (any shift type or a day off)
• One of a group of shift types
• Not a shift type
• Not one of a group of shift types

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).	2.0+
<Max>	Optional	Max	The maximum number matches of the pattern(s).	2.0+
<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.	2.0+
<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.	2.0+
<Pattern>	Required	Pattern	A a sequences of shift types and/or days off.	2.0+

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>

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.	2.0+
<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.	2.0+
<Shift>	Optional	string	Possible values are : A shift ID   Match this shift. The shift is specified using an ID defined in ShiftTypes. $   Match any shift (but not a day off). -   Match a day off. *   Match any shift or a day off. It is also possible to specify a shift group as a comma-separated list of shift ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID.	2.0+
<NotShift>	Optional	string	Match anything but this shift (including a day without a shift). The shift is specified using an ID defined in ShiftTypes. It is also possible to specify a shift group as a comma-separated list of shift ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID, meaning match anything but one of the shifts in this group of shifts (including a day without a shift).	2.0+

Example

<Sequence> 
  <Max count="3" weight="1000" label="Max 3 working Sundays"/>
  <Pattern>
    <Start>Sunday</Start>
    <Shift>$</Shift>
  </Pattern>
</Sequence>

<Min>, <Max>

Specifies a minimum or maximum value for a constraint.

Parents : Sequence

Attributes

Name	Required	Type	Description	Ver.
count	Required	NonNegativeInteger	The maximum or minimum.	2.0+
weight	Required	NonNegativeDouble	The weight for the constraint.	2.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.	2.0+
label	Optional	string	A label for the constraint. The label is only used in visualisations such as RosterViewer.	2.0+

Example

<Min count="1" weight="1000" label="Min 1..."/>

<Max count="0" weight="1000" label="Max 0..." function="quadratic"/>

<Employees>

The employees.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more Employee elements.

Name	Required	Type	Description
<Employee>	Required	Employee	An employee.

Example

<Employees>
  <Employee ID="E1">
    <ContractID>ContractA</ContractID>
  </Employee>
  <Employee ID="E2">
    <ContractID>ContractB</ContractID>
  </Employee>
  <Employee ID="E3">
    <ContractID>ContractB</ContractID>
  </Employee>
</Employees>

<Employee>

An employee in the roster.

Parents : Employees

Attributes

Name	Required	Type	Description
ID	Required	ID	A unique ID for this employee.

Elements

Employee contains the following elements in any order.
Since version 1.36, 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. Since version 1.36 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+
<ValidTasks>	Optional	ValidTasks	The tasks which can be assigned to the employee. If this element is omitted then the employee can be assigned any task. If this element is used then only the tasks listed can be assigned to this employee. To model the situation where an employee can be assigned a task but would prefer not to be assigned that task use the weight attribute for the <Task> element.	1.0+
<ValidTaskTransfers>	Optional	ValidTaskTransfers	If an employee can be assigned more than one task type in a single shift (i.e. the employee can transfer to another task during the task) then the combinations of tasks that can make up a single shift are defined here. If this tag as omitted then the employee can transfer between any tasks during the shift. (To not allow any task transfers use the <AllowTaskTransfers> tag in <Contract>).	1.9+
<DependentTasks>	Optional	DependentTasks	These are tasks which must be added to an employee's shift if another defined task is assigned in the shift. It can be used to model tasks which contribute towards working hours but for which there is no demand. For example, to include traveling times to specific work locations.	1.67+
<Skills>	Optional	Skills	The skills, qualifications, experience, training, group etc this employee has/belongs to.	1.0+

Example

<Employee ID="E1">
  <ContractID>C1</ContractID>
  <ContractID>C2</ContractID>
  <ValidTasks>
    <Task>T1</Task>
    <Task weight="1">T2</Task>
  </ValidTasks>
</Employee>

<ValidTasks>

The tasks which can be assigned to the employee. If this element is omitted then the employee can be assigned any task. If this element is used then only the tasks listed can be assigned to this employee. To model the situation where an employee can be assigned a task but would prefer not to be assigned that task use the weight attribute for the <Task> element.

Parents : Employee

Attributes

None

Elements

ValidTasks contains one or more <Task> elements.

Name	Required	Type	Description
<Task>	Optional	string	A task ID. Task can optionally also have an attribute : weight which has a value of type NonNegativeDouble. If this attribute is used then the employee can be assigned the task but the solution's penalty will be increased by the number of minutes the employee works this task multiplied by the weight. Task can also have an attribute : function which can have the value 'Linear' or 'Quadratic' (case-insensitive). If 'Linear' is used then the solution's penalty will be increased by the number of minutes the employee works this task multiplied by the weight. If 'Quadratic' is used then the solution's penalty will be increased by number of minutes the employee works this task squared and then multiplied by the weight. The default value is 'Linear' if the function attribute is not used.

Example

<ValidTasks>
  <Task>T1</Task>
  <Task weight="1">T2</Task>
</ValidTasks>

<ValidTaskTransfers>

If an employee can be assigned more than one task type in a single shift (i.e. the employee can transfer to another task during the task) then the combinations of tasks that can make up a single shift are defined here. If this tag as omitted then the employee can transfer between any tasks during the shift.
(To not allow any task transfers use the <AllowTaskTransfers> tag in <Contract>).

Parents : Employee

Attributes

None

Elements

ValidTaskTransfers contains zero or more <TaskGroup> elements.

Name	Required	Type	Description
<TaskGroup>	Optional	TaskGroup	A group of two or more tasks which may be assigned during a single shift (i.e. during a single shift the employee can transfer between any of the tasks in this group).

Example

<ValidTaskTransfers>
  <TaskGroup>
    <Task>Task1</Task>
    <Task>Task2</Task>
    <Task>Task3</Task>
  </TaskGroup>
  <TaskGroup>
    <Task>Task4</Task>
    <Task>Task5</Task>
    <Task>Task6</Task>
  </TaskGroup>
</ValidTaskTransfers>

<TaskGroup>

A group of two or more tasks which may be assigned during a single shift (i.e. during a single shift the employee can transfer between any of the tasks in this group).

Parents : ValidTaskTransfers

Attributes

None

Elements

TaskGroup contains one or more <Task> elements.

Name	Required	Type	Description
<Task>	Required	string	The ID of a Task. Specified in Task attribute 'ID'.

Example

<TaskGroup>
  <Task>Task1</Task>
  <Task>Task2</Task>
  <Task>Task3</Task>
</TaskGroup>

<DependentTasks>

These are tasks which must be added to an employee's shift if another defined task is assigned in the shift. It can be used to model tasks which contribute towards working hours but for which there is no demand. For example, to include traveling times to specific work locations.
The dependent tasks are added only at the start or end of a shift. This means that tasks that have dependent tasks will only have the dependent tasks added if the task is at the start of the shift and has a dependent task before it, or if the task is at the end of a shift and has a dependent task after it.
DependentTasks are not applied to fixed shifts. Dependent tasks are included when calculating shift start and end times for all constraints except the ShiftLengths constraint and the Workload constraint when the unit attribute is set as ShiftLength. Dependent tasks added to shifts are also ignored when classifying ShiftTypes by start time, end time and/or length.

See also FixedDependentTasks. FixedDependentTasks differs by being a hard constraint and the dependent task will only be inserted following the defined task. It will also be inserted after every period of the defined task and not just at the end of the shift as in DependentTasks. FixedDependentTasks are useful for modelling scenarios such as when there is a Cashier task that must always have a 15-minute Cashing-up task immediately afterwards.

Parents : Employee

Attributes

None

Elements

DependentTasks contains zero or more <Task> elements.

Name	Required	Type	Description	Ver.
<Task>	Required	Task	A dependent task.	1.67+

Example

<DependentTasks>
  
  <Task taskID="task1" taskIDBefore="preTask1" taskIDAfter="postTask1" 
        durationBefore="45" durationAfter="30" weight="10"/>
  
  <Task taskID="task2" taskIDBefore="preTask2" taskIDAfter="postTask2" 
        durationBefore="20" durationAfter="0" weight="10"/>
        
  <Task taskID="task3" taskIDBefore="preTask2" durationBefore="20" weight="10"/>
  
</DependentTasks>

<Task>

These are tasks which must be added to an employee's shift if another defined task is assigned in the shift. It can be used to model tasks which contribute towards working hours but for which there is no demand. For example, to include traveling times to specific work locations.
The dependent tasks are added only at the start or end of a shift. This means that tasks that have dependent tasks will only have the dependent tasks added if the task is at the start of the shift and has a dependent task before it, or if the task is at the end of a shift and has a dependent task after it.
DependentTasks are not applied to fixed shifts.

Parents : DependentTasks

Attributes

Name	Required	Type	Description	Ver.
taskID	Required	ID	The ID of the task with dependent tasks.	1.67+
taskIDBefore	Optional	string	The ID of the task that will be added before this task. The ID is used to identify the dependent task in the solution XML.	1.67+
durationBefore	Optional	NonNegativeInteger	The length of time in minutes of the dependent task before this task. This only applies to tasks at the start of a shift.	1.67+
taskIDAfter	Optional	string	The ID of the task that will be added after this task. The ID is used to identify the dependent task in the solution XML.	1.67+
durationAfter	Optional	NonNegativeInteger	The length of time in minutes of the dependent task after this task. This only applies to tasks at the end of a shift.	1.67+
weight	Optional	NonNegativeDouble	A value added to the solution's penalty for this dependent task.	1.67+
label	Optional	string	A label for the constraint.	1.67+

Example

<DependentTasks>
  
  <Task taskID="task1" taskIDBefore="preTask1" taskIDAfter="postTask1" 
        durationBefore="45" durationAfter="30" weight="10"/>
  
  <Task taskID="task2" taskIDBefore="preTask2" taskIDAfter="postTask2" 
        durationBefore="20" durationAfter="0" weight="10"/>
        
  <Task taskID="task3" taskIDBefore="preTask2" durationBefore="20" weight="10"/>
  
</DependentTasks>

<Skills>

The skills, qualifications, experience, training, group etc this employee has/belongs to. Cover requirements may be specified by skill as well as task.

Parents : Employee

Attributes

None

Elements

Skills contains one or more <Skill> elements.

Name	Required	Type	Description
<Skill>	Required	string	A skill ID.

Example

<Skills>
  <Skill>Skill1</Skill>
  <Skill>Skill2</Skill>
</Skills>

<CoverRequirements>

The minimum and maximum numbers of employees required (and/or preferred) to cover tasks at certain times in the scheduling horizon.

Parents : SchedulingHorizon

Attributes

None

Elements

CoverRequirements contains zero or more <Cov> or <CoverRequirement> elements.

Since version 1.39 it is possible to use the <Cov> or the <CoverRequirement> tag. The <Cov> tag is the recommended method because it is simpler and more compact. The main difference between <Cov> and <CoverRequirement> is how the start and end times are interpreted. Using <Cov> if the start and end time covers more than one time interval then the minimum and maximum requirements apply to each time interval between the start and end time. For example if the interval length is 15 minutes, the start time is 10:00, the end time is 11:00 and the minimum is 3 staff then this means that 3 people are required from 10:00-10:15, 3 people are required from 10:15-10:30, 3 people are required from 10:30-10:45 and 3 people are required from 10:45-11:00.
Using <CoverRequirement> however this would be interpreted as 3 people can be working at any time between 10:00-11:00. For example, there could be 2 people at 10:00-10:15 and 1 at 10:15-10:30 and the constraint would be satisfied.

Name	Required	Type	Description	Ver.
<Cov>	Optional	Cov	The minimum and maximum number of employees required to cover a task during a time period.	1.39+
<CoverRequirement>	Optional	CoverRequirement	The minimum and maximum number of employees required to cover a task during a time period.	1.0+

Example

<CoverRequirements>
  <Cov start="2014-06-16T06:00:00" end="2014-06-16T09:00:00" task="T1">
    <Min weight="1000">1</Min>
    <Max function="quadratic" weight="1">2</Max>
  </Cov>
  <Cov start="2014-06-16T09:00:00" end="2014-06-16T18:00:00" task="T1">
    <Min weight="1000">2</Min>
    <Max function="quadratic" weight="1">4</Max>
  </Cov>
  <Cov start="2014-06-16T18:00:00" end="2014-06-16T22:00:00" task="T1">
    <Min weight="1000">1</Min>
    <Max function="quadratic" weight="1">2</Max>
  </Cov>
</CoverRequirements>

<Cov>

The minimum and maximum number of employees required to cover a task during a time period.

If the start to end time spans more than one time interval then it means that the min and max requirements apply to each time interval between the start and end. For example, if the interval length is 15 minutes, the start time is 10:00, the end time is 11:00 and the minimum is 3 staff then this means that 3 people are required from 10:00-10:15, 3 people are required from 10:15-10:30, 3 people are required from 10:30-10:45 and 3 people are required from 10:45-11:00. If the float attribute is set to true though then it means that 3 intervals in total must be covered between the start and end. For example, there could be 2 people at 10:00-10:15 and 1 at 10:15-10:30 and the constraint would be satisfied.
The <Min> and <Max> elements both have weight attributes. If the cover requirement is not satisfied then the amount by which the requirement is not satisfied is multiplied by the weight and added to the solution's penalty. For example, if a minimum of 10 employees are required for a task at a certain time period but only 8 are provided in the solution then a penalty of (10-8) * weight will be added to the penalty.
<Min> and <Max> can also optionally have function attributes which can have the values 'Linear', 'Quadratic' or 'Constant' (case-insensitive). If the 'Quadratic' function is used and the cover requirement is not satisfied then the amount by which the requirement is not satisfied is squared and then multiplied by the weight and added to the solution's penalty. So for the example above the penalty would be (10-8) * (10-8) * weight.

Parents : CoverRequirements

Attributes

Name	Required	Type	Description	Ver.
start	Required	DateTime	The start of the time period the cover requirement applies to.	1.39+
end	Required	DateTime	The end of the time period the cover requirement applies to.	1.39+
task	Required	string	A Task or TaskGroup ID. A TaskGroup can also be specified as a comma-separated list of Task ID's. If a TaskGroup is specified then it means a minimum or maximum number of staff must be assigned at this time to all combinations of the tasks in the group (not each task).	1.39+
skill	Optional	string	A Skill or SkillGroup ID. If this attribute is used then it means the min or max number of employees must also have this skill or one of the skills in this skill group. A comma-separated list of Skill ID's may also be provided to represent a SkillGroup.	1.39+
float	Optional	Boolean	If this attribute is used and set to true and the start and end times cover more than one time interval then it means the minimum and maximum requirements are in total for all the time intervals covered (not for each interval). For example, if the interval length is 15 minutes, the start time is 10:00, the end time is 11:00 and the minimum is 3 staff then it means that 3 intervals in total must be covered between the start and end. For example, there could be 2 people at 10:00-10:15 and 1 at 10:15-10:30 and the constraint would be satisfied. If this attribute is not used then the value is assumed to be false by default.	1.39+
bydate	Optional	Boolean	If this attribute is used and set to true then the min and max requirements are in total for all the time intervals covered (not for each interval) between the start and end date (The time component is now ignored in the start and end attributes and a day is assumed to start at 00:00. The dates can also just be provided in the format YYYY-MM-DD. The end date is inclusive). For example, if the interval length is 15 minutes, and the constraint is to make sure there are no more than 40 hours assigned of a task (or group of tasks) over a seven day period. Then the maximum should be set as 40*(60/15)=160. Only shifts which start within the start and end date window are counted. If a shift finishes after the window end but starts within then it is still counted in its entirety (this is the same behaviour as the Workload constraints). If this attribute is not used then the value is assumed to be false by default.	1.55+
byDateShiftEnd	Optional	Boolean	If this attribute is used and set to true then it is the same as the bydate attribute above except that shifts are categorised by their end time rather than their start time. If a shift ends between the start and end date then it is counted in its entirety. (There is a similar option for the Workload constraints).	1.56+
consecutive	Optional	Boolean	If this attribute is used and set to true and the start and end times span more than one time interval and the float attribute is set to true then the work must be assigned consecutively. For example if there was a minimum constraint of 4 between 09:00-11:00 and the scheduling horizon is split into 15 minute time intervals then at least one employee must be assigned at least 60 (4*15) consecutive minutes on that task between 09:00-11:00. If it was a maximum of 4 then no employees can be assigned 60 or more consecutive minutes of that task between 09:00-11:00. If this attribute is not used then the value is assumed to be false by default.	1.39+
ID	Optional	string	An ID for the constraint which can be used to get information from the solver about the solution before, during and after solving.	1.39+

Elements

Cov contains in any order, any number of <Min> and <Max> elements.

Name	Required	Type	Description	Ver.
<Min>	Optional	NonNegativeDouble	The minimum number of employees required. Min must have a weight attribute (NonNegativeDouble) and optionally a function attribute (valid values: 'Linear', 'Quadratic' or 'Constant' (case-insensitive)). If the function attribute is not used then the weight function is linear by default.	1.39+
<Max>	Optional	NonNegativeDouble	The maximum number of employees required. Max must have a weight attribute (NonNegativeDouble) and optionally a function attribute (valid values: 'Linear', 'Quadratic' or 'Constant' (case-insensitive)). If the function attribute is not used then the weight function is linear by default.	1.39+

Example

<Cov start="2014-06-16T06:00:00" end="2014-06-16T09:00:00" task="T1">
  <Min weight="10000">3</Min>
  <Max weight="10000">6</Max>
  <Min function="quadratic" weight="1">4</Min>
  <Max function="quadratic" weight="1">4</Max>
</Cov>

<CoverRequirement>

The minimum and maximum number of employees required to cover a task during a time period.

Parents : CoverRequirements

Attributes

None

Elements

CoverRequirement contains <Start> and <End> elements (or an <Index element) followed by one or more <Cover elements.

Name	Required	Type	Description
<Start>	Optional	DateTime	The start of the time period the cover requirement applies to.
<End>	Optional	DateTime	The end of the time period the cover requirement applies to.
<Index>	Optional	NonNegativeInteger	An index in the scheduling horizon the cover requirement applies to. The scheduling horizon starts on index zero.
<Cover>	Required	Cover	The min and/or max numbers of employees (optionally with certain skills) required to cover a task for this time period.

Example

<CoverRequirement>
  <Start>2011-11-13T10:00</Start>
  <End>2011-11-13T10:15</End>
  <Cover>
    <Task>T1</Task>
    <Min weight="1000">2</Min>
    <Max function="quadratic" weight="1">2</Max>
  </Cover>
</CoverRequirement>

<Cover>

The min and/or max numbers of employees (optionally with certain skills) required to cover a task for this time period.

The <Min> and <Max> elements both have weight attributes. If the cover requirement is not satisfied then the amount by which the requirement is not satisfied is multiplied by the weight and added to the solution's penalty. For example if a Min of 10 employees are required for task at a certain time period but only 8 are provided in the solution then a penalty of (10-8) * weight will be added to the penalty.
<Min> and <Max> can also optionally have function attributes which can have the values 'Linear', 'Quadratic' or 'Constant' (case-insensitive). If the 'Quadratic' function is used and the cover requirement is not satisfied then the amount by which the requirement is not satisfied is squared and then multiplied by the weight and added to the solution's penalty. So for the example above the penalty would be (10-8) * (10-8) * weight.

Parents : CoverRequirement

Attributes

Name	Required	Type	Description	Ver.
ID	Optional	string	An ID for the constraint which can be used to get information from the solver about the solution before, during and after solving.	1.10+
consecutive	Optional	Boolean	If this attribute is used and set to true and the constraint spans more than one time interval (index) then the work must be assigned consecutively. For example if there was a minimum constraint of 4 between 09:00-11:00 and the scheduling horizon is split into 15 minute time intervals then at least one employee must be assigned at least 60 (4*15) consecutive minutes on that task between 09:00-11:00. If it was a maximum of 4 then no employees can be assigned 60 or more consecutive minutes of that task between 09:00-11:00.	1.0+

Elements

Cover contains a <Skill> or <SkillGroup> element (both optional) followed by a <Task> or <TaskGroup> element followed by <Min> and/or <Max> (both optional) followed by a <Label> element (optional).

Name	Required	Type	Description
<Skill>	Optional	string	The min or max number of employees covering this task must also have this skill. (An employee's skills are defined in Employee).
<SkillGroup>	Optional	string	The min or max number of employees covering this task must also have one of the skills in this skill group. The skill group is specified using an ID defined in SkillGroups.
<Task>	Optional	string	The task this cover requirement applies to. The task is specified using an ID defined in Tasks.
<TaskGroup>	Optional	string	The task group this cover requirement applies to. The task group is specified using an ID defined in TaskGroups.
<Min>	Optional	NonNegativeDouble	The minimum number of employees required. If the constraint spans more than one time interval (a floating cover constraint) then this is the minimum number of time intervals of this task assigned during the time span. Min must have a weight attribute (NonNegativeDouble) and optionally a function attribute (valid values: 'Linear', 'Quadratic' or 'Constant' (case-insensitive)). If the function attribute is not used then the weight function is linear by default.
<Max>	Optional	NonNegativeDouble	The maximum number of employees required. If the constraint spans more than one time interval (a floating cover constraint) then this is the maximum number of time intervals of this task assigned during the time span. Max must have a weight attribute (NonNegativeDouble) and optionally a function attribute (valid values: 'Linear', 'Quadratic' or 'Constant' (case-insensitive)). If the function attribute is not used then the weight function is linear by default.
<Label>	Optional	string	A label used to describe the constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML).

Example

<Cover>
  <Task>T2</Task>
  <Min weight="1000">12</Min>
  <Max function="quadratic" weight="1">12</Max>
  <Label>Must be at least 12 employees from 09:00-12:00</Label>
</Cover>

<Requests>

Requests for specific days on or off, or for specific shifts on or off.

Parents : SchedulingHorizon

Attributes

None

Elements

Contains zero or more <OffDay>, <OnDay>, <OffShift>, <OnShift> elements in any order.

Name	Required	Type	Description	Ver.
<OffDay>	Optional	OffDay	A day off constraint.	2.0+
<OnDay>	Optional	OnDay	A day on constraint.	2.0+
<OffShift>	Optional	OffShift	A shift off constraint.	2.0+
<OnShift>	Optional	OnShift	A shift on constraint.	2.0+

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"/>
    
  <OffShift weight="1000" employee="C" date="2018-02-18" shift="E"/>
  <OffShift weight="1000" employee="C" date="2" shift="L"/>
    
  <OnShift weight="1000" employee="D" date="2018-02-17" shift="E"/>
  <OnShift weight="1000" employee="D" date="0" shift="E,L,D"/>
  <OnShift weight="1000" employee="D" date="1" shift="Grp1"/>

</Requests>

<OffDay>

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.	2.0+
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).	2.0+
weight	Required	NonNegativeDouble	The weight for the constraint.	2.0+

Example

<OffDay weight="1000" employee="A" date="2018-02-18"/>

<OnDay>

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.	2.0+
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).	2.0+
weight	Required	NonNegativeDouble	The weight for the constraint.	2.0+

Example

<OnDay weight="1000" employee="B" date="2018-02-18"/>

<OffShift>

A shift off constraint. The employee must not be assigned the specified shift.

Parents : Requests

Attributes

Name	Required	Type	Description	Ver.
employee	Required	string	An Employee ID.	2.0+
shift	Required	string	A ShiftType ID.	2.0+
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).	2.0+
weight	Required	NonNegativeDouble	The weight for the constraint.	2.0+

Example

<OffShift weight="1000" employee="C" date="2018-02-18" shift="E"/>

<OnShift>

A shift on constraint. The employee must be assigned the specified shift or one of several shifts.

Parents : Requests

Attributes

Name	Required	Type	Description	Ver.
employee	Required	string	An Employee ID.	2.0+
shift	Required	string	A ShiftType ID, or a shift group as a comma-separated list of shift ID's (e.g. "E,D,L,N"), or a ShiftGroup ID.	2.0+
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).	2.0+
weight	Required	NonNegativeDouble	The weight for the constraint.	2.0+

Example

<OnShift weight="1000" employee="D" date="2018-02-17" shift="E"/>

<FixedAssignments>

These are shift assignments (or day off assignments) which must be in the solution.

Remarks
Fixed assignments can contain any break assignment/configuration, the break(s) in a fixed assignment do not have to be valid according to break constraints defined for that employee.
Fixed assignments may also contain tasks which are defined as not valid for that employee. In other words, if a fixed assignment contains a task which cannot be assigned to that employee then it will not be considered a violation and the fixed assignment will still appear in the solution (version 1.27+).
If a fixed NoShift assignment and a fixed Shift assignment overlap then the Shift assignment will override the NoShift assignment. In other words, a fixed Shift assignment will still appear in the solution even if there is a NoShift assignment overlapping with that Shift.

Parents : SchedulingHorizon

Attributes

None

Elements

FixedAssignments contains zero or more <Employee> elements.

Name	Required	Type	Description
<Employee>	Optional	Employee	Contains assignments which must be in an employee's schedule in the solution.

Example

<FixedAssignments>
  <Employee ID="E1">
    <NoShift>
      <Start>2011-11-16T08:00</Start>
      <End>2011-11-16T12:30</End>
    </NoShift>
    <NoShift>
      <Start>2011-11-17T14:00</Start>
      <End>2011-11-17T19:00</End>
    </NoShift>
  </Employee>
  <Employee>
    <EmployeeID>E2</EmployeeID>
    <NoShift>
      <Start>2011-11-19T08:00</Start>
      <End>2011-11-19T19:00</End>
    </NoShift>
  </Employee>
</FixedAssignments>

<Employee>

These are shift assignments (or day 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. The employee ID is defined in <Employees>.	1.57+

Elements

Employee contains zero or more <NoShift> and <Shift> elements.

Name	Required	Type	Description
<NoShift>	Optional	NoShift	A time period during which the employee must have no tasks assigned.
<Shift>	Optional	Shift	A pre-assigned shift which cannot be altered or un-assigned.

Example

<Employee ID="E1">
  <NoShift>
    <Start>2011-11-16T08:00</Start>
    <End>2011-11-16T12:30</End>
  </NoShift>
  <NoShift>
    <Start>2011-11-17T14:00</Start>
    <End>2011-11-17T19:00</End>
  </NoShift>
  <Shift>
    <Date>2011-11-15</Date>
    <Start>07:30:00</Start>
    <Task>
      <ID>T1</ID>
      <Length>150</Length>
    </Task>
    <Task>
      <ID>$b</ID>
      <Length>30</Length>
    </Task>
    <Task>
      <ID>T1</ID>
      <Length>120</Length>
    </Task>
    <Task>
      <ID>$b</ID>
      <Length>30</Length>
    </Task>
    <Task>
      <ID>T1</ID>
      <Length>210</Length>
    </Task>
  </Shift>
</Employee>

<NoShift>

An employee must have no task assignments during this time period.

Parents : Employee

Attributes

None

Elements

NoShift contains a <Start> and <End> element.

Name	Required	Type	Description
<Start>	Required	DateTime	The start of the time period during which the employee must not have any task assignments.
<End>	Required	DateTime	The end of the time period during which the employee must not have any task assignments.

Example

<NoShift>
  <Start>2011-11-19T08:00</Start>
  <End>2011-11-19T19:00</End>
</NoShift>

<Shift>

A pre-assigned shift which cannot be altered or un-assigned. Fixed shifts are allowed to break hard constraints such as Breaks, ValidTasks, Shift Start and End Times, ValidTaskTransfers and MinRestTime between fixed shifts.

For a split shift enter the Task ID as '-' (hyphen) to indicate the split and its duration.

Parents : Employee

Attributes

Name	Required	Type	Description	Ver.
addBreaks	Optional	Boolean	If this value is set as 'true' then the solver will add break(s) to this shift. The shift's start and end time and the tasks within the shift will not be changed though. If this attribute is not used then the default value is 'false' meaning breaks will not be added or changed in this shift.	1.49+
type	Optional	string	If this value is set as 'external' then the shift is considered as a fixed, pre-assigned shift that cannot be altered but it can be replaced by a generated shift, if doing so creates a better solution. If this attribute is not used then the shift is a standard, fixed shift which must always appear in the solution and which cannot be altered.	1.45+
ExternalID	Optional	string	An ID that can be used to identify this shift in the solution XML. If this attribute is used then in the solution XML returned by the engine this shift will have the same ExternalID attribute value (see the Solution documentation).	1.33+

Elements

Shift contains a <Day> or <Date> element followed by a <Start> element followed by one or more <Task> elements.

Name	Required	Type	Description
<Day>	Required	NonNegativeInteger	The day in the planning period the shift starts on (the first day in the planning period is day zero).
<Date>	Required	Date	The date the shift starts on. Specified in the format : YYYY-MM-DD.
<Start>	Required	TimeOfDay	The time the shift starts.
<Task>	Required	Task	Task contains a task ID (defined in Tasks) and a duration to indicate the amount of time to spend on that task before switching to the next task or break.

Example

<Shift>
  <Day>0</Day>
  <Start>07:30:00</Start>
  <Task>
    <ID>T1</ID>
    <Length>150</Length>
  </Task>
  <Task>
    <ID>$b</ID>
    <Length>30</Length>
  </Task>
  <Task>
    <ID>T1</ID>
    <Length>120</Length>
  </Task>
  <Task>
    <ID>$b</ID>
    <Length>30</Length>
  </Task>
  <Task>
    <ID>T1</ID>
    <Length>210</Length>
  </Task>
</Shift>

<Task>

Task contains a task ID and a duration to indicate the amount of time to spend on that task before switching to the next task or break.

Parents : Shift

Attributes

Name	Required	Type	Description	Ver.
WorkLength	Optional	NonNegativeDouble	The amount of time (in minutes) this task is counted as work. This may not be the same as the Length (i.e. the difference between the start and finish time) if for example it is a break which is not counted as work.	1.14+

Elements

Task contains an <ID> element followed by a <Length> element.

Name	Required	Type	Description
<ID>	Required	string	The task ID (defined in Tasks). For breaks the ID is $b. For a split shift set the task ID as '-' (hyphen) to indicate the split.
<Length>	Required	NonNegativeDouble	The time in minutes for this task.

Example

<Task>
  <ID>T1</ID>
  <Length>150</Length>
</Task>

<FixedShiftTasks>

Tasks which must appear at defined points and durations within a shift if a shift is assigned on the defined day to the defined employee.

Parents : SchedulingHorizon

Attributes

None

Elements

FixedAssignments contains zero or more <FixedTask> elements.

Name	Required	Type	Description	Ver.
<FixedTask>	Optional	FixedTask	Defines tasks which must appear at certain points and for certain durations in a shift if a shift is assigned to the defined employee on the defined date.	1.29+

Example

<FixedShiftTasks>
  <FixedTask>
    <Employee>E1</Employee>
    <Day>0</Day>
    <Task>
      <ID>j</ID>
      <Length>30</Length>
      <Start>0</Start>
    </Task>
    <Task>
      <ID>k</ID>
      <Length>30</Length>
      <Start>30</Start>
    </Task>
  </FixedTask>
  <FixedTask>
    <Employee>E2</Employee>
    <Day>0</Day>
    <Task>
      <ID>j</ID>
      <Length>60</Length>
      <StartFromEnd>60</StartFromEnd>
    </Task>
  </FixedTask>
</FixedShiftTasks>

<FixedTask>

Defines tasks which must appear at certain points and for certain durations in a shift if a shift is assigned to the defined employee on the defined date.

Parents : FixedShiftTasks

Attributes

None

Elements

FixedTask contains in any order an <Employee> element, a <Day> or <Date> element and one or more <Task> elements.

Name	Required	Type	Description	Ver.
<Employee>	Required	string	The ID of the employee the constraint applies to. The employee ID is defined in <Employees>.	1.29+
<Day>	Optional	NonNegativeInteger	The day index in the scheduling horizon the constraint applies to. The scheduling horizon starts on day zero.	1.29+
<Date>	Optional	Date	The date the constraint applies to. Specified in the format : YYYY-MM-DD.	1.29+
<Task>	Required	Task	A task which must be assigned at a defined point and for a defined duration within a shift.	1.29+

Example

<FixedTask>
  <Employee>E1</Employee>
  <Day>0</Day>
  <Task>
    <ID>j</ID>
    <Length>60</Length>
    <Start>0</Start>
  </Task>
</FixedTask>

<Task>

A task which must be assigned at a defined point and for a defined duration within a shift.

Parents : FixedTask

Attributes

Name	Required	Type	Description	Ver.
splitShift	Optional	NonNegativeInteger	If the employee can be assigned split-shifts then this attribute is required to define which stretch of work to apply the constraint to in a split-shift. For example to apply this constraint to the first stretch of work in a split-shift then use splitShift=1. If this attribute is used then the constraint defined only applies to corresponding work stretches in split-shifts. In other words additional FixedTask constraints will need to be defined for non split-shifts.	1.29+

Elements

Task contains in any order an <ID> and <Length> element and a <StartTime>, <Start> or <StartFromEnd> element.

Name	Required	Type	Description	Ver.
<ID>	Required	string	The task ID. The task ID is defined in <Tasks>.	1.29+
<Length>	Required	NonNegativeDouble	The length of time in minutes that the task should be assigned for.	1.29+
<StartTime>	Optional	TimeOfDay	The time of the day when the task should start.	1.32+
<Start>	Optional	NonNegativeDouble	The relative point of time in minutes after the start of the shift when the task should start. For example to start the shift with this task use the value zero.	1.29+
<StartFromEnd>	Optional	NonNegativeDouble	The relative point of time in minutes before the end of the shift when the task should start. For example to ensure the last 30 minutes of a shift is this task use Length=30 and StartFromEnd=30.	1.29+

Example

<Task>
  <ID>j</ID>
  <Length>60</Length>
  <Start>0</Start>
</Task>

---

Boolean

Boolean is one of the values {true, false, 1, 0}.

DateTime

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: 2012-04-30T12:43:35, 2012-04-30T12:43.

ID

ID is a string which can contain only the characters A to Z (upper and lower case), 0 to 9, period (.) and underscore (_).

NonNegativeDouble

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.

PositiveDouble

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.

NonNegativeInteger

NonNegativeInteger is a whole number greater than or equal to zero (e.g. 0,1,2,..).

Hard Constraint

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.

Integer

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.

Soft Constraint

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

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.

TimeSpan

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.