AutoRoster problem data

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.

To help get started an AutoRoster XML template file is also available.

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

XML data flow diagram

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

Annotated AutoRoster instance

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

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

Elements

SchedulingPeriod contains the following elements in any order:

Name Required Type Description Ver.
<StartDate> Required Date The date of the first day in the scheduling period. Specified in the format : YYYY-MM-DD. 3.0+
<EndDate> Required Date The date of the last day in the scheduling period. Specified in the format : YYYY-MM-DD. 3.0+
<ShiftTypes> Optional ShiftTypes The shifts to be assigned e.g. early shifts, night shifts, 12 hour shifts etc. 3.0+
<ShiftGroups> Optional ShiftGroups Some constraints require shift types to be grouped together (for example a group of night shifts). The groups are defined here. 3.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. 3.0+
<Employees> Optional Employees The employees to be scheduled. 3.0+
<Rules> Optional 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. 3.0+
<EmployeePairings> Optional 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. 3.0+
<SkillGroups> Optional SkillGroups Skills can be grouped together and cover specified for different skill groups. The groups are defined here. 3.0+
<ShiftBlocks> Optional ShiftBlocks Cover requirements can be specified for a sequence of consecutive shifts. These 'blocks' can be defined here. 3.32+
<CoverRequirements> Optional CoverRequirements The minimum and maximum numbers of employees working at certain times/shifts during the scheduling period. 3.0+
<DayOffRequests> Optional DayOffRequests Dates on which employees request not to be working. 3.0+
<DayOnRequests> Optional DayOnRequests Dates on which employees want to be working. 3.0+
<ShiftOffRequests> Optional ShiftOffRequests Dates on which employees do not want specific shifts. 3.0+
<ShiftOnRequests> Optional ShiftOnRequests Dates on which employees want specific shifts. 3.0+
<FixedAssignments> Optional FixedAssignments Shift assignments and day off assignments which must be in the solution. 3.0+

Example

<?xml version="1.0" encoding="UTF-8"?>
<SchedulingPeriod 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">
      <Color>#66FF00</Color>
      <StartTime>07:00:00</StartTime>
      <EndTime>14:45:00</EndTime>
    </Shift>
  </ShiftTypes>
 
  <Contracts>
    <Contract ID="A">
      <MaxTot label="Max 10 E shifts" value="10" shift="E" weight="1000"/>
    </Contract>
  </Contracts>
 
  <Employees>
    <Employee ID="A">
      <ContractID>A</ContractID>
    </Employee>
  </Employees>

  <CoverRequirements>
    <DayOfWeekCover>
      <Day>Saturday</Day>
      <Cover>
        <Shift>E</Shift>
        <Min weight="1000">1</Min>
      </Cover>
    </DayOfWeekCover>
  </CoverRequirements>
  
</SchedulingPeriod>

<SkillGroups>

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

Parents : SchedulingPeriod

Attributes

None

Elements

SkillGroups contains zero or more <SkillGroup> elements.

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

Example

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

<SkillGroup>

A group of skills.

Parents : SkillGroups

Attributes

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

Elements

SkillGroup contains one or more <Skill> elements.

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

Example

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

<ShiftTypes>

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

Parents : SchedulingPeriod

Attributes

None

Elements

Contains zero or more <Shift> elements.

Name Required Type Description
<Shift> Optional Shift A specific shift type. For example a night shift.

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

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
<StartTime> Optional TimeOfDay The shift's start time. Specified in the format : hh:mm:ss or hh:mm. Default value is 00:00:00.
<EndTime> Optional TimeOfDay The shift's end time. Specified in the format : hh:mm:ss or hh:mm. Default value is 00:00:00. If the end time is earlier than the start time then it is assumed the shift finishes on the next day.
<Duration> Optional NonNegativeInteger The shift's length in minutes. This can be used instead of EndTime. The maximum shift length is 48 hours minus the start time. That is, the shift can finish on the next day but not on the day after the next day (it can only span one midnight).
<Name> Optional string A name for this shift.
<Label> Optional string A label for the shift when displaying schedules. The ID is used if this element is omitted.
<Color> Optional string A colour for the shift when displaying schedules. Any valid HTML colour may be used.
<TimeUnits> Optional NonNegativeDouble The amount of working time this shift counts as. This is used by the Workload constraint.
In version 3.23+ if this tag is not included then a value in minutes is automatically calculated.
<AutoAllocate> Optional Boolean If false then this shift will not be assigned by the solver (except where it is pre-assigned in FixedAssignments). If this tag is omitted the default value is true.
<TimePeriods> Optional TimePeriods If the shift covers more than one time period in the day then the start and end times of the periods are specified here. This may be used to model shifts which actually represent a combination of two or more shifts.
<Resources> Optional Resources This can be used to define 'resources' other than TimeUnits. The resources defined here are used in the Workload constraint to impose minimum and/or maximum limits on the amount of a resource that can be assigned to an employee.

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 numerical values. Resource values may also be specified to be used only on certain days in the planning period.

Parents : Shift

Attributes

None

Elements

