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.

XML data flow diagram

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

Annotated ShiftSolver instance

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+
<DayOffRequests> Optional DayOffRequests Dates on which employees request not to be working. 1.2+
<DayOnRequests> Optional DayOnRequests Dates on which employees want to be working. 1.2+
<ShiftOffRequests> Optional ShiftOffRequests Dates on which employees do not want specific shifts. 1.2+
<ShiftOnRequests> Optional ShiftOnRequests Dates on which employees want specific shifts. 1.2+
<FixedAssignments> Optional FixedAssignments Tasks, time periods and days which must be assigned or not assigned (in other words 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+
<Rules> Optional Rules Rules can be used to create new, custom constraints related to shift types that cannot otherwise be modelled using other options such as Patterns. 1.47+

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+
<Resources> Optional Resources This can be used to define 'resources' (keys and numerical values) which are associated with the shift type. The resources defined here can then be referenced in the Rule constraint. 1.47+

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+
<Patterns> Optional Patterns A flexible constraint which can model a wide variety of requirements on the employee's work schedule. 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+

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>

<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 pattern 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 comma separated 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+
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 number in the planning horizon or actual dates. The first day in the planning period is day zero. A day starts at midnight (00:00).

A shift which starts before but finishes after the region start date is not counted in the total work time for a region. A shift which starts within the region but finishes after the region end date is counted in its entirety in the total work time for a region. That is, the total work time for a region is the sum of the shifts which start within the region.

Parents : Workload

Attributes

None

Elements

Workload contains a <Min> and/or a <Max> element (in either order) a <RegionStart> or <RegionStartDate> (both are optional) and a <RegionEnd> or <RegionEndDate> (both are optional).

The default start day is day zero if <RegionStart> and <RegionStartDate> are omitted. The default end day is the last day in the planning horizon if <RegionEnd> and <RegionEndDate> are omitted.

Name Required Type Description
<Min> Optional Min The minimum number of minutes worked.
<Max> Optional Max The maximum number of minutes worked.
<RegionStart> Optional NonNegativeInteger The first day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionStartDate> Optional date The first day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.
<RegionEnd> Optional NonNegativeInteger The last day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionEndDate> Optional date The last day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.

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 RegionStart and RegionEnd) 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 RegionStart and RegionEnd) 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>

<Patterns>

This is a general and flexible constraint which can model a wide variety of requirements on the employee's schedule.

Parents : Contract

Attributes

None

Elements

Patterns contains one or more <Match> elements.

Name Required Type Description
<Match> Required Match Match specifies a minimum and/or maximum total number of matches of particular sequences of shifts (patterns) between any two dates in the planning period. The pattern is expressed in the form of a regular expression.

Example

<Patterns>
  <Match>
    <Max>
      <Count>18</Count>
      <Weight>1000</Weight>
      <Label>Max 18 shifts</Label>
    </Max>
    <Pattern>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>4</Count>
      <Weight>1000</Weight>
      <Label>Max 4 nights</Label>
    </Max>
    <Pattern>
      <Shift>N</Shift>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>0</Count>
      <Weight>10</Weight>
      <Label>Min 2 consecutive days off</Label>
    </Max>
    <Pattern>
      <Start>0</Start>
      <Shift>-</Shift>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
    <Pattern>
      <ShiftGroup>All</ShiftGroup>
      <Shift>-</Shift>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>0</Count>
      <Weight>1000</Weight>
      <Label>Max 6 consecutive days on</Label>
    </Max>
    <Pattern>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>0</Count>
      <Weight>100</Weight>
      <Label>Complete weekends</Label>
    </Max>
    <Pattern>
      <StartDay>Saturday</StartDay>
      <ShiftGroup>All</ShiftGroup>
      <Shift>-</Shift>
    </Pattern>
    <Pattern>
      <StartDay>Saturday</StartDay>
      <Shift>-</Shift>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>0</Count>
      <Weight>1000</Weight>
      <Label>No night shift before a free weekend</Label>
    </Max>
    <Pattern>
      <StartDay>Friday</StartDay>
      <Shift>N</Shift>
      <Shift>-</Shift>
      <Shift>-</Shift>
    </Pattern>
  </Match>
  <Match>
    <Max>
      <Count>0</Count>
      <Weight>1000</Weight>
      <Label>At least two free days after a night shift</Label>
    </Max>
    <Pattern>
      <Shift>N</Shift>
      <Shift>-</Shift>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
