ScheduleSolver problem data

XML format for ScheduleSolver problem instances

This document describes the data format used for ScheduleSolver problem instances. As well as being read by the rostering engine, the format can also be read by RosterViewer. The data format is an XML based format and can be validated against the format's schema.

Although instances can be created using an editor, in practice the XML is normally generated dynamically by another application. This XML is then passed to the rostering engine which solves the problem and returns the solution. The solution is also encoded using an XML format.

XML data flow diagram

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>.
  • Tasks. The tasks to be assigned. 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, 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 also impacted 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 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.

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

<ScheduleSolver>

The root element of the document.

Attributes

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

Elements

ScheduleSolver contains the following elements in any order:

Name Required Type Description Ver.
<StartDate> Required date The date of the first day in the scheduling horizon. Specified in the format : YYYY-MM-DD. 1.0+
<EndDate> Required date The date of the last day in the scheduling horizon. Specified in the format : YYYY-MM-DD. 1.0+
<Tasks> Optional Tasks The tasks to be assigned. 1.7+
<ShiftTypes> Optional ShiftTypes For some constraints it is necessary to categorise each shift as a certain type e.g. a 'Night Shift', 'Late Shift' or 'Early Shift' etc. The shifts can be categorised by their start times, end times and lengths. The shift types are defined here. 1.0+
<Contracts> Optional Contracts Each employee can have a different set of constraints for their work schedule. These are specified within contracts which are linked to each employee. 1.0+
<Employees> Optional Employees The employees to assign the tasks to. 1.0+
<FixedAssignments> Optional FixedAssignments Tasks, time periods and days which must be assigned or not assigned (they are fixed in place and cannot be changed). 1.0+
<Requests> Optional Requests Employee requests for days on or off, or specific shift types on certain dates. 1.2+

Example

<?xml version="1.0" encoding="UTF-8"?>
<ScheduleSolver 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="ScheduleSolver-1.0.xsd">
  <StartDate>2018-10-07</StartDate>
  <EndDate>2018-10-13</EndDate>
  <Tasks>
    <Task ID="T1">
      <Start>2018-10-07T06:00:00</Start>
      <End>2018-10-07T20:00:00</End>
      <Weight>1000000</Weight>
    </Task>
    <Task ID="T2">
      <Start>2018-10-07T04:00:00</Start>
      <End>2018-10-07T16:00:00</End>
      <Weight>1000000</Weight>
    </Task>
    <Task ID="T3">
      <Start>2018-10-07T20:00:00</Start>
      <End>2018-10-08T06:00:00</End>
      <Weight>1000000</Weight>
    </Task>
  </Tasks>
  <Employees>
    <Employee ID="0">
      <ContractID>C1</ContractID>
      <ContractID>C2</ContractID>
    </Employee>
    <Employee ID="1">
      <ContractID>C2</ContractID>
    </Employee>
    <Employee ID="2">
      <ContractID>C2</ContractID>
    </Employee>
    <Employee ID="3">
      <ContractID>C2</ContractID>
    </Employee>
    <Employee ID="4">
      <ContractID>C2</ContractID>
    </Employee>
  </Employees>
  <Contracts>
    <Contract ID="C1">
      <ShiftLengths>
        <Min>
          <Length>360</Length>
          <Label>Min 6h shifts</Label>
          <Weight function="Linear">1</Weight>
        </Min>
        <Max>
          <Length>750</Length>
          <Label>Max 12.5h shifts</Label>
        </Max>
      </ShiftLengths>
    </Contract>
    <Contract ID="C2">
      <MinRestTime>660</MinRestTime>
      <MinRestInPeriod start="2018-10-07T00:00:00" end="2018-10-14T00:00:00" 
                       label="An unbroken rest period of 45 hours every week">2700</MinRestInPeriod>
      <DailyRest dayStart="03:00" label="Min 11 hours continuous rest in 24hrs">660</DailyRest>
      <ShiftLengths>
        <Min>
          <Length>510</Length>
          <Label>Min 8.5h shifts</Label>
          <Weight function="Linear">1</Weight>
        </Min>
        <Max>
          <Length>750</Length>
          <Label>Max 12.5h shifts</Label>
        </Max>
      </ShiftLengths>
      <Workload>
        <TimeUnits>
          <PeriodStart>2018-10-07</PeriodStart>
          <PeriodEnd>2018-10-13</PeriodEnd>
          <Max>
            <Count>2550</Count>
            <Label>Max 42.5 hrs</Label>
          </Max>
        </TimeUnits>
      </Workload>
    </Contract>
  </Contracts>
  <FixedAssignments>
    <Employee ID="0">
      <NoShift>
        <Start>2018-10-07T08:00</Start>
        <End>2018-10-08T12:30</End>
      </NoShift>
      <NoShift>
        <Start>2018-10-09T14:00</Start>
        <End>2018-10-13T19:00</End>
      </NoShift>
    </Employee>
    <Employee ID="1">
      <NoShift>
        <Start>2018-10-07T08:00</Start>
        <End>2018-10-13T19:00</End>
      </NoShift>
      <Task ID="T3"/>
      <NotTask ID="T2"/>
    </Employee>
  </FixedAssignments>
</ScheduleSolver>

<Tasks>

The tasks to be assigned. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in current versions).

Parents : ScheduleSolver

Attributes

None

Elements

0 or more Task elements.

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

Example

<Tasks>
  <Task ID="L1">
    <Start>2018-10-07T06:00:00</Start>
    <End>2018-10-07T20:00:00</End>
    <UnassignedWeight>1000000</UnassignedWeight>
  </Task>
  <Task ID="N1">
    <Start>2018-10-07T08:00:00</Start>
    <End>2018-10-08T06:00:00</End>
    <UnassignedWeight>1000000</UnassignedWeight>
  </Task>
  <Task ID="E1">
    <Start>2018-10-07T04:00:00</Start>
    <End>2018-10-07T16:00:00</End>
    <UnassignedWeight>1000000</UnassignedWeight>
  </Task>