Resources contains zero or more <Resource> elements.

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

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

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

Element

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

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

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

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

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="FullTime">
    
        <Workload>
            <TimeUnits>
                <Max>
                    <Count>168</Count>
                    <Weight function="quadratic">100</Weight>
                    <Label>Max 168 hours</Label>
                </Max>
                <Min>
                    <Count>160</Count>
                    <Weight function="quadratic">100</Weight>
                    <Label>Min 160 hours</Label>
                </Min>
                <RegionStartDate>2014-09-01</RegionStartDate>
            </TimeUnits>
        </Workload>
        
        <!-- 
        Prevents the sequence off-on-off.
        -->
        <MinSeq label="Min two consecutive working days" value="2" shift="E,D,L"
                weight="1000"/>
        
        <!-- 
        Prevents the sequence on-off-on.
        -->
        <MinSeq label="Min two consecutive days off" value="2" shift="-"
                weight="1000"/>
        
        <!-- 
        Limit the employee to five consecutive working days.
        -->
        <MaxSeq label="Max five consecutive working days" value="5"
                shift="E,D,L" weight="1000"/>
        
        <!--
        MinRestTime constraint.
        -->
        <MinRestTime label="At least 14 hours rest after a shift"
                     weight="10000">840</MinRestTime>
    
    </Contract>  
</Contracts>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract. Note that since version 3.26 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 may contain zero or more of the following elements in any order.

Name Required Type Description Ver.
<Conditionals> Optional Conditionals Conditional constraints take the form of IF ... THEN ... statements. The IF and THEN expressions contain boolean variables and the operators 'AND' and 'OR'. The variables are defined in the Patterns and Workload constraints and will have the values true or false depending on whether the underlying pattern or workload constraint is satisfied. If the IF expression evaluates to true then the THEN expression must also evaluate to true otherwise the constraint is violated. 3.0+
<DailyRest> Optional DailyRest A minimum amount of continuous rest (non-work) time required during 24 hours. 3.31+
<Label> Optional string A label for this contract (used when displaying solutions). 3.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. 3.26+
<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). 3.26+
<MaxWeekends> Optional MaxWeekends Used for modelling constraints such as a maximum number of weekends or weekend shifts. 3.34+
<MinRestTime> Optional MinRestTime A minimum amount of rest (non-work) time in minutes required after shifts (or specific shifts). 3.24+
<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. 3.26+
<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). 3.26+
<MinWeekends> Optional MinWeekends Used for modelling constraints such as a minimum number of weekends or weekend shifts. 3.34+
<MultipleShiftsPerDay> Optional MultipleShiftsPerDay By default employees cannot be assigned more than one shift per day. This is used to allow more than one shift to assigned on a day. 3.19+
<Patterns> Optional Patterns This is a very general and flexible constraint which can model a wide variety of requirements on the employee's schedule. 3.0+
<RestBetweenDates> Optional RestBetweenDates A minimum amount of continuous rest (non-work) time required between two dates. 3.31+
<ValidShifts> Optional ValidShifts Used to restrict which shift types can be assigned to employees with this contract. This is a hard constraint, meaning only the shifts defined here can be assigned. If this tag is not used then all shift types can be assigned. 3.28+
<Workload> Optional 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). 3.0+

Example

<Contract ID="StandardConstraints">

    <!-- 
    Limit the employee to five consecutive working days.
    -->
    <MaxSeq label="Max five consecutive working days" value="5" shift="$" weight="1000"/>
    
    <!--
    MinRestTime constraint.
    -->
    <MinRestTime label="At least 14 hours rest after a shift" weight="10000">840</MinRestTime>
    
    <!-- 
    Prevent the sequence on-off-on.
    -->
    <MinSeq label="Min two consecutive days off" value="2" shift="-" weight="1000"/>
                
    <!--
    Let all staff be assigned these shifts:
    -->
    <ValidShifts shift="EA,DA,LA"/>                    
            
    <Workload>
        <TimeUnits>
            <Max>
                <Count>168</Count>
                <Weight function="quadratic">100</Weight>
                <Label>Max 168 hours</Label>
            </Max>
            <RegionStartDate>2014-09-01</RegionStartDate>
        </TimeUnits>
    </Workload>        

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

None

Elements

Workload contains one or more <TimeUnits> elements.

Name Required Type Description
<TimeUnits> Required 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.

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

None

Elements

Workload 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) a <ShiftGroup> (optional) and a <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.

Name Required Type Description
<Min> Optional Min The minimum number of time units.
<Max> Optional Max The maximum number of time units.
<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.
<ShiftGroup> Optional string If a ShiftGroup is specified then only work done during the shift types in this group will be counted. The group is specified using an ID defined in ShiftGroups. Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
<Resource> Optional string If a Resource is specified then units of that Resource are counted by the constraint instead of TimeUnits (the default resource). The Resource ID's and units of resource for each ShiftType are defined in ShiftTypes.

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

None

Elements

Min contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeDouble The minimum value.
<Weight> Optional NonNegativeDouble A value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic" , "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var> Optional ID If this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label> Optional string A label for this 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.