</Patterns>

<Match>

Match specifies a minimum and/or maximum total number of matches of particular sequences of shifts (patterns) between any two dates in the planning period. The dates can be specified using the day number in the planning horizon or actual dates (the first day in the horizon is day zero). A pattern is only matched if it is found entirely between the start and end date.

A pattern is specified using a regular expression which matches one of the following for each day in the pattern :

  • A specific shift
  • Any shift
  • A day off (a day without a shift)
  • Anything (any shift or a day off)
  • One of a group of shifts
  • Not a shift
  • Not one of a group of shifts

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

Attributes

None

Elements

Match contains a <Min> and/or a <Max> element (in either order) a <RegionStart> or <RegionStartDate> (both are optional) a <RegionEnd> or <RegionEndDate> (both are optional) and one or more <Pattern> elements.

The default start day is day zero if <RegionStart> and <RegionStartDate> are omitted. The default end day is the last day in the planning horizon if <RegionEnd> and <RegionEndDate> are omitted.

Name Required Type Description
<Min> Optional Min The minimum number of matches of the pattern(s).
<Max> Optional Max The maximum number matches of the pattern(s).
<RegionStart> Optional NonNegativeInteger The first day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionStartDate> Optional date The first day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.
<RegionEnd> Optional NonNegativeInteger The last day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionEndDate> Optional date The last day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.
<Pattern> Required Pattern A regular expression for matching sequences of shift types and days off.

Example

<Match>
  <Max>
    <Count>2</Count>
    <Weight>1000</Weight>
    <Label>Max 2 consecutive working weekends</Label>
  </Max>
  <RegionStart>5</RegionStart>
  <RegionEnd>20</RegionEnd>
  <Pattern>
    <StartDay>Saturday</StartDay>
    <ShiftGroup>All</ShiftGroup>
    <Shift>-</Shift>
  </Pattern>
  <Pattern>
    <StartDay>Saturday</StartDay>
    <Shift>-</Shift>
    <ShiftGroup>All</ShiftGroup>
  </Pattern>
  <Pattern>
    <StartDay>Saturday</StartDay>
    <ShiftGroup>All</ShiftGroup>
    <ShiftGroup>All</ShiftGroup>
  </Pattern>
</Match>

<Pattern>

Pattern is a regular expression for matching sequences of shift types and days off in an employee's schedule.

Parents : Patterns

Attributes

None

Elements

Pattern contains any number of <Start>, <StartDay>, <StartDate>, <Starts> and <StartExcludes> elements (all optional) followed by one or more of the elements : <Shift>, <NotShift>, <ShiftGroup>, <NotGroup> (in any order).

If none of <Start>, <StartDay>, <StartDate>, <Starts> or <StartExcludes> are used then the pattern will be matched when it starts on any day in the planning period.

Name Required Type Description
<Start> Optional NonNegativeInteger The pattern is only matched if it starts on this day in the planning period (the planning period starts on day zero).
<StartDay> Optional string The pattern is only matched if it starts on this day of the week. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
<StartDate> Optional date The pattern is only matched if it starts on this date in the planning period. Specified in the format : YYYY-MM-DD.
<Starts> Optional DayIndexes The pattern is only matched if it starts on any of the days, dates and days of the week specified in this tag.
<StartExcludes> Optional DayIndexes 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 in this tag.
<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.

Since version 1.42 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.
<ShiftGroup> Optional string Match one of the shifts in this group of shifts. The group is specified using an ID defined in ShiftGroups.

Since version 1.42 it is also possible to specify a shift group as a comma separated list of shift ID's (e.g. "E,D,L,N").
<NotShift> Optional string Match anything but this shift (including a day without a shift). The shift is specified using an ID defined in ShiftTypes.