</Tasks>

<Task>

A task definition. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in current versions).

Parents : Tasks

Attributes

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

Elements

Task contains the following elements in any order:

Name Required Type Description Ver.
<Start> Required DateTime The task's start time. 1.0+
<End> Optional DateTime The tasks's end time. 1.0+
<Worktime> Optional NonNegativeDouble In minutes, the total time counted as working time. Since version 1.6+, Worktime can optionally have an attribute 'contract' to define the worktime for this task when it is assigned to an employee with the specified contract. 1.2+
<UnassignedWeight> Optional NonNegativeDouble The penalty if this task is not assigned. 1.3+
<AssignedWeight> Optional NonNegativeDouble The penalty if this task is assigned. 1.3+
<Skills> Optional Skills The skills, qualifications, experience, training, group etc required by employees for this task. 1.4+
<ShiftType> Optional ID The task's ShiftType. 1.6+

Example

  <Task ID="E1">
    <Start>2021-10-07T06:00:00</Start>
    <End>2021-10-07T16:00:00</End>
    <UnassignedWeight>1000000</UnassignedWeight>
    <Skills>
      <Skill>Skill1</Skill>
      <Skill>Skill2</Skill>
    </Skills>
    <ShiftType>EarlyShift</ShiftType>
    <Worktime contract="C1">600</Worktime>
    <Worktime contract="C2">540</Worktime>
    <Worktime>570</Worktime>
  </Task>

<Skills>

The skills, qualifications, experience, training, group etc required by employees for a task. Skills for each employee are defined in Employees.

Parents : Task

Attributes

None

Elements

Skills contains one or more <Skill> elements.

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

Example

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

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

Attributes

None

Elements

0 or more Shift elements.

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

Example

<ShiftTypes>
  <Shift ID="N">
    <Name>Night Shift</Name>
    <Label>N</Label>
    <MinEnd>23:00</MinEnd>
    <MaxEnd>1.08:00</MaxEnd>
  </Shift>
  <Shift ID="L">
    <Name>Late Shift</Name>
    <Label>L</Label>
    <MinEnd>18:00</MinEnd>
    <MaxEnd>23:00</MaxEnd>
  </Shift>
  <Shift ID="E">
    <Name>Early Shift</Name>
    <Label>E</Label>
    <MaxStart>06:00</MaxStart>
  </Shift>
  <Shift ID="D">
    <Name>Day Shift</Name>
    <Label>D</Label>
  </Shift>
</ShiftTypes>

<Shift>

A shift type definition.

Parents : ShiftTypes

Attributes

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

Elements

Shift contains the following elements in any order:

Name Required Type Description Ver.
<Name> Optional string A name for this shift. 1.0+
<Label> Optional string A label for the shift when displaying schedules. The ID is used if this element is omitted. 1.0+
<Color> Optional string A colour for the shift when displaying schedules. Any valid HTML colour may be used. 1.0+
<MinStart> Optional TimeOfDay A shift must start at or after this time to be categorised as this shift type. 1.0+
<MaxStart> Optional TimeOfDay A shift must start before or at this time to be categorised as this shift type. 1.0+
<MinEnd> Optional TimeSpan A shift must end at or after this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. 1.0+
<MaxEnd> Optional TimeSpan A shift must end before or at this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. 1.0+
<MinLength> Optional NonNegativeDouble In minutes. A shift must be at least this length to be categorised as this shift type. 1.0+
<MaxLength> Optional NonNegativeDouble In minutes. A shift must be at most this length to be categorised as this shift type. 1.0+

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>

<ShiftGroups>

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

Parents : ScheduleSolver

Attributes

None

Elements

ShiftGroups contains zero or more <ShiftGroup> elements.

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

Example

<ShiftGroups>
  <ShiftGroup ID="N">
    <Shift>N1</Shift>
    <Shift>N2</Shift>
  </ShiftGroup>
  <ShiftGroup ID="L">
    <Shift>L1</Shift>
    <Shift>L2</Shift>
    <Shift>L3</Shift>
  </ShiftGroup>
  <ShiftGroup ID="E">
    <Shift>E1</Shift>
    <Shift>E2</Shift>
    <Shift>E3</Shift>
  </ShiftGroup>
</ShiftGroups>

<ShiftGroup>

A group of shift types.

Parents : ShiftGroups

Attributes

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

Elements

ShiftGroup contains one or more <Shift> elements.

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

Example

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

<Contracts>

Contracts contain the constraints on the employees' work schedules.

Parents : ScheduleSolver

Attributes

None

Elements

Contracts contains zero or more <Contract> elements.

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

Example

<Contracts>
  <Contract ID="C1">
    <ShiftLengths>
      <Min>
        <Length>300</Length>
        <Label>Shift must not be less than 5h</Label>
        <Weight function="quadratic">100</Weight>
      </Min>
      <Max>
        <Length>480</Length>
        <Label>Shifts must be more than 8h</Label>
        <Weight function="quadratic">100</Weight>
      </Max>
    </ShiftLengths>
  </Contract>
  <Contract ID="C2">
    <ShiftLengths>
      <Min>
        <Length>480</Length>
        <Label>Shift must not be less than 8h</Label>
        <Weight function="quadratic">100</Weight>
      </Min>
      <Max>
        <Length>540</Length>
        <Label>Shifts must be more than 9h</Label>
        <Weight function="quadratic">100</Weight>
      </Max>
    </ShiftLengths>
  </Contract>
</Contracts>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract. An employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee.

Parents : Contracts

Attributes

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

Elements

Contract contains zero or more of the following elements in any order.