If the constraint has a weight it is a soft constraint and is part of the penalty 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

None

Elements

Max contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeDouble The maximum value.
<Weight> Optional NonNegativeDouble A value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var> Optional ID If this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label> Optional string A label for this constraint for when displaying a solution.

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

None

Elements

Min contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeInteger The minimum value.
<Weight> Optional NonNegativeDouble A value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic" , "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var> Optional ID If this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label> Optional string A label for this 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.

If the constraint has a weight it is a soft constraint and is part of the penalty 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

None

Elements

Max contains the following elements in any order.

Name Required Type Description
<Count> Required NonNegativeInteger The maximum value.
<Weight> Optional NonNegativeDouble A value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var> Optional ID If this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label> Optional string A label for this constraint for when displaying a solution.

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

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 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>Work both or neither days of the weekend</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 Indexes 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 Indexes The pattern is only matched if it starts on any day in the planning period except the days, dates and days of the week specified in this tag.
<Shift> Optional string Possible values are :
A shift ID  Match this shift. The shift is specified using an ID defined in ShiftTypes.
$ Match any shift (but not a day off).
- Match a day off.
* Match any shift or a day off.

Since version 3.28 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID.
<ShiftGroup> Optional string Match one of the shifts in this group of shifts. The group is specified using an ID defined in ShiftGroups.

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

Since version 3.28 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N") or by using a ShiftGroup ID, meaning match anything but one of the shifts in this group of shifts (including a day without a shift).
<NotGroup> Optional string Match anything but one of the shifts in this group of shifts (including a day without a shift). The group is specified using an ID defined in ShiftGroups.

Since version 3.28 it is also possible to specify a shift group as a comma separated list of ShiftType 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>

<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

None

Elements

Conditionals contains one or more <Conditional> elements.

Name Required Type Description
<Conditional> Required Conditional A conditional constraint.

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

None

Elements

Conditional contains a <Label> element (optional), an <If> and a <Then> element and 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).

Name Required Type Description
<Label> Optional string A label for this constraint for when displaying a solution.
<If> Required string A boolean logic expression for the IF statement.
<Then> Required string A boolean logic expression for the THEN statement.
<Weight> Optional NonNegativeDouble A value to represent this constraint's priority. If this element is omitted then the constraint is considered to be a hard constraint.

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>

<MinRestTime>

A minimum amount of rest (non-work) time in minutes required after shifts (or specific shifts).

By default if this tag is not used then there is no minimum rest time and overlapping shifts are also allowed. To prevent overlapping shifts use the value 0. To allow overlapping shifts but only for a maximum overlap time use a negative value. For example to allow shifts to overlap for up to 15 minutes use -15.

This constraint does not apply between shifts which start on the same day. If multiple shifts per day are allowed then also use the MinRestTime element in MultipleShiftsPerDay.

This tag is provided as a shortcut and internally generates Pattern constraints which prevent patterns that would violate this minimum rest time. Because of this any violations of this constraint are identifed in the solution XML as Pattern constraints but with the label provided here.

MinRestTime can optionally also include weight, label, shift and shiftGroup attributes.

If the shift attribute is used then this rest time is required after that shift only.

If the shiftGroup attribute is used then this rest time is required after all shifts in that group.

If neither shift or shiftGroup are used then this rest time is required after all shifts that are not already specified by a shift or shiftGroup.

Parents : Contract

Attributes

Name Required Type Description Ver.
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. 3.24+
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). 3.24+
shift Optional string A shift specified using an ID defined in ShiftTypes.
Since version 3.28 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.24+
shiftGroup Optional string A shift group specified using an ID defined in ShiftGroups.
Since version 3.28 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.24+

Type

Double

Example

<Contract ID="C1">
  <MinRestTime label="At least 8hrs off after a shift" weight="10000">480</MinRestTime>
  <MinRestTime shift="L1,L2,L3" label="At least 10hrs rest after late shifts" weight="10000">600</MinRestTime>
  <MinRestTime shift="N" label="At least 12hrs off after night shifts" weight="10000">720</MinRestTime>
</Contract>

<DailyRest>

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

Any violations of this constraint are identifed in the solution XML as Other violations with the constraint ID DailyRest.

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. 3.31+
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. 3.31+
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). 3.31+
restShifts Optional string A shift specified using an ID defined in ShiftTypes or a shift group specified using an ID defined in ShiftGroups. Rest shifts are considered rest (non-work) time.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.31+
nextDayException Optional string If the shift specified here is assigned on the next day then the DailyRest is always satisfied. This means that the constraint does not count if a required shift is assigned on the next day. "-" (hyphen) can also be used to specify a day off.
A shift is specified using an ID defined in ShiftTypes or a shift group specified using an ID 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") and "-" for a day off.
3.38+

Type

Double

Example

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

<RestBetweenDates>

A minimum amount of continuous rest (non-work) time in minutes required between two dates (with times).

Any violations of this constraint are identifed in the solution XML as Other violations with the constraint ID RestBetweenDates.

