Xml format for AutoRoster problem instances

This document describes the data format used for AutoRoster problem instances. As well as being read by the rostering engine, the data format can also be read by Roster Booster. The data format is an XML based format and so can be created and edited using any text editor. An xml aware editor is recommended to allow the data to be validated against the format's schema as it is edited. Many XML editors also provide other useful features such as tag suggestion and auto-completion.

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

Throughout this document, a number of terms such as 'shift types', 'cells', 'scheduling period' are frequently used. The figure below shows an annotated example roster to help explain some commonly used terms.

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

• The planning horizon. The planning period (sometimes called the scheduling horizon) is simply specified using the tags <StartDate> and <EndDate>.
• Shift types. The shift types that can be assigned in the roster. This information is specified within the tag <ShiftTypes>.
• 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, weekends, night shifts etc.
  
  To model these requirements, three general constraints are provided (<Workload>, <Patterns> and <Conditionals>). The vast majority of scheduling requirements can be modelled using these constraints.
  
  These constraints are entered within the tag <Contracts>. Each employee can have their own contract but it is common for employees to have the same constraints so contracts may also be shared by two or more employees.
  
  The schedule for each employee in the current planning period is clearly also affected by the employee's schedule in the previous planning period. To model this there are two options:
  
  
  1. Include the previous planning period (or as much of it as is relevant) in the current planning period (by making the start date earlier) and then fix all these assignments in place using <FixedAssignments> so they cannot be changed. (See the example instance Ikegami-3Shift-DATA1 for an example of this method).
  2. The second option is to enter constraints (in the contracts) which are based on the assignments made in the previous schedules. For example if a night shift can only followed by a night shift or a day off and the last day of the previous schedule has a night shift, then enter a constraint (e.g. using <Patterns>) in this scheduling period which ensures that only a night shift or day off is assigned on the first day.
  
  The second method is usually more efficient for the solver but may be more effort to model. An effective compromise is to include some of the previous roster (fixed in place) and then add additional constraints for the ones which would require long sections of the previous schedule.
• Cover constraints. Cover constraints describe the min and max numbers of employees that must be working each day. The cover can be specified per shift and/or for a specific time period in the day. The cover can be further split up by skill levels or requirements for specific groups of employees.

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

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

<SchedulingPeriod>

The root element of the document.

Attributes

Elements

SchedulingPeriod contains a sequence of child elements in the following order:

Example

<?xml version="1.0" encoding="UTF-8"?>
<SchedulingPeriod ID="Example" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                  xsi:noNamespaceSchemaLocation="SchedulingPeriod-3.0.xsd">
  <StartDate>2009-04-05</StartDate>
  <EndDate>2009-04-30</EndDate>
  
  <ShiftTypes>
    <Shift ID="E">
      <Label>E</Label>
      <Color>#66FF00</Color>
      <StartTime>07:00:00</StartTime>
      <EndTime>14:45:00</EndTime>
    </Shift> 
  </ShiftTypes>
  
  <Contracts>
    <Contract ID="A">
      <Patterns>
        <Match>
          <Max>
            <Count>10</Count>
            <Weight>1000</Weight>
            <Label>Max 10 E shifts</Label>
          </Max>  
          <Pattern>
            <Shift>E</Shift>
          </Pattern>
        </Match>     
      </Patterns>
    </Contract>
  </Contracts>
  
  <Employees>
    <Employee ID="A">
      <ContractID>A</ContractID>
    </Employee>
  </Employees>
  
  <CoverRequirements>
    <DayOfWeekCover>
      <Day>Saturday</Day>
      <Cover>
        <Shift>E</Shift>
        <Min>2</Min>
      </Cover>
    </DayOfWeekCover>
  </CoverRequirements>
    
</SchedulingPeriod>

<SkillGroups>

Skills can be placed in groups for use in cover constraints.

Parents : SchedulingPeriod

Attributes

Elements

SkillGroups contains zero or more <SkillGroup> elements.

Example

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

<SkillGroup>

A group of skills.

Parents : SkillGroups

Attributes

Elements

SkillGroup contains one or more <Skill> elements.

Example

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

<ShiftTypes>

ShiftTypes contains the definitions of the different shifts to be assigned in the scheduling period.

Parents : SchedulingPeriod

Attributes

Elements

Contains zero or more <Shift> elements.