Name Required Type Description Ver.
<Label> Optional string A label for this contract which is used when displaying solutions. 1.0+
<MultipleTasksPerShift/> Optional MultipleTasksPerShift By default an employee can be assigned a maximum of one task in each shift. If this tag is included though, then an employee's shifts can contain multiple tasks. 1.7+
<MultipleShiftsPerDay/> Optional MultipleShiftsPerDay By default an employee can be assigned a maximum of one shift per day. If this tag is included though, then the employee can be assigned more than one shift on a single day. If multiple shifts are assigned on a day then the combined shifts are considered when calculating the start time, end time, shift length, shift type etc. 1.0+
<MinRestTime> Optional NonNegativeDouble The minimum amount of rest time (non-work time) required between shifts on each day. The time is in minutes. This is a hard constraint. 1.0+
<MinRestInPeriod> Optional MinRestInPeriod A minimum amount of consecutive rest required within a defined period. 1.0+
<DailyRest> Optional DailyRest A minimum amount of continuous rest (non-work) time required during 24 hours. 1.0+
<Workload> Optional Workload Minimum and maximum total working time between any two dates in the planning period. 1.0+
<ShiftStartTimes> Optional ShiftStartTimes Earliest and latest shift start times (optionally for each day). 1.0+
<ShiftEndTimes> Optional ShiftEndTimes Earliest and latest shift finish times (optionally for each day). 1.0+
<ShiftStartEndTimes> Optional ShiftStartEndTimes Valid combined start and finish times for shifts (optionally for each day). 1.0+
<ShiftLengths> Optional ShiftLengths Minimum and maximum shift lengths (optionally for each day). 1.0+
<UseIfNeeded> Optional UseIfNeeded If this is used then employees with this contract will only be assigned shifts if they are needed. The constraint is given a weight and the employee will only be scheduled if doing so enables other constraints with higher weights to be satisfied. The constraint can be used to leave certain employees unscheduled if possible (for example, 'temporary' or 'dummy employees'). 1.0+
<MaxTot> Optional MaxTot Used for modelling constraints such as a maximum number of days on or off or a maximum number of shifts of a particular type (optionally between two dates in the planning period). 1.0+
<MinTot> Optional MinTot Used for modelling constraints such as a minimum number of days on or off or a minimum number of shifts of a particular type (optionally between two dates in the planning period). 1.0+
<MaxSeq> Optional MaxSeq Used for modelling constraints such as a maximum number of consecutive days on or off or a maximum number of consecutive shifts of a particular type. 1.0+
<MinSeq> Optional MinSeq Used for modelling constraints such as a minimum number of consecutive days on or off or a minimum number of consecutive shifts of a particular type. 1.0+
<Sequence> Optional Sequence A flexible constraint which can model a variety of rules on an employee's work schedule. 1.2+

Example

<Contract ID="C1">
  <MinRestTime>840</MinRestTime>
  <ShiftStartTimes>
    <Min>
      <Time>07:00</Time>
      <Label>Shifts must start after 7am</Label>
      <Weight>10</Weight>
    </Min>
    <Max>
      <Time>12:00</Time>
      <Label>Shifts must start before 12pm</Label>
      <Weight>10</Weight>
    </Max>
  </ShiftStartTimes>
  <ShiftLengths>
    <Min>
      <Length>480</Length>
      <Label>Shifts must not be less than 8h</Label>
      <Weight function="quadratic">100</Weight>
    </Min>
    <Max>
      <Length>720</Length>
      <Label>Shifts must not be more than 12h</Label>
      <Weight function="quadratic">100</Weight>
    </Max>
  </ShiftLengths>
  <Workload>
    <TimeUnits>
      <Max>
        <Count>2250</Count>
        <Label>Max 37.5 hours</Label>
        <Weight function="quadratic">1</Weight>
      </Max>
      <Min>
        <Count>2250</Count>
        <Label>Min 37.5 hours</Label>
        <Weight>1</Weight>
      </Min>
    </TimeUnits>
  </Workload>
  <MaxTot label="Max 6 shifts per week" value="6" shift="$" start="0" end="6" weight="100000"/>
  <MinTot label="Min 5 shifts per week" value="5" shift="$" start="0" end="6" weight="100000"/>
  <MaxTot label="Max 5 shifts per week (low priority)" value="5" shift="$" start="0" end="6" weight="100"/>
  <MinSeq label="Min 4 consecutive shifts" value="4" shift="$" weight="100000"/>
  <MaxSeq label="Max 6 consecutive shifts" value="6" shift="$" weight="100000"/>
  <MaxSeq label="Max 5 consecutive shifts (low priority)" value="5" shift="$" weight="100"/>
  <MinSeq label="Min 2 consecutive rest days (low priority)" value="2" shift="-" weight="100"/>
  <MaxSeq label="Max 3 consecutive rest days" value="3" shift="-" weight="100000"/>
</Contract>

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

Name Required Type Description Ver.
<Min> Optional Min The earliest a shift can start (soft constraint or hard constraint). 1.0+
<Max> Optional Max The latest a shift can start (soft constraint or hard constraint). 1.0+

Example

<ShiftStartTimes>
  <Min>
    <Time>07:00</Time>
    <Label>Shift must start after 7am</Label>
    <Weight>10</Weight>
  </Min>
  <Min>
    <Time>08:00</Time>
    <Label>Ideally shift should start at 8am</Label>
    <Weight>1</Weight>
  </Min>
  <Max>
    <Time>08:00</Time>
    <Label>Ideally shift should start at 8am</Label>
    <Weight>1</Weight>
  </Max>
  <Max>
    <Time>12:00</Time>
    <Label>The latest the shift can start is 12pm</Label>
    <Weight>10</Weight>
  </Max>
</ShiftStartTimes>

<Min>

The earliest a shift can start.

If the <Weight> element is not used then it is a hard constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a shift starts before the minimum time and the function type specified is linear then the penalty function value will be the difference in minutes between the shift's start time and the minimum start time multiplied by the weight. If the function is quadratic it will be the difference in minutes squared and then multiplied by the weight.

Parents : ShiftStartTimes

Attributes

None

Elements

Min contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another earliest shift start time constraint for that day).