Parents : Contract

Attributes

Name Required Type Description Ver.
start Required DateTime The start date and time for the constraint. 3.31+
end Required DateTime The end date and time for the constraint. 3.31+
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. 3.31+
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). 3.31+
restShifts Optional string A shift specified using an ID defined in ShiftTypes or a shift group specified using an ID defined in ShiftGroups. Rest shifts are considered rest (non-work) time.
It is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.31+

Type

Double

Example

<Contract ID="C1">
  <RestBetweenDates start="2016-03-14T03:00:00" end="2016-03-21T03:00:00" 
                    label="Min 36hrs continuous rest between..." weight="100000"
                    restShifts="V,T">2160</RestBetweenDates>
</Contract>

<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. 3.26+
weight Required NonNegativeDouble The weight for the constraint. 3.26+
shift Optional string Indicates whether the constraint applies to days on, days off or specific shifts. Possible values are :
$   Working days (a day with a shift starting on it).
-   Days off (a day without a shift starting on it).
A shift ID    Specified using an ID defined in ShiftTypes.
A shift group ID    Specified using an ID defined in ShiftGroups.

Since version 3.27 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.26+
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. 3.26+
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. 3.26+
label Optional string A label for the constraint. The label is only used in visualisations such as Roster Booster. 3.26+

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

<MaxWeekends>, <MinWeekends>

<MaxWeekends> and <MinWeekends> are used to model the maximum and minimum total number of weekends that can be assigned to a person. A weekend is considered as being worked if there is a shift assigned which is inside or intersects the time window defined as the weekend (i.e. the shift end time is after the window start time and the shift start time is before the window end time).

If the countShifts attribute is used then a constraint is applied on the total number of shifts within weekends.

Parents : Contract

Attributes

Name Required Type Description Ver.
value Required NonNegativeInteger The maximum or minimum. 3.34+
startTime Required TimeOfDay The start time for the weekend definition. Specified in the format : hh:mm:ss or hh:mm. 3.34+
startDay Required string The day of the week the window start time is on. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'. 3.34+
endTime Required TimeOfDay The end time for the weekend definition. Specified in the format : hh:mm:ss or hh:mm. 3.34+
endDay Required string The day of the week the window end time is on. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'. 3.34+
weight Required NonNegativeDouble The weight for the constraint. 3.34+
ignoreShift Optional string The shift(s) defined here do not count as work during a weekend (for example vacation shifts). Possible values are :
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 ShiftType ID's (e.g. "E,D,L,N").
3.34+
countShifts Optional Boolean If this is true then the constraint counts the total number of shifts within the weekends rather than the number of weekends. 3.34+
startRegion 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. 3.34+
endRegion 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. 3.34+
label Optional string A label for the constraint. The label is only used in visualisations such as Roster Booster. 3.34+

Example

<MaxWeekends startDay="Friday" startTime="18:00" endDay="Monday" endTime="06:00" 
             value="2" weight="1000" 
             label="Max 2 weekends">

<MinWeekends startDay="Friday" startTime="18:00" endDay="Monday" endTime="06:00" 
             value="2" weight="1000" 
             label="Min 2 weekends">

<MaxWeekends startDay="Saturday" startTime="00:00" endDay="Monday" endTime="00:00" 
             value="8" weight="1000" countShifts="true" ignoreShift="V,T" 
             label="Max 8 weekend shifts">

<MinWeekends startDay="Saturday" startTime="00:00" endDay="Monday" endTime="00:00" 
             value="8" weight="1000" countShifts="true" ignoreShift="V,T" 
             label="Min 8 weekend shifts">

<ValidShifts>

Used to restrict which shift types can be assigned to an employee. This is a hard constraint, meaning only the shifts defined here can be assigned. If this tag is not used then all shift types can be assigned.

Parents : Contract

Attributes

Name Required Type Description Ver.
shift Required string A comma separated list of ShiftType ID's and/or ShiftGroup ID's.
Since version 3.35 it is also possible to use ShiftBlock ID's.
3.28+

Example

<ValidShifts shift="EA,DA,LA"/>

<Indexes>

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

Parents : Pattern, Pair, NotPair

Attributes

None

Elements

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

Name Required Type Description
<Day> Optional NonNegativeInteger An 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

<Match>
  <Max><Count>2</Count><Weight>1000</Weight></Max>
  <Pattern>
    <Starts>
      <Day>0</Day>
      <Day>2</Day>
      <Day>3</Day>
    </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>
      <Day>27</Day>
    </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>
  <Days>
    <Day>0</Day>
    <Day>1</Day>
    <Day>2</Day>
    <Day>3</Day>
    <Day>4</Day>
  </Days>
  <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>
    <Day>7</Day>
  </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>

<MultipleShiftsPerDay>

By default employees cannot be assigned more than one shift per day. To allow more than one shift to be assigned on a day use MultipleShiftsPerDay.

If this element is empty then every possible shift combination is valid.

If it is not empty then only shift combinations defined in <ValidGroup> elements or combinations which satisfy <MinRestTime> elements can be assigned on the same day.

