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 RosterViewer. The data format is an XML based format and so can be created and edited using any text editor. An XML aware editor is recommended to allow the data to be validated against the format's schema as it is edited. Many XML editors also provide other useful features such as tag suggestion and auto-completion.

To help get started 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.

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

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

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

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

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

<SchedulingPeriod>

The root element of the document.

Attributes

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+
function	Optional	string	The penalty function for the constraint. Valid values are "Linear", "Quadratic", or "Constant" (case-insensitive). The default value is "Linear" if the attribute is not used.	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 RosterViewer.	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.

If the shiftStartOnly attribute is used then a shift is only counted as a weekend shift if it starts within the weekend interval.

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+
shiftStartOnly	Optional	Boolean	If this is true then shifts are counted as weekend shifts if they start within the weekend interval. If this is false then shifts are counted as weekend shifts if they overlap with the defined weekend interval.	3.44+
regionStart	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+
regionEnd	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 RosterViewer.	3.34+
isSeq	Optional	Boolean	If true, the constraint models the maximum number of consecutive weekends. False by default.	3.46+
previousSeq	Optional	NonNegativeInteger	The number of previous consecutive weekends worked before the start of this scheduling period.	3.46+

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 specified, the function will be linear by default.

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.