Name Required Type Description Ver.
<Time> Required TimeOfDay The earliest start time. 1.0+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. 1.0+

Example

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

<Max>

The latest a shift can start.

If the <Weight> element is not used then it is a hard constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a shift starts after the maximum time and the function type specified is linear then the penalty function value will be the difference in minutes between the shift's start time and the maximum start time multiplied by the weight. If the function is quadratic it will be the difference in minutes squared and then multiplied by the weight.

Parents : ShiftStartTimes

Attributes

None

Elements

Max contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another latest shift start time constraint for that day).

Name Required Type Description Ver.
<Time> Required TimeOfDay The latest start time. 1.0+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. 1.0+

Example

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

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

Name Required Type Description Ver.
<Min> Optional Min The earliest a shift can end (soft constraint or hard constraint). 1.0+
<Max> Optional Max The latest a shift can end (soft constraint or hard constraint). 1.0+

Example

<ShiftEndTimes>
  <Min>
    <Time>16:00</Time>
    <Label>Must finish at or after 16:00 on day 0</Label>
    <Weight>1000</Weight>
    <DayIndex>0</DayIndex>
  </Min>
  <Max>
    <Time>17:00</Time>
    <Label>Must finish at or before 17:00 on day 0</Label>
    <Weight>1000</Weight>
    <DayIndex>0</DayIndex>
  </Max>
</ShiftEndTimes>

<Min>

The earliest a shift can finish.

If the <Weight> element is not used then it is a hard constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a shift ends before the minimum time and the function type specified is linear then the penalty function value will be the difference in minutes between the shift's end time and the minimum end time multiplied by the weight. If the function is quadratic it will be the difference in minutes squared and then multiplied by the weight.

Parents : ShiftEndTimes

Attributes

None

Elements

Min contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another earliest shift end time constraint for that day).

Name Required Type Description Ver.
<Time> Required TimeSpan The earliest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. 1.0+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. (The day is the day that the shift starts on). 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. (The day is the day that the shift starts on). 1.0+

Example

<Min>
  <Time>16:00</Time>
  <Label>Must finish at or after 16:00 on day 0</Label>
  <Weight>1000</Weight>
  <DayIndex>0</DayIndex>
</Min>

<Max>

The latest a shift can finish.

If the <Weight> element is not used then it is a hard constraint.

The <Weight> element can optionally have an attribute function to set how to calculate the penalty function value. For example if a shift ends after the maximum time and the function type specified is linear then the penalty function value will be the difference in minutes between the shift's end time and the maximum end time multiplied by the weight. If the function is quadratic it will be the difference in minutes squared and then multiplied by the weight.

Parents : ShiftEndTimes

Attributes

None

Elements

Max contains in any order a <Time> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another latest shift end time constraint for that day).

Name Required Type Description Ver.
<Time> Required TimeSpan The latest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. 1.0+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. (The day is the day that the shift starts on). 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. (The day is the day that the shift starts on). 1.0+

Example

<Max>
  <Time>17:00</Time>
  <Label>Must finish at or before 17:00 on day 0</Label>
  <Weight>1000</Weight>
  <DayIndex>0</DayIndex>
</Max>

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

Example

<ShiftStartEndTimes>
  <Shift>
    <MinStart>06:00</MinStart>
    <MaxStart>06:00</MaxStart>
    <MinEnd>14:00</MinEnd>
    <MaxEnd>14:00</MaxEnd>
  </Shift>
  <Shift>
    <MinStart>14:00</MinStart>
    <MaxStart>14:00</MaxStart>
    <MinEnd>20:00</MinEnd>
    <MaxEnd>20:00</MaxEnd>
  </Shift>
  <Shift>
    <MinStart>20:00</MinStart>
    <MaxStart>20:00</MaxStart>
    <MinEnd>1.06:00</MinEnd>
    <MaxEnd>1.06:00</MaxEnd>
  </Shift>
</ShiftStartEndTimes>

<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.0+
day Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. This is the day that the shift starts on. The first day in the scheduling horizon is day zero. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. 1.0+
startDate Optional date The start date for a range of days that this constraint applies to. Specified in the format : YYYY-MM-DD. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. 1.0+
endDate Optional date The end date for a range of days that this constraint applies to. Specified in the format : YYYY-MM-DD. If neither the date or startDate or endDate attribute or the day attribute are used then the constraint applies to every day in the planning horizon. 1.0+

Elements

Shift contains in any order a <MinStart>, <MaxStart>, <MinEnd> and a <MaxEnd> element (all optional).

Name Required Type Description Ver.
<MinStart> Optional TimeOfDay The earliest start time. 1.0+
<MaxStart> Optional TimeOfDay The latest start time. 1.0+
<MinEnd> Optional TimeSpan The earliest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. 1.0+
<MaxEnd> Optional TimeSpan The latest end time. For shifts which can finish the next day or later use the day prefix of TimeSpan. For example for midnight the next day use 1.00:00 or for 06:00AM the next day use 1.06:00. 1.0+

Example

<Shift startDate="2018-11-12" endDate="2018-11-19">
  <MinStart>06:00</MinStart>
  <MaxStart>06:00</MaxStart>
  <MinEnd>14:00</MinEnd>
  <MaxEnd>14:00</MaxEnd>
</Shift>

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

Example

<ShiftLengths>
  <Min>
    <Length>480</Length>
    <Label>Shift must not be less than 8h</Label>
    <Weight function="quadratic">100</Weight>
  </Min>
  <Min>
    <Length>540</Length>
    <Label>Try and assign shifts of length 9h</Label>
    <Weight function="quadratic">1</Weight>
  </Min>
  <Max>
    <Length>540</Length>
    <Label>Try and assign shifts of length 9h</Label>
    <Weight function="quadratic">1</Weight>
  </Max>
  <Max>
    <Length>720</Length>
    <Label>Shifts must be less than 12h</Label>
    <Weight function="quadratic">100</Weight>
  </Max>