Any combination defined in a <ValidGroup> is still valid even if it violates a <MinRestTime> element. In other words <ValidGroup> overrides <MinRestTime> constraints.

Parents : Contract

Attributes

None

Elements

MultipleShiftsPerDay contains zero or more <ValidGroup> and <MinRestTime> elements in any order. If MultipleShiftsPerDay is empty or has zero <ValidGroup> and <MinRestTime> elements then every shift combination is valid.

Name Required Type Description Ver.
<ValidGroup> Optional ValidGroup A combination of shifts. 3.19+
<MinRestTime> Optional MinRestTime A minimum amount of rest (non-work) time in minutes required after shifts (or specific shifts). 3.24+

Example

<MultipleShiftsPerDay>
  <MinRestTime>120</MinRestTime>
  <MinRestTime shift="E">180</MinRestTime>
  <ValidGroup>
    <Shift>E</Shift>
    <Shift>L</Shift>
  </ValidGroup>
  <ValidGroup>
    <Shift>E</Shift>
    <Shift>D</Shift>
    <Shift>N</Shift>
  </ValidGroup>
</MultipleShiftsPerDay>

<ValidGroup>

A valid combination of shifts that can be assigned together on a single day.

Parents : MultipleShiftsPerDay

Attributes

None

Elements

ValidGroup 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

<ValidGroup>
  <Shift>E</Shift>
  <Shift>N</Shift>
</ValidGroup>

<MinRestTime>

A minimum amount of rest (non-work) time in minutes required after shifts (or specific shifts).

By default if this tag is not used then there is no minimum rest time and overlapping shifts are also allowed. To prevent overlapping shifts use the value 0. To allow overlapping shifts but only for a maximum overlap time use a negative value. For example to allow shifts to overlap for up to 15 minutes use -15.

MinRestTime can optionally also include shift and shiftGroup attributes.

If the shift attribute is used then this rest time is required after that shift only.

If the shiftGroup attribute is used then this rest time is required after all shifts in that group.

If neither shift or shiftGroup are used then this rest time is required after all shifts that are not already specified by a shift or shiftGroup.

Parents : MultipleShiftsPerDay

Attributes

Name Required Type Description
shift Optional string A shift specified using an ID defined in ShiftTypes. Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
shiftGroup Optional string A shift group specified using an ID defined in ShiftGroups. Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").

Type

Double

Example

<MultipleShiftsPerDay>
  <MinRestTime>120</MinRestTime>
  <MinRestTime shift="E">180</MinRestTime>
  <MinRestTime shiftGroup="D1">60</MinRestTime>
</MultipleShiftsPerDay>

<Employees>

The employees.

Parents : SchedulingPeriod

Attributes

None

Elements

Contains zero or more Employee elements.

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

Example

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

<Employee>

An employee in the roster.

Parents : Employees

Attributes

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

Elements

Employee contains the following elements in any order. Since version 3.26, 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
<ContractID> Optional string The ID of the Contract which contains the work regulations and preferences (constraints) for this employee. Note that since version 3.26 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.
<Name> Optional string A label for the employee when displaying the solution. The ID is used if this element is omitted.
<Skills> Optional Skills The skills, qualifications, experience, training, group etc this employee has/belongs to.
<CoverResources> Optional 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.

Example

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

<Skills>

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

Parents : Employee

Attributes

None

Elements

Skills contains one or more <Skill> elements.

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

Example

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

<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

None

Elements

CoverResources contains one or more <CoverResource> elements.

Name Required Type Description
<CoverResource> Required 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.

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

Name Required Type Description
ID Required string An ID for this cover resource.

Elements

CoverResource contains one or more <Shift> elements.

Name Required Type Description
<Shift> Required NonNegativeDouble Shift is a NonNegativeDouble and has an ID (string) attribute.

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

None

Elements

Rules contains zero or more <Rule> elements.

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

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)

Since version 3.33 the fourth set of brackets can also contain a CoverResource ID defined in Employee.

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

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

None

Elements

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

Name Required Type Description
<Pair> Optional 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).
<NotPair> Optional 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).

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>
    <Day>0</Day>
    <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

None

Elements

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

Name Required Type Description
<Label> Optional string A label to describe the constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML).
<Day> Optional NonNegativeInteger If Day is used then the constraint only applies to this day in the scheduling period. The first day in the scheduling period is day zero.
<Days> Optional Indexes If Days is used then the constraint only applies to the days, dates and days of the week specified in this tag.
<Excludes> Optional Indexes If Excludes is used then the constraint applies to every day in the planning period except the days, dates and days of the week specified in this tag.
<Matches> Required Matches Matches contains valid employee-to-shift assignments which may be made for two or more employees on the same day (or offset days).
<Weight> Optional NonNegativeDouble A weight for the priority of this constraint. The higher the weight the more important the constraint is. If the Weight element is omitted then the constraint is assumed to be a hard constraint.

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

None

Elements

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