Example

  <ShiftTypes>
    <Shift ID="N">
      <Label>N</Label>
      <Color>LightBlue</Color>
      <Name>Night</Name>
      <StartTime>18:00:00</StartTime>
      <EndTime>06:00:00</EndTime>
    </Shift>
    <Shift ID="E">
      <Label>E</Label>
      <Color>LightGreen</Color>
      <Name>Evening</Name>
      <StartTime>12:00:00</StartTime>
      <EndTime>20:00:00</EndTime>
    </Shift>
    <Shift ID="D">
      <Label>D</Label>
      <Color>Yellow</Color>
      <Name>Day</Name>
      <StartTime>06:00:00</StartTime>
      <EndTime>16:00:00</EndTime>
    </Shift>
    <Shift ID="O">
      <Label>O</Label>
      <Color>Red</Color>
      <Name>Other work</Name>
      <StartTime>06:00:00</StartTime>
      <EndTime>18:00:00</EndTime>
      <AutoAllocate>false</AutoAllocate>
    </Shift>
  </ShiftTypes>

<Shift>

A specific shift type. For example a night shift.

Parents : ShiftTypes

Attributes

Elements

Shift contains the following child elements in any order:

Example

    <Shift ID="E">
      <Label>E</Label>
      <Color>#66FF00</Color>
      <Name>Early</Name>
      <StartTime>07:00:00</StartTime>
      <EndTime>14:45:00</EndTime>
      <TimeUnits>75</TimeUnits>
    </Shift>

<Resources>

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

Parents : Shift

Attributes

Elements

Resources contains zero or more <Resource> elements.

Example

  <Shift ID="D1">
    <TimePeriods>
     <TimePeriod><Start>08:30:00</Start><End>15:30:00</End></TimePeriod>
     <TimePeriod><Start>17:30:00</Start><End>22:30:00</End></TimePeriod>
    </TimePeriods>
    <Resources>
     <Resource ID="ShiftUnits">2</Resource>
     <Resource ID="TimeUnits">10</Resource>
    </Resources>
  </Shift>

<Resource>

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

Parents : Resources

Attributes

Element

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

Example

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

<ShiftGroups>

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

Parents : SchedulingPeriod

Attributes

Elements

ShiftGroups contains zero or more <ShiftGroup> elements.

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

Elements

ShiftGroup contains one or more <Shift> elements.

Example

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

<Contracts>

Contracts contain the constraints on the employees' work schedules.

Parents : SchedulingPeriod

Attributes

Elements

Contracts contains zero or more <Contract> elements.

Example

<Contracts>
  <Contract ID="A">
    <Workload>    
      <TimeUnits>
        <Max> 
          <Count>1500</Count>
          <Weight>100</Weight>
          <Label>Max 150 hours</Label>
        </Max>
      </TimeUnits>
    </Workload>
    <Patterns>
      <Match>
        <Max> 
          <Count>0</Count>
          <Weight>1000</Weight>
          <Label>No N-E</Label>
        </Max>  
        <Pattern>
          <ShiftGroup>N</ShiftGroup>
          <ShiftGroup>E</ShiftGroup>
        </Pattern>
      </Match>
      <Match>
        <Max> 
          <Count>0</Count>
          <Weight>1000</Weight>
          <Label>No N-L</Label>
        </Max>  
        <Pattern>
          <ShiftGroup>N</ShiftGroup>
          <ShiftGroup>L</ShiftGroup>
        </Pattern>
      </Match>
    </Patterns>
  </Contract>    
</Contracts>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract.

Parents : Contracts

Attributes

Elements

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

Example

  <Contract ID="A">
    <Workload>    
      <TimeUnits>
        <Max> 
          <Count>1500</Count>
          <Weight>100</Weight>
          <Label>Max 150 hours</Label>
        </Max>
      </TimeUnits>
    </Workload>
    <Patterns>
      <Match>
        <Max> 
          <Count>0</Count>
          <Weight>1000</Weight>
          <Label>No N-E</Label>
        </Max>  
        <Pattern>
          <ShiftGroup>N</ShiftGroup>
          <ShiftGroup>E</ShiftGroup>
        </Pattern>
      </Match>
      <Match>
        <Max> 
          <Count>0</Count>
          <Weight>1000</Weight>
          <Label>No N-L</Label>
        </Max>  
        <Pattern>
          <ShiftGroup>N</ShiftGroup>
          <ShiftGroup>L</ShiftGroup>
        </Pattern>
      </Match>
    </Patterns>
  </Contract>

<Workload>

