This document describes the data format used for AutoRoster solutions.
After the rostering engine has solved the problem it returns the solution as XML.
The XML schema is available here.
If there are any constraint violations in the solution (for example, if the problem
is over-constrained), then the rostering engine will include the location of the violations
in the <Violations> tag.
A solution XML file can also be opened using RosterViewer if a
<SchedulingPeriodFile> tag is added after the
opening <Roster> tag. The SchedulingPeriodFile is
the path to the problem instance XML that this solution was generated from. The path can be absolute
or relative to the solution file. For example:
<?xml version="1.0" encoding="UTF-8"?> <Roster> <SchedulingPeriodFile>..\..\AutoRosterExample-1.xml</SchedulingPeriodFile> <Employee ID="E1">... </Roster>
The root element (opening tag) of the XML is <Roster>.
The root element of the document.
Attributes
None
Elements
Roster contains zero or more <Employee> elements followed by a <Violations> element.
Name | Required | Type | Description |
<Employee> | Optional | Employee | Contains the assignments in the solution for an employee. |
<Violations> | Optional | Violations | Contains all the constraint violations in this solution. |
Example
<?xml version="1.0" encoding="UTF-8"?> <Roster xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Roster.xsd"> <Employee ID="A01"> <Assign> <Day>3</Day> <Shift>D</Shift> </Assign> <Assign> <Day>4</Day> <Shift>N</Shift> </Assign> <Assign> <Day>7</Day> <Shift>D</Shift> </Assign> <Assign> <Day>9</Day> <Shift>D</Shift> </Assign> <Assign> <Day>10</Day> <Shift>D</Shift> </Assign> <Assign> <Day>12</Day> <Shift>N</Shift> </Assign> </Employee> </Roster>
Contains the assignments in the solution for an employee.
Parents : Roster
Attributes
Name | Required | Type | Description |
ID | Required | string | The ID of this employee (defined in the problem instance). |
Elements
Employee contains zero or more <Assign> elements.
Name | Required | Type | Description |
<Assign> | Optional | Assign | A shift assignment. |
Example
<Employee ID="A01"> <Assign> <Day>3</Day> <Shift>D</Shift> </Assign> <Assign> <Day>4</Day> <Shift>N</Shift> </Assign> <Assign> <Day>7</Day> <Shift>D</Shift> </Assign> <Assign> <Day>9</Day> <Shift>D</Shift> </Assign> <Assign> <Day>10</Day> <Shift>D</Shift> </Assign> <Assign> <Day>12</Day> <Shift>N</Shift> </Assign> </Employee>
A shift assignment.
Parents : Employee
Attributes
None
Elements
Assign contains a <Day> element followed by a <Shift> element.
Name | Required | Type | Description |
<Day> | Required | NonNegativeInteger | The day in the planning period of this assignment (the first day in the planning period is day zero). |
<Shift> | Required | string | A shift type ID (defined in the problem instance). Since version 3.35 if the instance contains ShiftBlocks and a ShiftBlock is assigned on this day then the attribute: type="shiftBlock" is included and the ID refers to the ShiftBlock instead e.g. <Shift type="shiftBlock">SB1</Shift> |
Example
<Assign> <Day>12</Day> <Shift>N</Shift> </Assign>
Contains information on all constraint violations in the roster.
Parents : Roster
Attributes
None
Elements
Violations contains a sequence of four child elements (all optional) in the following order:
Name | Required | Type | Description |
<EmployeeViolations> | Optional | EmployeeViolations | Violations in each employee's schedule due to the constraints in their contract or day/shift off/on requests. |
<RuleViolations> | Optional | RuleViolations | Violations of 'Rule' constraints (see Rules in the problem format). |
<EmployeePairingsViolations> | Optional | EmployeePairingsViolations | Violations of constraints on employees who should or should not work at the same time (see EmployeePairings in the problem format). |
<CoverViolations> | Optional | CoverViolations | Violations of cover (shift demand) constraints. |
Example
<Violations> <EmployeeViolations> <Employee ID="A"> <Requests> <Violation> <ID>L</ID> <Label>ShiftOn</Label> <Penalty>1</Penalty> <Cell>5</Cell> </Violation> <Violation> <ID>L</ID> <Label>ShiftOn</Label> <Penalty>1</Penalty> <Cell>7</Cell> </Violation> </Requests> <Patterns> <Violation> <Label>Min 2 consecutive 'N' shifts</Label> <Count>1</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1</Penalty> <Matches> <Cells> <Cell>12</Cell> <Cell>13</Cell> <Cell>14</Cell> </Cells> </Matches> </Violation> </Patterns> </Employee> <Employee ID="B"> <Patterns> <Violation> <Label></Label> <Count>2</Count> <WeightFunction>Linear</WeightFunction> <Penalty>200</Penalty> <Matches> <Cells> <Cell>5</Cell> <Cell>6</Cell> </Cells> <Cells> <Cell>19</Cell> <Cell>20</Cell> </Cells> </Matches> </Violation> <Violation> <Label>No night shift before a free weekend</Label> <Count>1</Count> <WeightFunction>Linear</WeightFunction> <Penalty>0</Penalty> <Matches> <Cells> <Cell>25</Cell> <Cell>26</Cell> <Cell>27</Cell> </Cells> </Matches> </Violation> </Patterns> </Employee> </EmployeeViolations> <CoverViolations> <Violation> <Shift>L</Shift> <Label></Label> <Count>3</Count> <Penalty>1</Penalty> <Cell>6</Cell> </Violation> <Violation> <Shift>L</Shift> <Label></Label> <Count>3</Count> <Penalty>1</Penalty> <Cell>20</Cell> </Violation> </CoverViolations> </Violations>
Violations in each employee's schedule from the constraints in their contract or day off/shift requests.
Parents : Violations
Attributes
None
Elements
EmployeeViolations contains zero or more <Employee> elements:
Name | Required | Type | Description |
<Employee> | Optional | Employee | Violations in an employee's schedule. |
Example
<EmployeeViolations> <Employee ID="A"> <Requests> <Violation> <ID></ID> <Label>CellOff</Label> <Penalty>1</Penalty> <Cell>19</Cell> </Violation> </Requests> <Patterns> <Violation> <Label>Min 2 consecutive E shifts</Label> <Count>1</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1</Penalty> <Matches> <Cells> <Cell>8</Cell> <Cell>9</Cell> <Cell>10</Cell> </Cells> </Matches> </Violation> </Patterns> </Employee> <Employee ID="B"> <Requests> <Violation> <ID></ID> <Label>CellOff</Label> <Penalty>1</Penalty> <Cell>6</Cell> </Violation> </Requests> </Employee> </EmployeeViolations>
Violations in an employee's schedule.
Parents : EmployeeViolations
Attributes
Name | Required | Type | Description |
ID | Required | string | The ID of this employee (defined in the problem instance). |
Elements
Employee contains the following elements (all optional) in any order:
Name | Required | Type | Description |
<Patterns> | Optional | Patterns | Violations of Pattern constraints (see Patterns in the problem format). |
<Workload> | Optional | Workload | Violations of Workload constraints (see Workload in the problem format). |
<Requests> | Optional | Requests | Violations of Day/Shift On/Off request constraints. |
<Conditionals> | Optional | Conditionals | Violations of Conditional constraints (see Conditionals in the problem format). |
<Other> | Optional | Other | Violations of other constraints (such as DailyRest, RestBetweenDates). |
Example
<Employee ID="B"> <Patterns> <Violation> <Label>Min 2 consecutive free shifts</Label> <Count>1</Count> <WeightFunction>Linear</WeightFunction> <Penalty>10</Penalty> <Matches> <Cells> <Cell>15</Cell> <Cell>16</Cell> <Cell>17</Cell> </Cells> </Matches> </Violation> <Violation> <Label>Max two shifts in this week</Label> <Count>3</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1</Penalty> <Matches> <Cells> <Cell>4</Cell> </Cells> <Cells> <Cell>5</Cell> </Cells> <Cells> <Cell>6</Cell> </Cells> </Matches> </Violation> </Patterns> </Employee>
Violations of Pattern constraints (see Patterns in the problem format).
Parents : Employee
Attributes
None
Elements
Patterns contains zero or more <Violation> elements
Name | Required | Type | Description |
<Violation> | Optional | Violation | A violation of this constraint. |
Example
<Patterns> <Violation> <Label>Min 2 consecutive free shifts</Label> <Count>1</Count> <WeightFunction>Linear</WeightFunction> <Penalty>10</Penalty> <Matches> <Cells> <Cell>15</Cell> <Cell>16</Cell> <Cell>17</Cell> </Cells> </Matches> </Violation> <Violation> <Label>Max two shifts in this week</Label> <Count>3</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1</Penalty> <Matches> <Cells> <Cell>4</Cell> </Cells> <Cells> <Cell>5</Cell> </Cells> <Cells> <Cell>6</Cell> </Cells> </Matches> </Violation> </Patterns>
Violations of Workload constraints (see Workload in the problem format).
Parents : Employee
Attributes
None
Elements
Workload contains zero or more <Violation> elements
Name | Required | Type | Description |
<Violation> | Optional | Violation | A violation of this constraint. |
Example
<Workload> <Violation> <Label>Max 30 hours</Label> <Count>40</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1000</Penalty> <Cells> <Cell>7</Cell> <Cell>8</Cell> <Cell>9</Cell> <Cell>10</Cell> </Cells> </Violation> </Workload>
Violations of Day/Shift On/Off request constraints.
Parents : Employee
Attributes
None
Elements
Requests contains zero or more <Violation> elements
Name | Required | Type | Description |
<Violation> | Optional | Violation | A violation of this constraint. |
Example
<Requests> <Violation> <ID>O</ID> <Label>ShiftOn</Label> <Penalty>1</Penalty> <Cell>26</Cell> </Violation> <Violation> <ID>O</ID> <Label>ShiftOn</Label> <Penalty>1</Penalty> <Cell>27</Cell> </Violation> <Violation> <ID>N</ID> <Label>ShiftGroupOn</Label> <Penalty>1</Penalty> <Cell>21</Cell> </Violation> </Requests>
Violations of Conditional constraints (see Conditionals in the problem format).
Parents : Employee
Attributes
None
Elements
Conditionals contains zero or more <Violation> elements
Name | Required | Type | Description |
<Violation> | Optional | Violation | A violation of this constraint. |
Example
<Conditionals> <Violation> <Label>If more than 150 hours worked then no night shifts and at least one weekend off.</Label> <Penalty>1000</Penalty> </Violation> <Violation> <Label>If the employee has at least one early shift in week one then they should have zero early shifts in week two.</Label> <Penalty>10000</Penalty> </Violation> </Conditionals>
Violations of constraints such as DailyRest and RestBetweenDates.
Parents : Employee
Attributes
None
Elements
Other contains one or more <Violation> elements
Name | Required | Type | Description |
<Violation> | Optional | Violation | A violation of a constraint. |
Example
<Other> <Violation> <Constraint>RestBetweenDates</Constraint> <Label>Min 36hrs consecutive rest between...</Label> <Count>1</Count> <WeightFunction>Constant</WeightFunction> <Penalty>1000</Penalty> <Cells> <Cell>0</Cell> <Cell>1</Cell> <Cell>2</Cell> <Cell>3</Cell> <Cell>4</Cell> <Cell>5</Cell> <Cell>6</Cell> </Cells> </Violation> </Other>
Violation of a Pattern constraint.
Parents : Patterns
Attributes
None
Elements
Violation contains a sequence of four elements in the following order:
Name | Required | Type | Description |
<Label> | Required | string | This is the label used in the constraint definition (see Patterns in the problem format). This tag will be empty if no label was provided. |
<Count> | Required | NonNegativeInteger | Count is the number of matches of the pattern(s). |
<WeightFunction> | Required | string | The weight function used for the constraint. For example, 'Linear', 'Quadratic', 'Constant' or 'Constraint'. |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
<Matches> | Required | Matches | Lists the locations of each pattern match in an employee's schedule. |
Example
<Violation> <Label>Max two shifts in this week</Label> <Count>3</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1</Penalty> <Matches> <Cells> <Cell>4</Cell> </Cells> <Cells> <Cell>5</Cell> </Cells> <Cells> <Cell>6</Cell> </Cells> </Matches> </Violation>
Lists the locations of each pattern match in an employee's schedule.
Parents : Violation
Attributes
None
Elements
Matches contains zero or more <Cells> elements
Name | Required | Type | Description |
<Cells> | Optional | Cells | Lists the days in the employee's schedule where a match is found. |
Example
<Matches> <Cells> <Cell>4</Cell> </Cells> <Cells> <Cell>5</Cell> </Cells> <Cells> <Cell>6</Cell> <Cell>7</Cell> <Cell>8</Cell> </Cells> </Matches>
Violation of a Workload constraint.
Parents : Workload
Attributes
None
Elements
Violation contains a sequence of four elements in the following order:
Name | Required | Type | Description |
<Label> | Required | string | This is the label used in the constraint definition (see Workload in the problem format). This tag will be empty if no label was provided. |
<Count> | Required | NonNegativeDouble | Count is the number of time units (or other resource) assigned in the solution. |
<WeightFunction> | Required | string | The weight function used for the constraint. For example, 'Linear', 'Quadratic', 'Constant' or 'Constraint'. |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
<Cells> | Required | Cells | Lists the days in the employee's schedule where the constraint is violated. For maximum constraints it just contains the days with shifts assigned on. For minimum constraints it contains all the days in the constraint's range. |
Example
<Violation> <Label>Max 30 hours</Label> <Count>40</Count> <WeightFunction>Linear</WeightFunction> <Penalty>1000</Penalty> <Cells> <Cell>7</Cell> <Cell>8</Cell> <Cell>9</Cell> <Cell>10</Cell> </Cells> </Violation>
Violation of a constraint.
Parents : Other
Attributes
None
Elements
Violation contains a sequence of four elements in the following order:
Name | Required | Type | Description |
<Constraint> | Required | string | The constraint ID. |
<Label> | Required | string | This is the label used in the constraint definition. This tag will be empty if no label was provided. |
<Count> | Required | NonNegativeDouble | Count is a number of violations in the solution. |
<WeightFunction> | Required | string | The weight function used for the constraint. For example, 'Linear', 'Quadratic', 'Constant' or 'Constraint'. |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
<Cells> | Required | Cells | Lists the days in the employee's schedule where the constraint is violated. |
Example
<Violation> <Constraint>RestBetweenDates</Constraint> <Label>Min 36hrs consecutive rest between...</Label> <Count>1</Count> <WeightFunction>Constant</WeightFunction> <Penalty>1000</Penalty> <Cells> <Cell>0</Cell> <Cell>1</Cell> <Cell>2</Cell> <Cell>3</Cell> <Cell>4</Cell> <Cell>5</Cell> <Cell>6</Cell> </Cells> </Violation>
Violation of a Requests constraint.
Parents : Requests
Attributes
None
Elements
Violation contains a sequence of four elements in the following order:
Name | Required | Type | Description |
<ID> | Required | string | For ShiftOff and ShiftOn constraints this is the ShiftTypeID. For ShiftGroupOn constraints this is the ShiftGroupID. For day off and on constraints this tag is empty. |
<Label> | Required | string | Label will contain one of the following strings: Day off requests : "CellOff" Day on requests : "CellOn" Shift off requests : "ShiftOff" Shift on requests : "ShiftOn" Shift group on requests : "ShiftGroupOn" |
<Penalty> | Required | NonNegativeDouble | The penalty caused by the violation. |
<Cell> | Required | NonNegativeInteger | The day in the employee's schedule where the constraint is violated. |
Example
<Violation> <ID>E</ID> <Label>ShiftGroupOn</Label> <Penalty>1</Penalty> <Cell>3</Cell> </Violation>
Violation of a Conditional constraint.
Parents : Conditionals
Attributes
None
Elements
Violation contains a sequence of two elements in the following order:
Name | Required | Type | Description |
<Label> | Required | string | This is the label used in the constraint definition (see Conditionals in the problem format). This tag will be empty if no label was provided. |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
Example
<Violation> <Label>If the employee has a night shift or a late shift then they should have at least two Fridays off</Label> <Penalty>10</Penalty> </Violation>
Violations of 'Rule' constraints (see Rules in the problem format).
Parents : Violations
Attributes
None
Elements
RuleViolations contains zero or more <Violation> elements:
Name | Required | Type | Description |
<Violation> | Optional | Violation | Violation of a 'Rule' constraint. |
Example
<RuleViolations> <Violation> <Label>1 and 2 must not both work E on day 0</Label> <Penalty>10000</Penalty> <Cells Employee="1"> <Cell>0</Cell> </Cells> <Cells Employee="2"> <Cell>0</Cell> </Cells> </Violation> <Violation> <Label>Example Rule1</Label> <Penalty>10</Penalty> <Cells Employee="3"> <Cell>0</Cell> <Cell>1</Cell> <Cell>2</Cell> <Cell>3</Cell> <Cell>4</Cell> <Cell>5</Cell> <Cell>6</Cell> </Cells> </Violation> </RuleViolations>
Violation of a 'Rule' constraint.
If a rule constraint is violated then a <Violation> element will be present. For each employee linked to the rule (by being in a variable in the rule) a separate <Cells> element is included in the <Violation> element to indicate which days are relevant to that employee in this rule.
Parents : RuleViolations
Attributes
None
Elements
Violation contains a <Label> element followed by a <Penalty> element and zero or more <Cells> elements in that order.
Name | Required | Type | Description |
<Label> | Required | string | The label used in the Rule definition
(see Rules in the problem format).
If no label was provided then this tag will be empty. |
<Penalty> | Required | NonNegativeDouble | The penalty due to the violation. |
<Cells> | Optional | Cells | Lists the days in the employee's schedule which are linked to this rule by being in variables within the rule. |
Example
<RuleViolations> <Violation> <Label>1 and 2 must not both work E on day 0</Label> <Penalty>10000</Penalty> <Cells Employee="1"> <Cell>0</Cell> </Cells> <Cells Employee="2"> <Cell>0</Cell> </Cells> </Violation> <Violation> <Label>Example Rule1</Label> <Penalty>10</Penalty> <Cells Employee="3"> <Cell>0</Cell> <Cell>1</Cell> <Cell>2</Cell> <Cell>3</Cell> <Cell>4</Cell> <Cell>5</Cell> <Cell>6</Cell> </Cells> </Violation> </RuleViolations>
Violations of constraints related to two or more employees working (or not working) at the same time (see EmployeePairings in the problem format).
Parents : Violations
Attributes
None
Elements
EmployeePairingsViolations contains zero or more <Violation> elements:
Name | Required | Type | Description |
<Violation> | Optional | Violation | Violation of a constraint related to two or more employees working (or not working) at the same time. |
Example
<EmployeePairingsViolations> <Violation> <Employee>D</Employee> <Employee>F</Employee> <Label>D and F should not work together</Label> <Count>2</Count> <Penalty>2</Penalty> <Cells> <Cell>1</Cell> <Cell>24</Cell> </Cells> </Violation> </EmployeePairingsViolations>
Violation of a constraint related to two or more employees working (or not working) at the same time.
Parents : EmployeePairingsViolations
Attributes
None
Elements
Violation contains a sequence of two or more <Employee> elements followed by <Label>, <Count>, <Penalty> and <Cells> elements.
Name | Required | Type | Description |
<Employee> | Required | string | The ID of the employees involved in the constraint. |
<Label> | Required | string | This is the label used in the constraint definition
(see EmployeePairings
in the problem format).
If no label was provided then this tag will be empty. |
<Count> | Required | NonNegativeInteger | The number of violations of this constraint in this solution. |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
<Cells> | Required | Cells | Lists the days in the employees' schedules where the constraint is violated. |
Example
<Violation> <Employee>C</Employee> <Employee>D</Employee> <Label>C and D should work together</Label> <Count>1</Count> <Penalty>100</Penalty> <Cells> <Cell>1</Cell> </Cells> </Violation>
Violations of cover/demand constraints.
Parents : Violations
Attributes
None
Elements
CoverViolations contains zero or more <Violation> elements:
Name | Required | Type | Description |
<Violation> | Optional | Violation | Violation of a cover/demand constraint. |
Example
<CoverViolations> <Violation> <Shift>L</Shift> <Label></Label> <Count>3</Count> <Penalty>1</Penalty> <Cell>6</Cell> </Violation> <Violation> <Shift>L</Shift> <Label></Label> <Count>3</Count> <Penalty>1</Penalty> <Cell>20</Cell> </Violation> </CoverViolations>
Violation of a cover/demand constraint.
Parents : CoverViolations
Attributes
None
Elements
Violation contains a <Skill> or <SkillGroup> element (both optional) followed by a <TimePeriod>, <Shift>, <ShiftGroup> or <ShiftBlock> element followed by <Label>, <Count>, <Penalty> and <Cell>.
Name | Required | Type | Description |
<Skill> | Optional | string | The skill required in this constraint. |
<SkillGroup> | Optional | string | The skill(s) required in this constraint. (The skill group is specified using an ID defined in SkillGroup). |
<TimePeriod> | Optional | TimePeriod | The time period this cover requirement applies to if it was specified using a start time and end time. |
<Shift> | Optional | string | The shift type this cover requirement applies to if it was specified using shift types. The shift type is specified using an ID defined in ShiftTypes. |
<ShiftGroup> | Optional | string | The shift group this cover requirement applies to if it was specified using a shift group. The shift group is specified using an ID defined in ShiftGroups. |
<ShiftBlock> | Optional | string | The ShiftBlock this cover requirement applies to if it was specified using a ShiftBlock. The ShiftBlock is specified using an ID defined in ShiftBlocks. |
<Label> | Required | string | The label used for the constraint. If no label was
provided this tag will be empty. |
<Count> | Required | NonNegativeDouble | The level of cover provided in the solution for this shift or time period and skill(s). |
<Penalty> | Required | NonNegativeDouble | If the constraint is a soft constraint (that is, it has a weight) then Penalty contains the penalty caused by the violation. |
<Cell> | Required | NonNegativeInteger | The day on which the constraint is violated. |
Example
<Violation> <Skill>1</Skill> <Shift>L</Shift> <Label></Label> <Count>3</Count> <Penalty>1</Penalty> <Cell>6</Cell> </Violation>
Lists days in an employee's schedule.
Parents : Violation (Rules)
Attributes
Name | Required | Type | Description |
Employee | Required | string | An employee ID. |
Elements
Cells contains zero or more <Cell> elements
Name | Required | Type | Description |
<Cell> | Optional | NonNegativeInteger | A day in the roster. The days start at zero, that is, the first day is day zero. |
Example
<Cells Employee="A"> <Cell>0</Cell> <Cell>1</Cell> <Cell>2</Cell> </Cells>
Lists days in an employee's schedule.
Parents : Matches, Violation (Workload), Violation (Other), Violation (EmployeePairings)
Attributes
None
Elements
Cells contains zero or more <Cell> elements
Name | Required | Type | Description |
<Cell> | Optional | NonNegativeInteger | A day in the roster. The days start at zero, that is, the first day is day zero. |
Example
<Cells> <Cell>0</Cell> <Cell>1</Cell> </Cells>
A time period in the day.
Parents : Cover
Attributes
None
Elements
TimePeriod contains two child elements in any order:
Name | Required | Type | Description |
<Start> | Required | time | When the period begins. Specified in the format : hh:mm:ss. |
<End> | Required | time | When the period ends. Specified in the format : hh:mm:ss. |
Example
<TimePeriod> <Start>15:30:00</Start> <End>19:30:00</End> </TimePeriod>
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 is a whole number greater than or equal to zero (e.g. 0,1,2,..).