Name Required Type Description
<Label> Optional string A label to describe the constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML).
<Day> Optional NonNegativeInteger If Day is used then the constraint only applies to this day in the scheduling period. The first day in the scheduling period is day zero.
<Days> Optional Indexes If Days is used then the constraint only applies to the days, dates and days of the week specified in this tag.
<Excludes> Optional Indexes If Excludes is used then the constraint applies to every day in the planning period except the days, dates and days of the week specified in this tag.
<Matches> Optional Matches Matches contains employee-to-shift assignments which must not be made for two or more employees on the same day (or offset days).
<Weight> Optional NonNegativeDouble A weight for the priority of this constraint. The higher the weight the more important the constraint is. If the Weight element is omitted then the constraint is assumed to be a hard constraint.

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

None

Elements

Matches contains one or more <Match> elements.

Name Required Type Description
<Match> Required Match A set of employee-to-shift assignments.

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

None

Elements

Match contains at least one <Assignment> element.

Name Required Type Description
<Assignment> Required Assignment An employee-to-shift or employee-to-shift group assignment.

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>
    <Day>0</Day>
    <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

None

Elements

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

Name Required Type Description
<Employee> Required string The ID of the employee. The employee ID is defined in <Employees>.
<Shift> Optional string The ID of a Shift (see <ShiftTypes>). The value '*' can be used here to mean 'match any shift or a day without a shift'.

Shift optionally has an offset attribute which must be a positive or negative whole number (positive numbers may be prefixed with the + sign e.g. +1 or just 1).

Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
<ShiftGroup> Optional string The ID of a ShiftGroup (see <ShiftGroups>). The assignment is matched if the employee works one of the shifts from this group. The value '*' can be used here to mean 'match any shift or a day without a shift'.

ShiftGroup optionally has an 'offset' attribute which must be a positive or negative whole number (positive numbers may be prefixed with the + sign e.g. +1 or just 1).

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

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>

<ShiftBlocks>

Cover constraints may be specified per ShiftBlock. The ShiftBlocks are defined here and referenced in the cover constraints. A ShiftBlock is a sequence of consecutive shifts.

Parents : SchedulingPeriod

Attributes

None

Elements

ShiftBlocks contains zero or more <ShiftBlock> elements.

Name Required Type Description Ver.
<ShiftBlock> Optional ShiftBlock A sequence of consecutive shifts. 3.32+

Example

<ShiftBlocks>
  <ShiftBlock ID="SB1">
    <Shift>A</Shift>
    <Shift>A</Shift>
    <Shift>B</Shift>
    <Shift>B</Shift>
  </ShiftBlock>
  <ShiftBlock ID="SB2">
    <Shift>A</Shift>
    <Shift>-</Shift>
    <Shift>B</Shift>
    <Shift>C</Shift>
  </ShiftBlock>
  <ShiftBlock ID="SB3">
    <Shift>A,B</Shift>
    <Shift>C</Shift>
    <Shift>A,B</Shift>
    <Shift>D</Shift>
    <Shift>D</Shift>
  </ShiftBlock>
</ShiftBlocks>

<ShiftBlock>

A sequence of consecutive shifts.

The block may contain a day without a shift on by using a hyphen: <Shift>-</Shift>.

If multiple shifts per day are allowed then they can be included by separating each shift ID with a comma. For example: <Shift>ID1, ID2</Shift>.

Parents : ShiftBlocks

Attributes

Name Required Type Description Ver.
ID Required ID A unique ID for this ShiftBlock. 3.32+

Elements

ShiftBlock contains one or more <Shift> elements.

Name Required Type Description Ver.
<Shift> Required string The ID of a shift type. Specified in Shift attribute 'ID'. Use a hyphen '-' to represent a day without a shift. To list multiple shifts on a single day, separate each ID using a comma. 3.32+

Example

<ShiftBlocks>
  <ShiftBlock ID="SB1">
    <Shift>A</Shift>
    <Shift>A</Shift>
    <Shift>B</Shift>
    <Shift>B</Shift>
  </ShiftBlock>
  <ShiftBlock ID="SB2">
    <Shift>A</Shift>
    <Shift>-</Shift>
    <Shift>B</Shift>
    <Shift>C</Shift>
  </ShiftBlock>
  <ShiftBlock ID="SB3">
    <Shift>A,B</Shift>
    <Shift>C</Shift>
    <Shift>A,B</Shift>
    <Shift>D</Shift>
    <Shift>D</Shift>
  </ShiftBlock>
</ShiftBlocks>

<CoverRequirements>

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

Parents : SchedulingPeriod

Attributes

None

Elements

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

Name Required Type Description
<DayOfWeekCover> Optional DayOfWeekCover The cover requirements on a specific day of the week. For example the number of shifts needing assigning on a Monday.
<DateSpecificCover> Optional DateSpecificCover The cover requirements on a specific date in the scheduling horizon.

<DayOfWeekCover>

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

Parents : CoverRequirements

Attributes

None

Elements

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

Name Required Type Description
<Day> Required string A day of the week. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
<Cover> Required Cover The min and/or max numbers of employees (optionally with certain skills) covering shifts/time periods.

Example