Since version 1.42 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).
<NotGroup> Optional string Match anything but one of the shifts in this group of shifts (including a day without a shift). The group is specified using an ID defined in ShiftGroups.

Since version 1.42 it is also possible to specify a shift group as a comma separated list of shift ID's (e.g. "E,D,L,N").

Example

<Match>
  <Max>
    <Count>3</Count>
    <Weight>1000</Weight>
    <Label>Max 3 Sundays</Label>
  </Max>
  <Pattern>
    <StartDay>Sunday</StartDay>
    <ShiftGroup>All</ShiftGroup>
  </Pattern>
</Match>

<DayIndexes>

DayIndexes is used to specify a group of days in the planning period.

Parents : Pattern

Attributes

None

Elements

Contains any number of <Day>, <Date> and <DayOfWeek> elements in any order.

Name Required Type Description
<Day> Optional NonNegativeInteger A day index in the planning period specified as an integer (the planning period starts on day zero).
<DayOfWeek> Optional string All indexes in the planning period which match this day of the week. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
<Date> Optional date An index in the planning period given as a date. Specified in the format : YYYY-MM-DD.

Example

<Starts>
  <Day>0</Day>
  <Day>2</Day>
  <Day>3</Day>
</Starts>

<Min>

Specifies a minimum value for a constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a minimum is not satisfied and the function type specified is linear then the penalty function value will be the minimum value minus the value provided in the solution then multiplied by the weight. If the function is quadratic it will be minimum value minus the value provided in the solution then squared and then multiplied by the weight.

Parents : Match

Attributes

None

Elements

Min contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeInteger The minimum value.
<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>1</Count>
  <Weight function="Quadratic">1000</Weight>
</Min>

<Max>

Specifies a maximum value for a constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a maximum is exceeded and the function type specified is linear then the penalty function value will be the value provided in the solution minus the maximum value then multiplied by the weight. If the function is quadratic it will be the value provided in the solution minus the maximum value then squared and then multiplied by the weight.

Parents : Match

Attributes

None

Elements

Max contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeInteger The maximum value.
<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>1</Count>
  <Weight function="Quadratic">1000</Weight>
</Max>

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

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.

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>

<Rules>

Rules are used to model new, custom constraints relating to ShiftTypes that cannot otherwise be modelled using other options such as Patterns.

Parents : SchedulingHorizon

Attributes

None

Elements

Rules contains zero or more <Rule> elements.

Name Required Type Description Ver.
<Rule> Optional Rule A rule is a boolean expression relating to shift assignments in the roster which must evaluate to true in the solution. 1.47+

Example

See Rule for examples.

<Rule>

Parents : Rules

A rule is a boolean expression relating to assignments in the roster which must evaluate to true in the solution.

The expression can contain

  • Arithmetic operators (+, -, *, /),
  • Relational operators (<, >, <=, >=, lt, gt, le, ge)
  • Equality operators (==, !=, eq, ne)
  • Boolean operators (!, &&, ||, not, and, or)
  • Constants (e.g. 0, 1, 2, 3, 1.5, -1, true, false)
  • Control statements (if, then, else)
  • Functions (e.g. abs, ceil, floor, max, min, pow, round, sign)
  • Variables.

Variables

A variable corresponds to an assignment in the roster and is specified using three sets of square brackets: [][][].
The first set of square brackets contains an employee ID.
The second set of square brackets contains a day index.
The third set of square brackets contains a shift ID.

In the solution the variable has the value 1 if the employee is assigned the shift type on the day index, otherwise the variable has the value 0.

In the first set of square brackets it is also possible to specify more than one employee by separating each ID using a comma ','. Additionally, skill IDs can be used which is equivalent to including all the employees with that skill.
In the second set of square brackets more than one day index can be specified by separating each index using a comma ','. A range of days can be specified by using a hyphen e.g. 0-3 is equivalent to [0,1,2,3] and more than one range can also be specified e.g. [0-3, 8-10, 19] is valid and equivalent to [0,1,2,3,8,9,10,19].
In the third set of brackets it is possible to specify more than one shift type by separating each ID using a comma ','. Additionally, shift group IDs can be used which is equivalent to including all the shifts in that group.