</ShiftLengths>

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

Parents : ShiftLengths

Attributes

None

Elements

Min contains in any order a <Length> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another minimum shift length constraint for that day).

Name Required Type Description Ver.
<Length> Required NonNegativeDouble The minimum shift length in minutes. 1.0+
<Weight> Required NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. 1.0+

Example

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

<Max>

A maximum shift length.

If the <Weight> element is not used then it is a hard constraint.

The <Weight> element can optionally have an attribute function to indicate how to calculate the penalty function value. For example if a shift is longer than the maximum length and the function type specified is linear then the penalty function value will be the difference in minutes between the shift's length and the maximum shift length multiplied by the weight. If the function is quadratic it will be the difference in minutes squared and then multiplied by the weight.

Parents : ShiftLengths

Attributes

None

Elements

Max contains in any order a <Length> and <Weight> element (both required) a <Label> element (optional) and a <DayIndex> or <Date> element (both optional). If neither <DayIndex> or <Date> are used then the constraint applies to every day in the scheduling horizon (unless there is another minimum shift length constraint for that day).

Name Required Type Description Ver.
<Length> Required NonNegativeDouble The maximum shift length in minutes. 1.0+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
<Label> Optional string A label for the constraint used when displaying a solution. 1.0+
<DayIndex> Optional NonNegativeInteger The day in the scheduling horizon that this constraint applies to. The first day in the scheduling horizon is day zero. 1.0+
<Date> Optional date The day in the scheduling horizon that this constraint applies to. Specified in the format : YYYY-MM-DD. 1.0+

Example

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

<MultipleShiftsPerDay>

By default, an employee can be assigned a maximum of one shift per day. Use this tag to allow multiple shifts per day.

Parents : Contract

Attributes

Name Required Type Description Ver.
on Optional Boolean Set as true to allow multiple shifts per day and false to restrict to a maximum of one shift per day. 1.7+

Example


<MultipleShiftsPerDay on="true"/>

<MultipleTasksPerShift>

By default an employee can be assigned a maximum of one task in each shift. If this tag is included though, then an employee's shifts can contain multiple tasks.

Parents : Contract

Attributes

Name Required Type Description Ver.
on Optional Boolean Set as true to allow multiple tasks per shift and false to restrict to a maximum of one task per shift. 1.7+

Example


<MultipleTasksPerShift on="true"/>

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

Parents : Contract

Attributes

Name Required Type Description Ver.
weight Required NonNegativeDouble The weight. The employee will only be assigned shifts if doing so reduces the solution's penalty by more than this value. 1.0+
start Optional NonNegativeInteger A day index in the planning period specified as an integer (the planning period starts on day zero). If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or after this day in the planning period. This can be useful if the end of the previous planning period is included in this planning period. 1.0+
startDate Optional date A day index in the planning period given as a date. Specified in the format : YYYY-MM-DD. If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or after this day in the planning period. This can be useful if the end of the previous planning period is included in this planning period. 1.0+
end Optional NonNegativeInteger A day index in the planning period specified as an integer (the planning period starts on day zero). If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or before this day in the planning period. 1.0+
endDate Optional date A day index in the planning period given as a date. Specified in the format : YYYY-MM-DD. If this is used then the employee will only be considered as being scheduled if they receive one or more shifts on or before this day in the planning period. 1.0+
label Optional string A label for the constraint. The label is only used in visualisations such as RosterViewer. 1.0+
shiftGroup Optional string If this is used then the employee will only be considered as being scheduled if they receive one or more shift types from this group. For example, if there was a 'vacation' shift and the shift type group did not include the 'vacation' shift type then the employee would not be considered as being scheduled if they had only 'vacation' shift types. The ID is defined in ShiftGroups.

It is also possible to specify a shift type group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). 		1.0+
shift Optional string If this is used then the employee will only be considered as being scheduled if they receive one or more of this shift type. The ID is defined in ShiftTypes.

It is also possible to specify a shift type group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N"). 		1.0+

Example


<UseIfNeeded weight="99999" label="Only use this employee if needed" startDate="2014-03-10"/>

<MaxTot>, <MinTot>, <MaxSeq>, <MinSeq>

<MaxTot> and <MinTot> are used to model maximum and minimum total numbers of days on or off or a particular shift type.
<MaxSeq> and <MinSeq> are used to model maximum and minimum consecutive numbers of days on or off or a particular shift type.

Parents : Contract

Attributes

Name Required Type Description Ver.
value Required NonNegativeInteger The maximum or minimum. 1.0+
weight Required NonNegativeDouble The weight for the constraint. 1.0+
function Optional string The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.0+
shift Optional string Indicates whether the constraint applies to days on, days off or specific shift types. Possible values are :
$   Working days (a day with a shift starting on it).
-   Days off (a day without a shift starting on it).
A shift type ID    Specified using an ID defined in ShiftTypes.
A shift type group ID    Specified using an ID defined in ShiftGroups.

It is also possible to specify a shift type group as a comma separated list of shift type ID's (e.g. "E,D,L,N"). 		1.0+
start Optional NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used then the constraint only applies on or after the this date in the planning period. 1.0+
end Optional NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). If this is used then the constraint only applies on or before this date in the planning period. 1.0+
label Optional string A label for the constraint. The label is only used in visualisations such as RosterViewer. 1.0+

Example

<MaxTot label="Max 4 night shifts" value="4" shift="N" weight="100000"/>
  
<MaxTot label="Max 6 shifts in week one" value="6" shift="$" 
        start="2014-03-10" end="2014-03-16" weight="100000"/>
  
<MinTot label="Min 4 shifts in week one" value="4" shift="$" 
        start="2014-03-10" end="2014-03-16" weight="100000"/>
  
<MinSeq label="Min 2 consecutive shifts" value="2" shift="$" weight="1000"/>
  
<MaxSeq label="Max 5 consecutive shifts" value="5" shift="$" weight="100000"/>
  