This constraint is used to model the requirements of min/max total time units (or any other resource) between any two dates in the planning period. Each shift has an associated number of time units (and other resources) (see ShiftTypes).

Parents : Contract

Attributes

Elements

Workload contains one or more <TimeUnits> elements.

Example

    <Workload>    
      <TimeUnits>
        <Max> 
          <Count>1500</Count>
          <Weight>100</Weight>
          <Label>Max 150 hours for the total planning period</Label>
        </Max>
      </TimeUnits>
    </Workload>

<TimeUnits>

TimeUnits specifies a minimum and/or maximum total number of time units (or other resource) 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.

Parents : Workload

Attributes

Elements

Workload contains a <Min> and/or a <Max> element (in either order) followed by <RegionStart> or <RegionStartDate> (both are optional) followed by <RegionEnd> or <RegionEndDate> (both are optional) followed by <ShiftGroup> (optional) followed by <Resource> (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.

Example

      <TimeUnits>
        <Max> 
          <Count>750</Count> 
          <Weight>100</Weight>
          <Label>Max 75 hours in two weeks</Label>
        </Max>
        <RegionStart>0</RegionStart>
        <RegionEnd>13</RegionEnd> 
      </TimeUnits>

<Min>

Specifies a minimum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty/objective function. It can then also have a function type 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.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : TimeUnits

Attributes

Elements

Min contains the following elements in any order.

Example

    <Min> 
      <Count>1</Count> 
      <Weight function="Quadratic">1000</Weight>
    </Min>

<Max>

Specifies a maximum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty/objective function. It can then also have a function type 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.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : TimeUnits

Attributes

Elements

Max contains the following elements in any order.

Example

    <Max> 
      <Count>1</Count> 
      <Weight function="Quadratic">1000</Weight>
    </Max>

<Min>

Specifies a minimum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty/objective function. It can then also have a function type 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.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : Match

Attributes

Elements

Min contains the following elements in any order.

Example

    <Min> 
      <Count>1</Count> 
      <Weight function="Quadratic">1000</Weight>
    </Min>

<Max>

Specifies a maximum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty/objective function. It can then also have a function type 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.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : Match

Attributes

Elements

Max contains the following elements in any order.

Example

    <Max> 
      <Count>1</Count> 
      <Weight function="Quadratic">1000</Weight>
    </Max>

<Patterns>

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

Parents : Contract

Attributes

Elements

Patterns contains one or more <Match> elements.

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 free shifts</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

Elements

Match contains a <Min> and/or a <Max> element (in either order) followed by <RegionStart> or <RegionStartDate> (both are optional) followed by <RegionEnd> or <RegionEndDate> (both are optional) followed by 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.

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

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.

Example

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

<Conditionals>

Conditional constraints can be used to model rules of the form IF Condition1 satisfied THEN Condition2 must be satisfied. Condition1 and Condition2 and boolean logic expressions made up of boolean variables and 'AND' and 'OR' operators. The boolean variables are linked to Workload and Patterns constraints and are assigned the values true or false depending on whether their underlying constraint is satisfied.

Parents : Contract

Attributes

Elements

Conditionals contains one or more <Conditional> elements.

Example

<Contract ID="Example">
  <Workload>
    <TimeUnits>
      <Min>
        <Count>750</Count>
        <Var>Over75hrsWks1_2</Var>
        <Label>75 hours or more over week1 and week2</Label>
      </Min>
      <RegionStart>0</RegionStart>
      <RegionEnd>13</RegionEnd> 
    </TimeUnits>
  
    <TimeUnits>
      <Min>
        <Count>750</Count>
        <Var>Over75hrsWks3_4</Var>
        <Label>75 hours or more over week3 and week4</Label>
      </Min>
      <RegionStart>14</RegionStart>
      <RegionEnd>27</RegionEnd>
    </TimeUnits>
  </Workload>
    
  <Patterns>    
    <Match>
      <Min>
        <Count>1</Count>
        <Var>Nights</Var>
        <Label>Min 1 Night</Label>
      </Min>  
      <Pattern><ShiftGroup>N</ShiftGroup></Pattern>
    </Match>

    <Match>
      <Max>
        <Count>0</Count>
        <Var>NoEDs</Var>
        <Label>Max zero E or D</Label>
      </Max>  
      <Pattern><ShiftGroup>E</ShiftGroup></Pattern>
      <Pattern><ShiftGroup>D</ShiftGroup></Pattern>
    </Match>

    <Match>
      <Max>
        <Count>5</Count>
        <Var>Max5Nights</Var>
        <Label>Max 5 N</Label>
      </Max>  
      <Pattern><ShiftGroup>N</ShiftGroup></Pattern>
    </Match>
  
    <Match>
      <Max>
        <Count>4</Count>
        <Var>Max4Early</Var>
        <Label>Max 4 E</Label>
      </Max>  
      <Pattern><ShiftGroup>E</ShiftGroup></Pattern>
    </Match>
  
    <Match>
      <Min>
        <Count>10</Count>
        <Var>Min10DaysOff</Var>
        <Label>Min 10 days off</Label>
      </Min>  
      <Pattern><Shift>-</Shift></Pattern>
    </Match>
  
    <Match>
      <Min> 
        <Count>3</Count>
        <Var>3Weekends</Var>
        <Label>At least three weekends</Label>
      </Min>  
      <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>
  </Patterns>

  <Conditionals>
    <Conditional>
      <Label>If at least one night shift then no early 
      or day shifts (nights only or early and days only)</Label>
      <If>Nights</If>
      <Then>NoEDs</Then>
      <Weight>10000</Weight>
    </Conditional>
  
    <Conditional>
      <Label>If 75+ hours over week one and two and 75+ hours 
      over week three and four then no more than five night shifts</Label>
      <If>Over75hrsWks1_2 AND Over75hrsWks3_4</If>
      <Then>Max5Nights</Then>
      <Weight>1000</Weight>
    </Conditional>
  
    <Conditional>
      <Label>If three weekends worked then at least ten days 
      off and max four early shifts or max five nights</Label>
      <If>3Weekends</If>
      <Then>Max5Nights OR (Min10DaysOff AND Max4Early)</Then>
      <Weight>100</Weight>
    </Conditional>
  </Conditionals>
</Contract>

<Conditional>

A conditional constraint. See Conditionals for more information.

Parents : Conditionals

Attributes

Elements

Conditional contains a <Label> element (optional), followed by <If> and <Then> elements followed by a <Weight> element (optional).

The <If> and <Then> elements are boolean logic expressions made up of boolean variables and the boolean operators 'AND' and 'OR'. The variables are defined in <Min> and <Max> elements of Workload and Patterns constraints. The variables will be true or false depending on whether their underlying constraint is satisfied or not. If the IF expression evaluates to true then the THEN expression must also evaluate to true otherwise the constraint is violated.

As in most programming languages, AND has higher precedence than OR (and both are left associative). Parentheses can also be used to override the default precedence. The AND and OR operators are also both case-insensitive (i.e. 'And', 'and', 'Or', 'or' are all valid operators).

Example (See also Conditionals for more examples)

  <Conditionals>

    <Conditional>
      <If>Var1</If>
      <Then>Var2</Then>
    </Conditional>
    
    <Conditional>
      <If>Var1 AND Var2</If>
      <Then>Var3 OR Var4</Then>
    </Conditional>
    
    <Conditional>
      <If>(Var1 AND Var2) OR Var3</If>
      <Then>Var4</Then>
    </Conditional>
    
    <Conditional>
      <If>(Var1 AND Var2) OR (Var3 AND Var4)</If>
      <Then>Var5 AND (Var6 OR Var7 OR Var8) AND Var9</Then>
    </Conditional>
    
  </Conditionals>

<CellIndexes>

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

Parents : Pattern, Pair, NotPair

Attributes

Elements

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

Example

  <Match>
    <Max><Count>2</Count><Weight>1000</Weight></Max>
    <Pattern>
      <Starts>
        <Cell>0</Cell>
        <Cell>2</Cell>
        <Cell>3</Cell>
      </Starts>
      <ShiftGroup>All</ShiftGroup>
    </Pattern>
  </Match>
    
  <Match>
    <Max><Count>4</Count><Weight>1000</Weight></Max>
    <Pattern>
      <StartExcludes>
        <Date>2010-08-13</Date>
        <DayOfWeek>Saturday</DayOfWeek>
        <DayOfWeek>Sunday</DayOfWeek>
        <Cell>27</Cell>
      </StartExcludes>
      <Shift>N</Shift><Shift>N</Shift><Shift>N</Shift>
    </Pattern>
  </Match>

  <Pair>
    <Label>If A has a shift then B should have the same shift. 
    That is, If A has an E shift then B must have an E shift.
             If A has an L shift then B must have an L shift...
             (Only applies on days 0-4)</Label>
    <Weight>1000</Weight>
    <Cells>
      <Cell>0</Cell>
      <Cell>1</Cell>
      <Cell>2</Cell>
      <Cell>3</Cell>
      <Cell>4</Cell>
    </Cells>
    <Matches>
      <Match>
        <Assignment><Employee>A</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
  </Pair>
  
  <Pair>
    <Label>If C has shift E then D should have shift E too 
    (doesn't apply on Sundays or day 7)</Label>
    <Excludes>
      <DayOfWeek>Sunday</DayOfWeek>
      <Cell>7</Cell>
    </Excludes>
    <Matches>
      <Match>
        <Assignment><Employee>C</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>E</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>1000</Weight>
  </Pair>

<Employees>

The employees.

Parents : SchedulingPeriod

Attributes

Elements

Contains zero or more Employee elements.

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

Elements

Employee contains the following child elements in any order:

Example

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

<Skills>

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

Parents : Employee

Attributes

Elements

Skills contains one or more <Skill> elements.

Example

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

<CoverResources>

When an employee is assigned to a shift (or works during a certain time period), the cover count for that shift (or time period) is increased by one. However, if necessary the cover count can be increased by a value other than one by defining new 'cover resource' values here and referencing the cover resource's ID in the Cover constraints.

Parents : Employee

Attributes

Elements

CoverResources contains one or more <CoverResource> elements.

Example

<Employee ID="A">
  <ContractID>A</ContractID>
  <CoverResources>
    <CoverResource ID="Facility1_00-06">
      <Shift ID="1">6.0</Shift>
      <Shift ID="2">5.5</Shift>
      <Shift ID="3">6.2</Shift>
    </CoverResource>
    <CoverResource ID="Facility1_06-12">
      <Shift ID="3">5.7</Shift>
      <Shift ID="4">6.5</Shift>
    </CoverResource>
  </CoverResources>
</Employee>

<CoverResource>

CoverResource contains one or more <Shift> elements to indicate how much to increase the cover count by when that shift is assigned to the employee. For each shift type that is not defined in a <CoverResource> the resource value for that shift type is assumed to be zero.

Parents : CoverResources

Attributes

Elements

CoverResource contains one or more <Shift> elements.

Example

<Employee ID="A">
  <ContractID>A</ContractID>
  <CoverResources>
    <CoverResource ID="Facility1_00-06">
      <Shift ID="1">6.0</Shift>
      <Shift ID="2">5.5</Shift>
      <Shift ID="3">6.2</Shift>
    </CoverResource>
    <CoverResource ID="Facility1_06-12">
      <Shift ID="3">5.7</Shift>
      <Shift ID="4">6.5</Shift>
    </CoverResource>
  </CoverResources>
</Employee>

<Rules>

Rules is an alternative way of expressing and modelling the constraints that are modelled using <Contracts>, <EmployeePairings> and <CoverRequirements>. Due to its flexibility it can also be used to create new, custom constraints.

Parents : SchedulingPeriod

Attributes

Elements

Rules contains zero or more <Rule> elements.

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.

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 (in other words, negative penalties are not allowed).

See also: Operators, precedence and associativity.

Attributes

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>

<EmployeePairings>

This is used to model constraints such as two or more employees must work certain shifts at the same time. Or oppositely, two or more employees must not work certain shifts at the same time.

Parents : SchedulingPeriod

Attributes

Elements

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

Example

<EmployeePairings>
  <Pair>
    <Label>If A has a shift then B should have the same shift. 
    That is,
    If A has an E shift then B must have an E shift.
    If A has an L shift then B must have an L shift.
    If A has an N shift then B must have an N shift.</Label>
    <Weight>1000</Weight>
    <Matches>
      <Match>
        <Assignment><Employee>A</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
  </Pair>
  
  <Pair>
    <Label>If C has a shift then D should have the same shift 
    (only applies on day zero)</Label>
    <Matches>
      <Match>
        <Assignment><Employee>C</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>C</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>C</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
    <Cell>0</Cell>
    <Weight>1000</Weight>
  </Pair>

  <Pair>
    <Label>
    If E1 works a shift from group S1 then E2 must work a shift from group UPG_1_4_7_8.
    If E1 works a shift from group S7 then E2 must work a shift from group UPG_1_4_7.
    If E1 works a shift from group S8 then E2 must work a shift from group UPG_2_5_8 
       or work a shift from group UPG_3_6 on day+1.
    If E1 works a shift from group S3 then E2 must work a shift from group UPG_6 
       or work a shift from group S8 on day-1.
    If E1 works a shift from group S6 then E2 must work a shift from group UPG_3 
       or work a shift from group S8 on day-1.
    (E2 should work shifts which overlap with E1's shifts by at least two hours).
    </Label>
    <Matches>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S1</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>UPG_1_4_7_8</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S7</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>UPG_1_4_7</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S8</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>UPG_2_5_8</ShiftGroup>
                                           <ShiftGroup offset="1">UPG_3_6</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S3</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>UPG_6</ShiftGroup>
                                           <ShiftGroup offset="-1">S8</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S6</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>UPG_3</ShiftGroup>
                                           <ShiftGroup offset="-1">S8</ShiftGroup></Assignment>
      </Match>
    </Matches>
    <Weight>250</Weight>
  </Pair>

  <Pair>
    <Label>
    If E1 works a shift S1 then E2 must work a shift from group G2 and 
    E3 must work a shift from group G3 or shift S1
    </Label>
    <Matches>
      <Match>
        <Assignment><Employee>E1</Employee><Shift>S1</Shift></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>G2</ShiftGroup></Assignment>
        <Assignment><Employee>E3</Employee><ShiftGroup>G3</ShiftGroup><Shift>S1</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>250</Weight>
  </Pair>
  
  <NotPair>
    <Label>If X has a shift then Y should NOT have the same shift
    That is,
    If X has an E shift then B must NOT have an E shift.
    If X has an L shift then B must NOT have an L shift.
    If X has an N shift then B must NOT have an N shift.</Label>
    <Matches>
      <Match>
        <Assignment><Employee>X</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>X</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>X</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>1000</Weight>
  </NotPair>
  
  <NotPair>
    <Label>
    A violation occurs if :
    E1 has a shift from group S1 
    AND (E2 has shift from group S2 or has a shift from S2b on day-1)
    AND E3 has a shift from S3 
    AND E4 has a shift from S4.
    
    Or a violation occurs if :
    If E1 has a shift from shift group S5 and E2 has a shift from 
    group S6 on the same day.
    </Label>
    <Matches>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S1</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>S2</ShiftGroup>
                                           <ShiftGroup offset="-1">S2b</ShiftGroup></Assignment>
        <Assignment><Employee>E3</Employee><ShiftGroup>S3</ShiftGroup></Assignment>
        <Assignment><Employee>E4</Employee><ShiftGroup>S4</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S5</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>S6</ShiftGroup></Assignment>
      </Match>
    </Matches>
    <Weight>250</Weight>
  </NotPair>
</EmployeePairings>

<Pair>

If the employee in the first <Assignment> in each <Match> works a specified shift then the other employee(s) in the <Match> must work their specified shift(s) on the same day or optionally on an offset day (i.e. day -2, -1, +1 etc).

If an <Assignment> in a <Match> contains a day offset which would take the constraint out of the scheduling range (for example, when applied to day 0 and the offset is -1), then the constraint is considered as not violated on that day. In other words, if it is possible that the constraint is satisfied by a shift assignment in the previous scheduling period or the next scheduling period then no violation will occur in this scheduling period.

Parents : EmployeePairings

Attributes

Elements

Pair contains <Label>, <Cell>, <Cells>, <Excludes>, <Matches> and <Weight> elements in any order. All are optional except <Matches>. If none of <Cell>, <Cells> or <Excludes> are used then the constraint applies to all days in the scheduling period.

Example (See also EmployeePairings for more examples)

<EmployeePairings>
  <Pair>
    <Label>If A has a shift then B should have the same shift. 
    That is,
    If A has an E shift then B must have an E shift.
    If A has an L shift then B must have an L shift.
    If A has an N shift then B must have an N shift.</Label>
    <Weight>1000</Weight>
    <Matches>
      <Match>
        <Assignment><Employee>A</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>A</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>B</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
  </Pair>
</EmployeePairings>

<NotPair>

If the employee in the first <Assignment> in each <Match> works a specified shift then the other employee(s) in the <Match> must NOT work their specified shift(s) on the same day or optionally on an offset day (i.e. day -2, -1, +1 etc).
If only one <Assignment> is specified in a <Match> then the employee in the assignment must not work their specified shift(s).

If an <Assignment> in a <Match> contains a day offset which would take the constraint out of the scheduling range (for example, when applied to day 0 and the offset is -1), then no assumption is made about that match. In other words, any out of range matches are ignored and only in range matches are considered.

Parents : EmployeePairings

Attributes

Elements

NotPair contains <Label>, <Cell>, <Cells>, <Excludes>, <Matches> and <Weight> elements in any order. All are optional except <Matches>. If none of <Cell>, <Cells> or <Excludes> are used then the constraint applies to all days in the scheduling period.

Example (See also EmployeePairings for more examples)

<EmployeePairings>
  <NotPair>
    <Label>If X has a shift then Y should NOT have the same shift
    That is,
    If X has an E shift then B must NOT have an E shift.
    If X has an L shift then B must NOT have an L shift.
    If X has an N shift then B must NOT have an N shift.</Label>
    <Matches>
      <Match>
        <Assignment><Employee>X</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>X</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>X</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>Y</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>1000</Weight>
  </NotPair>
</EmployeePairings>

<Matches>

Matches contains employee-to-shift assignments which must or must not be made for two or more employees on the same day (or offset days).

Parents : Pair, NotPair

Attributes

Elements

Matches contains one or more <Match> elements.

Example

<EmployeePairings>
  <NotPair>
    <Label>
    A violation occurs if :
    E1 has a shift from group S1 
    AND (E2 has shift from group S2 or has a shift from S2b on day-1)
    AND E3 has a shift from S3 
    
    Or a violation occurs if :
    If E1 has a shift from shift group S5 and E2 has shift S6 on the same day or 
    shift S7 on the next day.
    </Label>
    <Matches>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S1</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>S2</ShiftGroup>
                                           <ShiftGroup offset="-1">S2b</ShiftGroup></Assignment>
        <Assignment><Employee>E3</Employee><ShiftGroup>S3</ShiftGroup></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>E1</Employee><ShiftGroup>S5</ShiftGroup></Assignment>
        <Assignment><Employee>E2</Employee><Shift>S6</Shift>
                                           <Shift offset="1">S7</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>250</Weight>
  </NotPair>
</EmployeePairings>

<Match>

A set of employee-to-shift assignments to be matched in an EmployeePairing constraint.

If the employee in the first <Assignment> works the specified shift or shift group then the match is made if employee(s) in the other <Assignment> all work their specified shift(s) or shift group(s).

Parents : Matches

Attributes

Elements

Match contains at least one <Assignment> element.

Example

<EmployeePairings>
  <Pair>
    <Label>If C has a shift then D should have the same shift 
    (only applies on day zero)</Label>
    <Matches>
      <Match>
        <Assignment><Employee>C</Employee><Shift>E</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>E</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>C</Employee><Shift>L</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>L</Shift></Assignment>
      </Match>
      <Match>
        <Assignment><Employee>C</Employee><Shift>N</Shift></Assignment>
        <Assignment><Employee>D</Employee><Shift>N</Shift></Assignment>
      </Match>
    </Matches>
    <Cell>0</Cell>
    <Weight>1000</Weight>
  </Pair>
</EmployeePairings>

<Assignment>

An employee-to-shift or employee-to-shift group assignment. The assignment is matched if the employee works one of the shifts in the <Shift> or <ShiftGroup> tags. If the <Shift> or <ShiftGroup> contains an offset attribute then the assignment is matched if the employee works the specified shift on the day offset relative to the other assignments. For example, if the offset is -1 then this assignment must be on the day before the other assignments. If the offset is +2 then the assignment must be two days after the other assignments etc.

Parents : Match

Attributes

Elements

Assignment contains an <Employee> element followed by one or more <Shift> and/or <ShiftGroup> elements.

Example

<EmployeePairings>
  <Pair>
    <Label>
    If E1 works a shift S1 then E2 must work a shift from group G2 and 
    E3 must work a shift from group G3 or shift S1
    </Label>
    <Matches>
      <Match>
        <Assignment><Employee>E1</Employee><Shift>S1</Shift></Assignment>
        <Assignment><Employee>E2</Employee><ShiftGroup>G2</ShiftGroup></Assignment>
        <Assignment><Employee>E3</Employee><ShiftGroup>G3</ShiftGroup>
                                           <Shift>S1</Shift></Assignment>
      </Match>
    </Matches>
    <Weight>250</Weight>
  </Pair>
</EmployeePairings>

<CoverRequirements>

The minimum and maximum numbers of employees covering shifts/time periods during the scheduling period.

Parents : SchedulingPeriod

Attributes

Elements

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

<DayOfWeekCover>

The minimum and maximum numbers of employees covering shifts/time periods on a specific week day.

Parents : CoverRequirements

Attributes

Elements

DayOfWeekCover contains one <Day> element followed by one or more Cover> elements.

Example

    <DayOfWeekCover>
        <Day>Friday</Day>
        <Cover>
            <ShiftGroup>N</ShiftGroup>
            <Min>4</Min>
        </Cover>
        <Cover>
            <Skill>Skilled</Skill>
            <ShiftGroup>N</ShiftGroup>
            <Min weight="100">1</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Na</Shift>
            <Min>1</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Nb</Shift>
            <Min>1</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Nc</Shift>
            <Min>1</Min>
        </Cover>
        <Cover>
            <ShiftGroup>D</ShiftGroup>
            <Min>10</Min>
            <Max>11</Max>
        </Cover>
        <Cover>
            <Skill>Skilled</Skill>
            <ShiftGroup>D</ShiftGroup>
            <Min weight="100">1</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Da</Shift>
            <Min>2</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Db</Shift>
            <Min>2</Min>
        </Cover>
        <Cover>
            <SkillGroup>SkilledOrSecondYear</SkillGroup>
            <Shift>Dc</Shift>
            <Min>2</Min>
        </Cover>
        <Cover>
            <Shift>Da</Shift>
            <Min>3</Min>
            <Max weight="10">4</Max>
        </Cover>
        <Cover>
            <Shift>Db</Shift>
            <Min>3</Min>
            <Max weight="10">4</Max>
        </Cover>
        <Cover>
            <Shift>Dc</Shift>
            <Min>3</Min>
            <Max weight="10">4</Max>
        </Cover>
    </DayOfWeekCover>

<DateSpecificCover>

The minimum and maximum numbers of employees covering shifts/time periods on a specific date in the scheduling horizon.

Parents : CoverRequirements

Attributes

Elements

DateSpecificCover contains <Date>, <Day> or <Cell> element followed by one or more <Cover> elements.

Example

    <DateSpecificCover>
        <Date>1996-11-26</Date>
        <Cover>
            <ShiftGroup>D</ShiftGroup>
            <Min weight="1000">12</Min>
            <Max weight="1000">16</Max>
        </Cover>
        <Cover>
            <Shift>Da</Shift>
            <Min>4</Min>
            <Max>6</Max>
        </Cover>
        <Cover>
            <Shift>Db</Shift>
            <Min>4</Min>
            <Max>6</Max>
        </Cover>
        <Cover>
            <Shift>Dc</Shift>
            <Min>4</Min>
            <Max>6</Max>
        </Cover>
    </DateSpecificCover>

<Cover>

The min and/or max numbers of employees (optionally with certain skills) covering shifts or time periods.

<Min> and <Max> may use weight attributes to indicate they are soft constraints (i.e. part of the penalty/objective function). If they are a soft constraint and the cover requirement is not satisfied then the amount by which the requirement is not satisfied is multiplied by the weight and added to the penalty function value. For example if a Min of 10 employees are required during a shift on a certain day but only 8 are provided in the solution then a penalty of (10-8) * weight will be added to the penalty function value. If the weight attribute is omitted then the constraint is assumed to be a hard constraint.

Parents : DayOfWeekCover , DateSpecificCover

Attributes

Elements

Cover contains a <Skill> or <SkillGroup> element (both optional) followed by a <TimePeriod>, <Shift> or <ShiftGroup> element followed by <Min> and/or <Max> (both optional) followed by a <Label> element (optional) and a <CoverResource> element (optional).

Example

    <DayOfWeekCover>
      <Day>Saturday</Day>
      <Cover>
        <Shift>E</Shift>
        <Min>2</Min>
        <Max>5</Max>
      </Cover>
      <Cover>
        <Skill>EyeTrained</Skill>
        <Shift>E</Shift>
        <Min weight="100">1</Min>
      </Cover>
      <Cover>
        <Shift>L</Shift>
        <Min>1</Min>
        <Max>4</Max>
      </Cover>
      <Cover>
        <Skill>EyeTrained</Skill>
        <Shift>L</Shift>
        <Min weight="100">1</Min>
      </Cover>
      <Cover>
        <Shift>N</Shift>
        <Min>1</Min>
        <Max>3</Max>
      </Cover>
      <Cover>
        <Skill>EyeTrained</Skill>
        <Shift>N</Shift>
        <Min weight="100">1</Min>
      </Cover>
    </DayOfWeekCover>