If more than one employee ID, day index and/or shift ID is used then for every matching assignment in the solution the variable's value is increased by one. For example:

For the variable [A][0-2][D], if employee A was assigned a D shift on days 0, 1 and 2 then the variable's value would be 3.

For the variable [A,B][0][D], if employees A and B both had D shifts on day 0 then the variable's value would be 2.

For the variable [A][0-1][D,E], if employee A had an E shift on day 0 and a D shift on day 1 then the variable's value would be 2.

For the variable [A][0-1][D,E], if employee A had a D and an E shift on day 0 and a D and an E shift on day 1 then the variable's value would be 4.

Example rules where variables such as these could then be used include:

[A][0-27][D] < 10    (Employee A must have less than 10 D shifts between days 0-27)

[A,B][0][D] <= 1     (A and B cannot both work D shift on day zero)

[A][0-6][D,E,N] < 1  (A cannot work shifts D, E or N on days 0-6)

A fourth set of square brackets can also be added to the variable to specify that the variable's value is the sum of resource values for the shifts rather just the number of shifts. For example if a resource has been defined in the ShiftTypes called TimeUnits then the following rule could be defined:

[A][0-27][AllShiftsGroup][TimeUnits] le 144    (Less than 144 hours work for employee A)

Conditional Expressions

A rule can take the form of a single boolean expression as in the examples above
or a conditional expression of the form: if expr1 then expr2
or a conditional expression of the form: if expr1 then expr2 else expr3
where expr1, expr2 and expr3 are boolean expressions. The conditional expression must evaluate to true in the solution.

Functions

Rules can also contain any number of inbuilt mathematical functions (e.g. abs, ceil, floor, max, min, pow, round, sign). See Rule functions.

Violations and Penalties

If the rule evaluates to false in a solution (i.e. it is a violation) then the penalty for the solution is increased by the value specified by the penalty attribute. The penalty attribute has the same syntax and uses the same operators as the rule expressions and it may also contain variables. The only difference is that it must be a numerical expression. That is, is must evaluate to a numerical value. If the penalty evaluates to a value less than zero then it assigned the value zero (negative penalties are not allowed).

See also: Operators, precedence and associativity.

Attributes

Name Required Type Description Ver.
penalty Required string If the rule is not satisfied then the solution's penalty is increased by the value of this numerical expression. The expression has the same syntax as a rule and can also contains variables. 1.47+
label Optional string A label to describe the rule. This is only used when displaying the solutions and identifying the violations (for example in the solution XML). 1.47+

Example

<Rules>
      
  <Rule penalty="1000" label="A total of more than 5 E shifts must be assigned to GroupA">
  
  [GroupA][0-27][E] gt 5 
  
  </Rule>
            
  <Rule penalty="(([GroupB][0][N] - 3) * ([GroupB][0][N] - 3)) * 100" 
        label="Max 3 N shifts assigned to GroupB on day zero (quadratic penalty)">
  
  [GroupB][0][N] le 3 
  
  </Rule>
      
  <Rule penalty="((([A][0-27][E] * 8) + ([A][0-27][L] * 8) + ([A][0-27][N] * 12)) - 144) * 1000" 
        label="Less than 144 hours work for employee A">
  
  (([A][0-27][E] * 8) + ([A][0-27][L] * 8) + ([A][0-27][N] * 12)) le 144 
  
  </Rule>
  
  <Rule penalty="1000" 
        label="If A has E and L shifts then they must have zero N shifts">
        
  if [A][0-27][E] ge 1 and [A][0-27][L] ge 1 then [A][0-27][N] le 0
  
  </Rule>
      
  <Rule penalty="10" 
        label="If A works a shift from GroupX on day zero 
               then B and C must not work a shift from GroupY on day one">
               
  if [A][0][GroupX] ne 0 then [B,C][1][GroupY] eq 0
  
  </Rule>
  
  <Rule penalty="abs(10 - [A][0-27][D]) * 1000" 
        label="Assign exactly 10 D shifts to employee A (linear penalty function)">
        
  [A][0-27][D] eq 10
  
  </Rule>  
      
</Rules>

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

<DayOffRequests>