<MinSeq label="Min 2 consecutive days off" value="2" shift="-" weight="100"/>

<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 Ver.
<TimeUnits> Required TimeUnits TimeUnits specifies a minimum and/or maximum total amount of work time that can be assigned to the employee between any two dates in the planning period. 1.0+

Example

<Workload>
  <TimeUnits>
    <Max>
      <Count>2100</Count>
      <Label>Max 2100 mins</Label>
      <Weight function="quadratic">100</Weight>
    </Max>
    <Min>
      <Count>2100</Count>
      <Label>Min 2100 mins</Label>
      <Weight>100</Weight>
    </Min>
  </TimeUnits>
</Workload>

<TimeUnits>

TimeUnits specifies a minimum and/or maximum total amount of work time that can be assigned to the employee between any two dates in the planning period. The dates can be specified using the day number in the planning horizon or actual dates. The first day in the planning period is day zero. A day starts at midnight (00:00).

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

Parents : Workload

Attributes

None

Elements

Workload contains a <Min> and/or a <Max> element (in either order) and a <PeriodStart> and <PeriodEnd> (both also optional).

The default start day is day zero if <PeriodStart> is omitted. The default end day is the last day in the planning horizon if <PeriodEnd> is omitted.

Name Required Type Description Ver.
<Min> Optional Min The minimum number of minutes worked. 1.2+
<Max> Optional Max The maximum number of minutes worked. 1.2+
<PeriodStart> Optional string The first day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. 1.2+
<PeriodEnd> Optional string The last day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. 1.2+

Example

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

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

Parents : TimeUnits

Attributes

None

Elements

Min contains the following elements in any order.

Name Required Type Description Ver.
<Count> Required NonNegativeDouble The minimum number of minutes to work. 1.2+
<Weight> Required NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.2+
<Label> Optional string A label for the constraint for when displaying a solution. 1.2+

Example

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

<Max>

A maximum number of minutes to work.

If the <Weight> element is not used then it is a hard constraint.

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

Parents : TimeUnits

Attributes

None

Elements

Max contains the following elements in any order.

Name Required Type Description Ver.
<Count> Required NonNegativeDouble The maximum number of minutes to work. 1.2+
<Weight> Optional NonNegativeDouble A value to represent the constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.2+
<Label> Optional string A label for the constraint for when displaying a solution. 1.2+

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.

If the <Weight> element is not used then it is a hard constraint.

Parents : Contract

Attributes

Name Required Type Description Ver.
start Required DateTime The start of the period the rest is required in. 1.0+
end Required DateTime The end of the period the rest is required in. 1.0+
weight Optional NonNegativeDouble The weight for the constraint. If the constraint is not satisfied then the weight is multiplied by the difference in minutes between the longest rest provided and the minimum rest required. 1.0+
label optional string A label for the constraint when displaying a solution. 1.0+
splitShiftRest optional Boolean If true then the time between split-shifts is considered as rest. False if omitted. 1.0+

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>

<DailyRest>

A minimum amount of continuous rest (non-work) time in minutes required within 24 hours.

Parents : Contract

Attributes

Name Required Type Description Ver.
dayStart Optional TimeOfDay The time of day that the 24 hour period starts. If this attribute is omitted then the default value is 00:00. 1.0+
weight Optional NonNegativeDouble A value to represent this constraint's priority. If this attribute is omitted then the constraint is considered to be a hard constraint. 1.0+
label Optional string A label for this constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML). 1.0+

Type

Double

Example

<Contract ID="C1">
  <DailyRest dayStart="03:00" label="Min 11hrs continuous rest in 24hrs" weight="10000">660</DailyRest>
</Contract>

<Sequence>

This is a general and flexible constraint which can model a wide variety of rules in an employee's schedule.

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

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

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

A pattern can optionally also include a start day or date which restricts the pattern to starting on that day. Many scheduling requirements can be modelled using this constraint. Examples of the different requirements that can be modelled using this constraint can be found in the example instances.

Parents : Contract

Attributes

None

Elements

Sequence contains a <Min> and/or a <Max> element (in either order) a <PeriodStart> a <PeriodEnd> and one or more <Pattern> elements.

The default start day is day zero if <PeriodStart> is omitted. The default end day is the last day in the planning horizon if <PeriodEnd> is omitted.

Name Required Type Description Ver.
<Min> Optional Min The minimum number of matches of the pattern(s). 1.2+
<Max> Optional Max The maximum number matches of the pattern(s). 1.2+
<PeriodStart> Optional string The first day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. 1.2+
<PeriodEnd> Optional string The last day of the period in the planning period that this constraint applies to (the day is inclusive). It can be specified as a NonNegativeInteger (the planning period starts on day zero) or as a date in the format : YYYY-MM-DD. 1.2+
<Pattern> Required Pattern A a sequences of shift types and/or days off. 1.2+

Example

<Sequence> 
  <Max count="3" weight="1000" label="Max three working Sundays"/>
  <Pattern>
    <Start>Sunday</Start>
    <Shift>$</Shift>
  </Pattern>
</Sequence>
        
<Sequence>
  <Max count="14" weight="1000" label="Max 14 shifts"/>
  <Pattern>
    <Shift>$</Shift>
  </Pattern>
</Sequence>
  
<Sequence>
  <Max count="4" weight="1000" label="Max four nights"/>
  <Pattern>
    <Shift>N</Shift>
  </Pattern>
</Sequence>
  
<Sequence>
  <Max count="0" weight="10" label="Min two consecutive days off"/>
  <Pattern>
    <Start>0</Start>
    <Shift>-</Shift>
    <Shift>$</Shift>
  </Pattern>
  <Pattern>
    <Shift>$</Shift>
    <Shift>-</Shift>
    <Shift>$</Shift>
  </Pattern>
</Sequence>