<DayOfWeekCover>
  <Day>Friday</Day>
  <Cover>
    <ShiftGroup>N</ShiftGroup>
    <Min weight="1000">4</Min>
  </Cover>
  <Cover>
    <Skill>LevelA</Skill>
    <ShiftGroup>N</ShiftGroup>
    <Min weight="100">1</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Na</Shift>
    <Min weight="1000">1</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Nb</Shift>
    <Min weight="1000">1</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Nc</Shift>
    <Min weight="1000">1</Min>
  </Cover>
  <Cover>
    <ShiftGroup>D</ShiftGroup>
    <Min weight="1000">10</Min>
    <Max weight="1000">11</Max>
  </Cover>
  <Cover>
    <Skill>LevelA</Skill>
    <ShiftGroup>D</ShiftGroup>
    <Min weight="100">1</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Da</Shift>
    <Min weight="1000">2</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Db</Shift>
    <Min weight="1000">2</Min>
  </Cover>
  <Cover>
    <Skill>LevelA, LevelB</Skill>
    <Shift>Dc</Shift>
    <Min weight="1000">2</Min>
  </Cover>
  <Cover>
    <Shift>Da</Shift>
    <Min weight="1000">3</Min>
    <Max weight="10">4</Max>
  </Cover>
  <Cover>
    <Shift>Db</Shift>
    <Min weight="1000">3</Min>
    <Max weight="10">4</Max>
  </Cover>
  <Cover>
    <Shift>Dc</Shift>
    <Min weight="1000">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

None

Elements

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

Name Required Type Description
<Date> Required Date A date. Specified in the format : YYYY-MM-DD.
<Day> Required NonNegativeInteger The day in the scheduling period these cover requirements apply to. The scheduling period starts on day zero.
<Cover> Required Cover The min and/or max numbers of employees (optionally with certain skills) covering shifts/time periods.

Example

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

<Cover>

The min and/or max numbers of employees (optionally with certain skills) covering shifts or time periods. For a information on modelling cover requirements which include skills see the FAQ: How to model cover constraints that include skills?