Requests for days off during the planning period (that is, days without a shift) for each employee.

Parents : SchedulingHorizon

Attributes

None

Elements

Contains zero or more <DayOff> elements.

Name Required Type Description
<DayOff> Optional DayOff A day off request.

Example

<DayOffRequests>
  <DayOff weight="1000">
    <EmployeeID>A</EmployeeID>
    <Date>2007-01-03</Date>
  </DayOff>
  <DayOff weight="1000">
    <EmployeeID>A</EmployeeID>
    <Date>2007-01-04</Date>
  </DayOff>
  <DayOff weight="10">
    <EmployeeID>B</EmployeeID>
    <Date>2007-01-20</Date>
  </DayOff>
</DayOffRequests>

<DayOff>

A request for a day off.

Parents : DayOffRequests

Attributes

Name Required Type Description
weight Required NonNegativeDouble The weight for this request. The weight is used to reflect the importance of this constraint. If the request is not satisfied then this value is added to the penalty.

Elements

DayOff contains an <EmployeeID> element and a <Date> or <Day> element.

Name Required Type Description
<EmployeeID> Required string The ID of the employee making this request (see Employee).
<Date> Optional Date The date requested off. Specified in the format : YYYY-MM-DD.
<Day> Optional NonNegativeInteger The day in the scheduling period requested off. The scheduling period starts on day zero.

Example

<DayOff weight="1">
  <EmployeeID>A</EmployeeID>
  <Date>2007-02-05</Date>
</DayOff>

<DayOnRequests>

Employee requests for days they want to be working on.

Parents : SchedulingHorizon

Attributes

None

Elements

Contains zero or more <DayOn> elements.

Name Required Type Description
<DayOn> Optional DayOn A day on request.

Example

<DayOnRequests>
  <DayOn weight="1000">
    <EmployeeID>X</EmployeeID>
    <Date>2007-01-03</Date>
  </DayOn>
  <DayOn weight="1000">
    <EmployeeID>X</EmployeeID>
    <Date>2007-01-04</Date>
  </DayOn>
  <DayOn weight="10">
    <EmployeeID>Y</EmployeeID>
    <Date>2007-01-20</Date>
  </DayOn>
</DayOnRequests>

<DayOn>

A request for a day to be working on.

Parents : DayOnRequests

Attributes

Name Required Type Description
weight Required NonNegativeDouble The weight for this request. The weight is used to reflect the importance of this constraint. If the request is not satisfied then this value is added to the penalty.

Elements

DayOn contains an <EmployeeID> element and a <Date> or <Day> element.

Name Required Type Description
<EmployeeID> Required string The ID of the employee making this request (see Employee).
<Date> Optional Date The date requested on. Specified in the format : YYYY-MM-DD.
<Day> Optional NonNegativeInteger The day in the scheduling period requested on. The scheduling period starts on day zero.

Example

<DayOn weight="10">
  <EmployeeID>Y</EmployeeID>
  <Date>2007-01-20</Date>
</DayOn>

<ShiftOffRequests>

Requests for no shifts of a certain type on certain days in the planning period for each employee.

Parents : SchedulingHorizon

Attributes

None

Elements

Contains zero or more <ShiftOff> elements.

Name Required Type Description
<ShiftOff> Optional ShiftOff A request to not work a certain shift on a certain date.

Example

<ShiftOffRequests>
  <ShiftOff weight="5">
    <Shift>Early</Shift>
    <EmployeeID>ExampleEmployee</EmployeeID>
    <Date>2007-02-05</Date>
  </ShiftOff>
  <ShiftOff weight="5">
    <Shift>Early</Shift>
    <EmployeeID>ExampleEmployee</EmployeeID>
    <Date>2007-02-06</Date>
  </ShiftOff>
  <ShiftOff weight="5">
    <Shift>Night</Shift>
    <EmployeeID>ExampleEmployee</EmployeeID>
    <Date>2007-02-05</Date>
  </ShiftOff>
  <ShiftOff weight="5">
    <Shift>Night</Shift>
    <EmployeeID>ExampleEmployee</EmployeeID>
    <Date>2007-02-06</Date>
  </ShiftOff>