<Sequence>
  <Max count="0" weight="1000" label="Max six consecutive days"/>
  <Pattern>
    <Shift>$</Shift>
    <Shift>$</Shift>
    <Shift>$</Shift>
    <Shift>$</Shift>
    <Shift>$</Shift>
    <Shift>$</Shift>
    <Shift>$</Shift>
  </Pattern>
</Sequence>

<Sequence>
  <Max count="0" weight="1000" label="Work both days of the weekend, or have both days off"/>
  <Pattern>
    <Start>Saturday</Start>
    <Shift>$</Shift>
    <Shift>-</Shift>
  </Pattern>
  <Pattern>
    <Start>Saturday</Start>
    <Shift>-</Shift>
    <Shift>$</Shift>
  </Pattern>
</Sequence>

<Sequence>
  <Max count="0" weight="1000" label="No night shift before a weekend off"/>
  <Pattern>
    <Start>Friday</Start>
    <Shift>N</Shift>
    <Shift>-</Shift>
    <Shift>-</Shift>
  </Pattern>
</Sequence>

<Sequence>
  <Max count="0" weight="1000" label="At least two free days after a night shift"/>
  <Pattern>
    <Shift>N</Shift>
    <Shift>-</Shift>
    <Shift>$</Shift>
  </Pattern>
</Sequence>
  
<Sequence>
  <Max count="2" weight="1000" label="Max two consecutive weekends on"/>
  <PeriodStart>5</PeriodStart>
  <PeriodEnd>20</PeriodEnd>
  <Pattern>
    <Start>Saturday</Start>
    <Shift>$</Shift>
    <Shift>-</Shift>
  </Pattern>
  <Pattern>
    <Start>Saturday</Start>
    <Shift>-</Shift>
    <Shift>$</Shift>
  </Pattern>
  <Pattern>
    <Start>Saturday</Start>
    <Shift>$</Shift>
    <Shift>$</Shift>
  </Pattern>
</Sequence>

<Pattern>

Pattern is a sequence of shift types and days off.

Parents : Sequence

Attributes

None

Elements

Pattern contains any number of <Start>, or <StartExcludes> elements (all optional) followed by one or more <Shift> and/or <NotShift> elements (in any order).

If neither <Start> or <StartExcludes> is used then the pattern will be matched when it starts on any day in the planning period.

Name Required Type Description Ver.
<Start> Optional string The pattern is only matched if it starts on this day in the planning period. The day can be specified as an index in the horizon as a NonNegativeInteger, or as a date, in the format YYYY-MM-DD, or as a day of the week, as 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', or 'Sunday'. A comma-separated list of values can also be used to represent multiple possible start days. 1.2+
<StartExcludes> Optional string The pattern is only matched if it starts on any day in the planning period except the days, dates and days of the week specified. The day can be specified as an index in the horizon as a NonNegativeInteger, or as a date, in the format YYYY-MM-DD, or as a day of the week, as 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', or 'Sunday'. A comma-separated list of values can also be used to represent multiple possible start days. 1.2+
<Shift> Optional string Possible values are :
A shift type ID  Match this shift type. The shift type is specified using an ID defined in ShiftTypes.
$ Match any shift type (but not a day off).
- Match a day off.
* Match any shift type or a day off.
It is also possible to specify a shift type group as a comma-separated list of shift type ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID. 		1.2+
<NotShift> Optional string Match anything but this shift type (including a day without a shift). The shift type is specified using an ID defined in ShiftTypes.
It is also possible to specify a shift type group as a comma-separated list of shift type ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID, meaning match anything but one of the shift types in this group of shift types (including a day without a shift). 		1.2+

Example

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

<Min>, <Max>

Specifies a minimum or maximum value for a constraint.

Parents : Sequence

Attributes

Name Required Type Description Ver.
count Required NonNegativeInteger The maximum or minimum. 1.2+
weight Required NonNegativeDouble The weight for the constraint. 1.2+
function Optional string The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used. 1.2+
label Optional string A label for the constraint. The label is only used in visualisations such as RosterViewer. 1.2+

Example

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

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

<Employees>

The employees.

Parents : ScheduleSolver

Attributes

None

Elements

0 or more Employee elements.

Name Required Type Description Ver.
<Employee> Required Employee An employee. 1.0+

Example

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

<Employee>

An employee in the roster.

Parents : Employees

Attributes

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

Elements

Employee contains the following elements in any order.
More than one <ContractID> element can be included. If more than one <ContractID> is included then all the constraints in each contract apply to the employee.

Name Required Type Description Ver.
<ContractID> Optional string The ID of the Contract which contains the work regulations and preferences (constraints) for this employee. An employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee. 1.0+
<Name> Optional string A label for the employee when displaying the solution. The ID is used if this element is omitted. 1.0+
<Skills> Optional Skills The skills, qualifications, experience, training, group etc this employee has/belongs to. A task that has skills defined cannot be asigned to this employee unless the employee has all the required skills for the task (see Task). A skill can also have a penalty associated with it if the skill is used or not used for a task. 1.4+

Example

<Employee ID="E1">
  <ContractID>C1</ContractID>
  <ContractID>C2</ContractID>
  <Skills>
    <Skill>Skill1</Skill>
    <Skill>Skill2</Skill>
  </Skills>
</Employee>

<Skills>

The skills, qualifications, experience, training, group etc this employee has/belongs to. A task that has skills defined cannot be asigned to this employee unless the employee has all the required skills for the task (see Task). A skill can also have a penalty associated with it if the skill is used or not used for a task.

Parents : Employee

Attributes

Attributes

Name Required Type Description Ver.
penaltyForUsing Optional NonNegativeDouble The penalty if a task requiring this skill is assigned to this employee. 1.9+
penaltyForNotUsing Optional NonNegativeDouble The penalty if a task does not require this skill but the task is assigned to this employee. 1.9+

Elements

Skills contains one or more <Skill> elements.

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

Example

