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>.
  • Shifts. The shifts to be assigned. These are specified within the tag <Shifts>.
  • Employees. The employees available for assigning the shifts 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
ID Optional string An ID used to identify the instance.

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+
<Shifts> Optional Shifts The shifts to be assigned. 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+
<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+
<FixedAssignments> Optional FixedAssignments Shifts, 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+

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>
  <Shifts>
    <Shift ID="L1">
      <Start>2018-10-07T06:00:00</Start>
      <End>2018-10-07T20:00:00</End>
      <Weight>1000000</Weight>
    </Shift>
    <Shift ID="N1">
      <Start>2018-10-07T08:00:00</Start>
      <End>2018-10-08T06:00:00</End>
      <Weight>1000000</Weight>
    </Shift>
    <Shift ID="E1">
      <Start>2018-10-07T04:00:00</Start>
      <End>2018-10-07T16:00:00</End>
      <Weight>1000000</Weight>
    </Shift>
  </Shifts>
  <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">
      <MultipleShiftsPerDay/>
      <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>
          <RegionStartDate>2018-10-07</RegionStartDate>
          <RegionEndDate>2018-10-13</RegionEndDate>
          <Max>
            <Count>2550</Count>
            <Label>Max 42.5 hrs</Label>
          </Max>
        </TimeUnits>
      </Workload>
    </Contract>
  </Contracts>
  <FixedAssignments>
    <Employee>
      <EmployeeID>0</EmployeeID>
      <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>
      <Shift ID="N1"/>
      <NotShift ID="E1"/>
    </Employee>
  </FixedAssignments>
</ScheduleSolver>

<Shifts>

The shifts to be assigned.

Parents : ScheduleSolver

Attributes

None

Elements

0 or more Shift elements.

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

Example

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

<Shift>

A shift definition.

Parents : Shifts

Attributes

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

Elements

Shift contains the following elements in any order:

Name Required Type Description Ver.
<Start> Required DateTime The shift's start time. 1.0+
<Length> Optional string The shift's length in minutes. The End tag can be used instead. 1.0+
<End> Optional DateTime The shift's end time. The Length tag can be used instead. 1.0+
<Weight> Required NonNegativeDouble The penalty if this shift is not assigned. 1.0+

Example

  <Shift ID="E1">
    <Start>2018-10-07T04:00:00</Start>
    <End>2018-10-07T16:00:00</End>
    <Weight>1000000</Weight>
  </Shift>

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

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. 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+
<MultipleShiftsPerDay/> Optional Empty element If this tag is included 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+
<Patterns> Optional Patterns A flexible constraint which can model a wide variety of requirements on the employee's work schedule. 1.0+

Example

<Contract ID="C1">
  <MinRestTime>840</MinRestTime>
  <ShiftStartTimes>
    <Min>
      <Time>07:00</Time>
      <Label>Shifts must start after 7am</Label>
      <Weight>10</Weight>
    </Min>
    <Max>
      <Time>12:00</Time>
      <Label>Shifts must start before 12pm</Label>
      <Weight>10</Weight>
    </Max>
  </ShiftStartTimes>
  <ShiftLengths>
    <Min>
      <Length>480</Length>
      <Label>Shifts must not be less than 8h</Label>
      <Weight function="quadratic">100</Weight>
    </Min>
    <Max>
      <Length>720</Length>
      <Label>Shifts must not be more than 12h</Label>
      <Weight function="quadratic">100</Weight>
    </Max>
  </ShiftLengths>
  <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
<Time> Required TimeOfDay The earliest start time.
<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.
<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.

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
<Time> Required TimeOfDay The latest start time.
<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.
<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>

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

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

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

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

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
<Length> Required NonNegativeDouble The maximum shift length in minutes.
<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.
<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>

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

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.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. The ID is defined in ShiftTypes.

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

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

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

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
<Count> Required NonNegativeDouble The maximum number of minutes to work.
<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.
<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.

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>

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

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.

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.

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.

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

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

Example

<Employee ID="E1">
  <ContractID>C1</ContractID>
  <ContractID>C2</ContractID>
</Employee>

<Rules>

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

Parents : ScheduleSolver

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

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

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>

<DayOffRequests>

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

Parents : ScheduleSolver

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

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

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

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.

Parents : ScheduleSolver

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>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>
    <EmployeeID>E2</EmployeeID>
    <NoShift>
      <Start>2019-11-19T08:00</Start>
      <End>2019-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. 1.0+

Elements

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

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

Example

  <Employee ID="1">
    <Shift ID="XX"/>
    <Shift ID="XY"/>
    <NotShift ID="AA"/>
    <NotShift ID="BB"/>
  </Employee>

<NoShift>

An employee must have no shift 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 shift assignments.
<End> Required DateTime The end of the time period during which the employee must not have any shift assignments.

Example

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

<Shift>

A pre-assigned shift which cannot be un-assigned.

Parents : Employee

Attributes

Name Required Type Description Ver.
ID Required string The shift ID (defined in Shifts). 1.0+

Elements

None

Example

  <Employee ID="1">
    <Shift ID="XX"/>
    <Shift ID="XY"/>
    <NotShift ID="AA"/>
    <NotShift ID="BB"/>
  </Employee>

<NotShift>

A shift which must not be assigned to this employee.

Parents : Employee

Attributes

Name Required Type Description Ver.
ID Required string The shift ID (defined in Shifts). 1.0+

Elements

None

Example

  <Employee ID="1">
    <Shift ID="XX"/>
    <Shift ID="XY"/>
    <NotShift ID="AA"/>
    <NotShift ID="BB"/>
  </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.