</ShiftOffRequests>

<ShiftOff>

A request for a shift off.

Parents : ShiftOffRequests

Attributes

Name Required Type Description
weight Required NonNegativeDouble The weight for this request. The weight is used to reflect the importance of this constraint. If the request is not satisfied then this value is added to the penalty.

Elements

ShiftOff contains a <Shift> element, an <EmployeeID> element and a <Date> or <Day> element.

Name Required Type Description
<Shift> Required string The ID of the shift (see ShiftTypes).
<EmployeeID> Required string The ID of the employee making this request (see Employee).
<Date> Optional Date The date the shift is requested off. Specified in the format : YYYY-MM-DD.
<Day> Optional NonNegativeInteger The day in the scheduling period the shift is requested off. The scheduling period starts on day zero.

Example

<ShiftOff weight="5">
  <Shift>Early</Shift>
  <EmployeeID>ExampleEmployee</EmployeeID>
  <Date>2007-02-06</Date>
</ShiftOff>

<ShiftOnRequests>

Requests for shifts of a certain type on certain days in the planning period for each employee.

Parents : SchedulingHorizon

Attributes

None

Elements

Contains zero or more <ShiftOn> elements.

Name Required Type Description
<ShiftOn> Optional ShiftOn A request for certain shift(s) on a certain date.

Example

<ShiftOnRequests>
  <ShiftOn weight="1">
    <ShiftGroupID>Early</ShiftGroupID>
    <EmployeeID>E1</EmployeeID>
    <Date>2007-02-05</Date>
  </ShiftOn>
  <ShiftOn weight="1">
    <ShiftGroupID>Late</ShiftGroupID>
    <EmployeeID>E2</EmployeeID>
    <Date>2007-02-06</Date>
  </ShiftOn>
  <ShiftOn weight="1">
    <Shift>L</Shift>
    <EmployeeID>E3</EmployeeID>
    <Date>2007-02-07</Date>
  </ShiftOn>
</ShiftOnRequests>

<ShiftOn>

A request for shift(s) on a specific day in the scheduling period.

Parents : ShiftOnRequests

Attributes

Name Required Type Description
weight Required NonNegativeDouble The weight for this request. The weight is used to reflect the importance of this constraint. If the request is not satisfied then this value is added to the penalty.

Elements

ShiftOn contains either a <Shift> element or a <ShiftGroupID> element or a <ShiftGroup> element, an <EmployeeID> element and a <Date> or a <Day> element.

Name Required Type Description
<Shift> Optional string The shift requested. Specified using the ID of the shift (see <ShiftTypes>).
<ShiftGroupID> Optional string The shift group requested. A shift from this group must be assigned on this day. The group is specified using the ID of a shift group (see <ShiftGroups>).
<ShiftGroup> Optional ShiftGroup The shift group requested. A shift from this group must be assigned on this day.
<EmployeeID> Required string The ID of the employee making this request. The employee ID is defined in <Employees>.
<Date> Optional Date The date the shift(s) is requested on. Specified in the format : YYYY-MM-DD.
<Day> Optional NonNegativeInteger The day in the scheduling period the shift(s) is requested on. The scheduling period starts on day zero.

Example

<ShiftOn weight="1">
  <ShiftGroupID>Early</ShiftGroupID>
  <EmployeeID>E1</EmployeeID>
  <Date>2007-02-05</Date>
</ShiftOn>

<ShiftGroup>

A group of shift types.

Parents : ShiftOn

Attributes

None

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>
  <Shift>E</Shift>
  <Shift>N</Shift>
</ShiftGroup>

<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>
    <EmployeeID>E1</EmployeeID>
    <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 Optional string The ID of the employee the assignments belong to (this can be used instead of the EmployeeID tag). 1.57+

Elements

Employee contains an <EmployeeID> element followed by zero or more <NoShift> and <Shift> elements.

Name Required Type Description
<EmployeeID> Required string The ID of the employee the assignments belong to. The employee ID is defined in <Employees>. Since version 1.57+ the ID attribute in the Employee element can be used instead.
<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>
  <EmployeeID>E1</EmployeeID>
  <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.