<Skills>
  <Skill penaltyForNotUsing="1" penaltyForUsing="0">Cashier</Skill>
  <Skill penaltyForUsing="0.25">Greeting</Skill>
  <Skill penaltyForUsing="0.5">Filling</Skill>
</Skills>

<Requests>

Requests for specific days on or off, or for specific shift types on or off.

Parents : ScheduleSolver

Attributes

None

Elements

Contains zero or more <OffDay>, <OnDay>, <OffShiftType>, <OnShiftType> elements in any order.

Name Required Type Description Ver.
<OffDay> Optional OffDay A day off constraint. 1.2+
<OnDay> Optional OnDay A day on constraint. 1.2+
<OffShiftType> Optional OffShiftType A shift type off constraint. (Pre version 1.7 this element was named <OffShift> but <OffShift> can still be used in current versions). 1.7+
<OnShiftType> Optional OnShiftType A shift type on constraint. (Pre version 1.7 this element was named <OnShift> but <OnShift> can still be used in current versions). 1.7+

Example

<Requests>
    
  <OffDay weight="1000" employee="A" date="2018-02-18"/>
  <OffDay weight="1000" employee="A" date="2"/>
    
  <OnDay weight="1000" employee="B" date="2018-02-18"/>
  <OnDay weight="1000" employee="B" date="2"/>
    
  <OffShiftType weight="1000" employee="C" date="2018-02-18" shift="E"/>
  <OffShiftType weight="1000" employee="C" date="2" shift="L"/>
    
  <OnShiftType weight="1000" employee="D" date="2018-02-17" shift="E"/>
  <OnShiftType weight="1000" employee="D" date="0" shift="E,L,D"/>
  <OnShiftType weight="1000" employee="D" date="1" shift="Grp1"/>

</Requests>

<OffDay>

A day off constraint. The employee must not have any shifts on this day.

Parents : Requests

Attributes

Name Required Type Description Ver.
employee Required string An Employee ID. 1.2+
date Required NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). 1.2+
weight Required NonNegativeDouble The weight for the constraint. 1.2+

Example

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

<OnDay>

A day on constraint. The employee must be working on this day.

Parents : Requests

Attributes

Name Required Type Description Ver.
employee Required string An Employee ID. 1.2+
date Required NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). 1.2+
weight Required NonNegativeDouble The weight for the constraint. 1.2+

Example

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

<OffShiftType>

A shift type off constraint. The employee must not be assigned the specified shift type. (Pre version 1.7 this element was named <OffShift> but <OffShift> can still be used in current versions).

Parents : Requests

Attributes

Name Required Type Description Ver.
employee Required string An Employee ID. 1.2+
shift Required string A ShiftType ID. 1.2+
date Required NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). 1.2+
weight Required NonNegativeDouble The weight for the constraint. 1.2+

Example

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

<OnShiftType>

A shift type on constraint. The employee must be assigned the specified shift type or one of several shift types. (Pre version 1.7 this element was named <OnShift> but <OnShift> can still be used in current versions).

Parents : Requests

Attributes

Name Required Type Description Ver.
employee Required string An Employee ID. 1.2+
shift Required string A ShiftType ID,
or a shift type group as a comma separated list of shift ID's (e.g. "E,D,L,N"),
or a ShiftGroup ID. 		1.2+
date Required NonNegativeInteger or date A day index in the planning period specified as an integer or as a date in the format : YYYY-MM-DD (the planning period starts on day zero). 1.2+
weight Required NonNegativeDouble The weight for the constraint. 1.2+

Example

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

<FixedAssignments>

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

Parents : ScheduleSolver

Attributes

None

Elements

FixedAssignments contains zero or more <Employee> elements.

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

Example

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

<Employee>

These are task assignments (or off assignments) which must be in an employee's schedule in the solution.

Parents : FixedAssignments

Attributes

Name Required Type Description Ver.
ID Required string The ID of the employee the assignments belong to. 1.0+

Elements

Employee contains zero or more <NoShift>, <Task> and/or <NotTask> elements.

Name Required Type Description Ver.
<NoShift> Optional NoShift A time period during which the employee must have no shifts assigned. 1.0+
<Task> Optional Task A pre-assigned task which must be assigned in the solution. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in current versions). 1.7+
<NotTask> Optional NotTask A task which must not be assigned to this employee. (Pre version 1.7 this element was named <NotShift> but <NotShift> can still be used in current versions). 1.7+

Example

  <Employee ID="1">
    <Task ID="T1" shiftID="S1"/>
    <Task ID="T2" shiftID="S1"/>
    <Task ID="T3" shiftID="S2"/>
    <Task ID="T4" shiftID="S2"/>
    <NotTask ID="T5"/>
    <NotTask ID="T6"/>
  </Employee>

<NoShift>

An employee must have no shifts assigned during this time period.

Parents : Employee

Attributes

None

Elements

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

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

Example

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

<Task>

A pre-assigned task which must be assigned in the solution. (Pre version 1.7 this element was named <Shift> but <Shift> can still be used in current versions).

Parents : Employee

Attributes

Name Required Type Description Ver.
ID Required string The task ID (defined in Tasks). 1.0+
shiftID Optional string Tasks with an identical shiftID will be assigned in the same shift. The shiftID defined here will also be used in the solution XML to identify this shift. 1.7+

Elements

None

Example

  <Employee ID="1">
    <Task ID="T1" shiftID="S1"/>
    <Task ID="T2" shiftID="S1"/>
    <Task ID="T3" shiftID="S2"/>
    <Task ID="T4" shiftID="S2"/>
  </Employee>

<NotTask>

A task which must not be assigned to this employee. (Pre version 1.7 this element was named <NotShift> but <NotShift> can still be used in current versions).

Parents : Employee

Attributes

Name Required Type Description Ver.
ID Required string The task ID (defined in Tasks). 1.0+

Elements

None

Example

  <Employee ID="1">
    <NotTask ID="T5"/>
    <NotTask ID="T6"/>
  </Employee>

Boolean

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.