<Min> and <Max> may use weight attributes to indicate they are soft constraints (i.e. part of the penalty 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

None

Elements

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

Since version 3.28 multiple <Min> and/or <Max> tags are allowed within in a single <Cover> tag.

Name Required Type Description Ver.
<Skill> Optional string The min or max number of employees covering this shift type or time period must also have this skill. (An employee's skills are defined in Employee). Since version 3.28 a comma separated list of Skill ID's may also be provided to represent a SkillGroup. 3.0+
<SkillGroup> Optional string The min or max number of employees covering this shift type or time period must also have at least one of the skills in this skill group. The skill group is specified using an ID defined in SkillGroups. Since version 3.28 a comma separated list of Skill ID's may also be provided to represent a SkillGroup. 3.0+
<TimePeriod> Optional TimePeriod The time period this cover requirement applies to. The TimePeriod element can also include a Shift or ShiftGroup attribute to indicate that only that shift or shifts within in that shift group count as work during this time period. 3.0+
<Shift> Optional string The shift type this cover requirement applies to. The shift type is specified using an ID defined in ShiftTypes. 3.0+
<ShiftGroup> Optional string The shift group this cover requirement applies to. The shift group is specified using an ID defined in ShiftGroups. If this tag is used then the min and max requirements apply to the group of shifts, not to each shift. For example if minimum 2 staff are required for a shift group containing shifts A and B, then it can be satisfied by assigning 2 staff to shift A and 0 to shift B or by assigning 2 staff to B and 0 or A or by assigning 1 to A and 1 to B.
Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
3.0+
<ShiftBlock> Optional string The ShiftBlock this cover requirement applies to. The ShiftBlock is specified using an ID defined in ShiftBlocks. 3.32+
<Min> Optional NonNegativeDouble The minimum number of employees required during this time period or shift type.

Min optionally has a function attribute to indicate whether the constraint is a hard constraint or soft constraint. Valid values are 'Linear', 'Quadratic' or 'Constraint'. If the function attribute is not used then the constraint is assumed to be a hard constraint.

Min also optionally has a weight attribute (NonNegativeDouble) to be used if the function is linear or quadratic.
3.0+
<Max> Optional NonNegativeDouble The maximum number of employees required during this time period or shift type.

Max optionally has a function attribute to indicate whether the constraint is a hard constraint or soft constraint. Valid values are 'Linear', 'Quadratic' or 'Constraint'. If the function attribute is not used then the constraint is assumed to be a hard constraint.

Max also optionally has a weight attribute (NonNegativeDouble) to be used if the function is linear or quadratic.
3.0+
<Label> Optional string A label used to describe the constraint. This is only used when displaying the solutions and identifying the violations (for example in the solution XML). 3.0+
<CoverResource> Optional string When an employee is assigned to the shift(s) or time period for this cover constraint, by default the cover count is increased by one. However, if necessary the cover count can be increased by a value other than one by specifying a cover resource ID in this tag. The ID should reference a cover resource defined in Employee. 3.0+

Example

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

<TimePeriods>

TimePeriods contains zero or more <TimePeriod> elements.

Parents : Shift

Attributes

None

Elements

TimePeriods contains zero or more <TimePeriod> elements.

Name Required Type Description
<TimePeriod> Optional TimePeriod A time period in the day.

Example

<Shift ID="D1">
  <Label>D1</Label>
  <TimePeriods>
    <TimePeriod><Start>08:30:00</Start><End>13:30:00</End></TimePeriod>
    <TimePeriod><Start>17:30:00</Start><End>22:30:00</End></TimePeriod>
  </TimePeriods>
</Shift>

<TimePeriod>

A time period in the day.

Parents : TimePeriods

Attributes

None

Elements

TimePeriod contains two elements in any order:

Name Required Type Description
<Start> Required TimeOfDay When the period begins. Specified in the format : hh:mm:ss or hh:mm.
<End> Required TimeOfDay When the period ends. Specified in the format : hh:mm:ss or hh:mm.

Example

<TimePeriod>
  <Start>15:30:00</Start>
  <End>19:30:00</End>
</TimePeriod>

<TimePeriod>

A time period in the day.

Parents : Cover

Attributes

Name Required Type Description
allowSplit optional Boolean If a shift and time period intersect such that the shift does not cover the time period entirely then the solver splits up the time period into separate time periods in order to remove partial coverings. For example, for an instance with a 12:00-20:00 shift and a cover constraint for 18:00-00:00, the solver will split the cover constraint into the following time periods: 12:00-18:00, 18:00-20:00 and 20:00-00:00.
If however you do not want the solver to split up a time period but count cover towards the time period even if a shift only covers it partially then set this attribute to false. If this attribute is omitted then the value is true by default.
shift optional string A shift ID (see ShiftTypes). If this attribute is used then only cover provided by this shift is counted during this time period for the constraint.
Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
shiftGroup optional string A shift group ID (see ShiftGroups). If this attribute is used then only cover provided by a shift in this group is counted during this time period for the constraint.
Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").

Elements

TimePeriod contains two child elements in any order:

Name Required Type Description
<Start> Required TimeOfDay When the period begins. Specified in the format : hh:mm:ss or hh:mm.
<End> Required TimeOfDay When the period ends. Specified in the format : hh:mm:ss or hh:mm.

Example

<TimePeriod>
  <Start>15:30:00</Start>
  <End>19:30:00</End>
</TimePeriod>

<DayOffRequests>

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

Parents : SchedulingPeriod

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

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

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

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

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

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

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

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

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>A01</EmployeeID>
    <Assign>
      <Shift>O</Shift>
      <Date>2009-05-04</Date>
    </Assign>
    <Assign>
      <Shift>O</Shift>
      <Date>2009-05-05</Date>
    </Assign>
  </Employee>
  <Employee>
    <EmployeeID>A07</EmployeeID>
    <Assign>
      <Shift>O</Shift>
      <Date>2009-05-04</Date>
    </Assign>
  </Employee>
</FixedAssignments>

<Employee>

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

Parents : FixedAssignments

Attributes

None

Elements

Employee contains an <EmployeeID> element followed by zero or more <Assign> elements.

Name Required Type Description
<EmployeeID> Required string The ID of the employee the assignments belong to. The employee ID is defined in <Employees>.
<Assign> Optional Assign A shift on or day off assignment.

Example

<Employee>
  <EmployeeID>E1</EmployeeID>
  <Assign>
    <Shift>V</Shift>
    <Date>2003-01-06</Date>
  </Assign>
  <Assign>
    <Shift>V</Shift>
    <Date>2003-01-07</Date>
  </Assign>
  <Assign>
    <Shift>V</Shift>
    <Date>2003-01-08</Date>
  </Assign>
  <Assign>
    <Shift>V</Shift>
    <Date>2003-01-09</Date>
  </Assign>
  <Assign>
    <Shift>V</Shift>
    <Date>2003-01-10</Date>
  </Assign>
</Employee>

<Assign>

A shift assignment (or day off).

Parents : Employee

Attributes

None

Elements

Assign contains a <Shift> element and a <Date> or a <Day> element.

Name Required Type Description
<Shift> Required string An ID for a shift type (defined in <Employees>) or a hyphen/minus sign (-) for a day off (a day without a shift assigned).
<Date> Required Date The date of this assignment (in the format : YYYY-MM-DD).
<Day> Required NonNegativeInteger The day in the planning period of this assignment (the planning period starts on day zero).

Example

<Assign>
  <Shift>V</Shift>
  <Date>2003-01-06</Date>
</Assign>

Boolean

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

Date

Date must be in the format : YYYY-MM-DD.

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.

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.

ID

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

Double

A number which can be negative, zero or positive and may also be fractional. That is, it can have a decimal component. For example -15, -1.5, 0, 1, 1.333, 1.5, 10.25, 1000 are all valid values.

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.

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 there should be four night shifts assigned on a particular day (with a weight of 10) but the engine decides that in order to better satisfy some other soft constraints there should be six assigned then a penalty of (6-4)*10=20 (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.