Employee Shift Scheduling User Guide

Create problem dataset using predefined model schema that follows OpenAPI specification. The application provides several out-of-the-box examples that can be used as a starting point.

Submit the unsolved dataset using the REST API. The application validates the input and returns a unique identifier of the problem. The solving process is scheduled and eventually starts.

Check the current best solution and receive information about the solving process. The solution contains optimized employee shift schedule. Use id attribute returned by submit dataset step.

Terminate the solving process and receive the current best solution. Use id attribute returned by submit dataset step.

Get info about the status of all solving processes.

The run configuration is shared across all models. Below is an example of a run configuration.

A run configuration has two fields: the run and the model.

The run has four fields:

The model is a model-specific field, that contains additional global model configuration attributes.

Employee contract can define multiple rules that are assessed over either a built-in or a custom period.

The period rule can optionally define a ruleValidityDateTimeSpan to limit the rule to a specific time span. The validity date time span uses the employee’s zone offset to determine the start and end time of the rule. To learn more about time zones and daylight saving time, see Timezones and Daylight Saving Time (DST).

The following example shows a rule that requires an employee to work no more than 6 hours a day, but only during December 2024:

Provides an optional configuration of the model, for example specifying the weight of constraints.

Employee that can be assigned to a shift.

Employee contract that defines settings specific to a group of employees (e.g. maximum number of minutes worked per month).

Unit of work that has to be covered by an employee. Each shift has a start and end time and can have various requirements (e.g. skills required).

Configuration of global rules that apply to all employees and shifts (e.g. fairness configuration).

The planning window is the time interval to schedule for. Typically, it is derived automatically and does not need to be supplied by user, except the case when there is a multi-day pattern rule starting or ending with one or more OFF elements.

Example planning window definition from Monday 2024-02-05 00:00 to Sunday 2024-02-11 23:59:59:

Please note that the start time is treated as inclusive, while the end as exclusive.

If omitted, the planning window interval is derived as follows:

Example: the earliest shift start = 2024-10-10T08:00+01:00 → window start = 2024-10-10T00:00+01:00.

Example: the latest shift start = 2024-10-10T08:00+01:00 → window end = 2024-10-11T00:00+01:00.

Tags provide additional data to domain objects, such as employees and shifts. An example of a tag could be country 'Belgium', department 'A', or employment type 'Contractor'.

Tags can be used to filter out specific employees or shifts in rules. Imagine a case where we want to apply Balance time worked constraints, but exclude external contractors and one-off shifts from the consideration. We follow a convention of using includeEmployeeTags, or excludeEmployeeTags to filter out employees, and using includeShiftTags, or excludeShiftTags to filter out shifts in the rules. These basic filters don’t require the user to enumerate all the tags and their categories explicitly in the input payload as a part of top-level tags and tagTypes collection.

Tags can be grouped into tag types. An example of a tag type could be 'Country', 'Department', or 'Employment type'. Some rules, such as Employee works shift with matching preferred shift tags, or configuration objects as Travel configuration require additional tag information, meaning the user needs to enumerate all referenced tags and their categories explicitly in the input payload as a part of top-level tags and tagTypes collection.

Employee possesses several skills. Shift can define one or more required skills. The constraint triggers if the employee does not have all the skills required by the shift. The skills need to be valid for the whole duration of the shift. Use the skill’s validityDateTimeSpans attribute to define the validity of a skill.

Score analysis justification example:

The constraint triggers if multiple shifts assigned to the same employee overlap. Employee contract can define several allow overlapping shift rules.

If defined, only shifts containing tags defined by the allow overlapping shift rule’s includeShiftTags attribute can overlap with other shifts. With shiftTagMatches set to ALL, all tags defined by the overlapping shift rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the overlapping shift rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the allow overlapping shift rule’s excludeShiftTags attribute can overlap with other shifts. With shiftTagMatches set to ALL, all tags defined by the overlapping shift rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the overlapping shift rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of minutes worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of minutes worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of locations worked. With shiftTagMatches set to ALL, all tags defined by the period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule excludeShiftTags attribute are included in the total number of locations worked. With shiftTagMatches set to ALL, all tags defined by the period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s locationsWorkedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

Score analysis justification example:

Employee contract can define several consecutive days worked rules`. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the rule’s includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by consecutive days worked rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by consecutive days worked rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the rule’s excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by consecutive days worked rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by consecutive days worked rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

If defined, shifts containing a tag defined by the rule’s shiftTypeTagCategories form a sequence based on the value of the tag, for example a sequence of consecutive "morning" shifts. The shift must always have at most one tag defined by the rule’s shiftTypeTagCategories attribute.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered. In case there are no shifts that satisfy the rule’s filters, not attaining the minimum does cause the constraint violation.

Score analysis justification example:

Global rules configuration can define one or more minimum or maximum number of shifts worked per period. This is useful to express a global requirement to fulfill a certain number of shifts in a period, optionally only for shifts, or employees with specific tags. The constraint triggers if all conditions below apply:

If defined, only employees containing tags defined by rule’s includeEmployeeTags attribute are included in the total number of shifts worked. With employeeTagMatches set to ALL, all tags defined by the rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the rule’s excludeEmployeeTags attribute are included in the total number of shifts worked. With employeeTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Configuration example for a requirement to staff at most 3 administrative shifts per day, including only full time employees.

Score analysis justification example:

Global rules configuration can define one or more costs rules. The constraint makes sure the total costs of shift assignments, that match tags specified, are in the required range.

The employee defines a cost group. The shift defines a cost group. The costs rule requires a list of employee shift cost details that expresses the cost of assigning the employee to the shift.

The constraint triggers if all conditions below apply:

Note you need to define the cost detail for each employee cost group and shift cost group combination that should be included in the total costs. Undefined employee cost group and shift cost group combinations are not included in the total costs.

If defined, only employees containing tags defined by the rule’s includeEmployeeTags attribute are included in the total costs. With employeeTagMatches set to ALL, all tags defined by the rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the rule’s excludeEmployeeTags attribute are included in the total costs. With employeeTagMatches set to ALL, all tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the rule’s includeShiftTags attribute are included in the total costs. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the rule’s excludeShiftTags attribute are included in the total costs. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Employee can define several required employee pairings. The pairings express employees that have to work together at the same time. The constraint triggers for each shift assigned to the employee that does not overlap with a shift assigned to the required employee.

Score analysis justification example:

Employee can define several prohibited employee pairings. The pairings express employees that cannot work together at the same time. The constraint triggers for each shift assigned to the employee that overlaps with a shift assigned to the prohibited employee.

Score analysis justification example:

Employee can define several prohibited risk factors. Shift can define one or more risk factors. The constraint triggers if the employee is assigned to a shift that contains one or more risk factors defined by the employee.

Score analysis justification example:

Shift can define one or more prohibited employees. The constraint triggers if the shift is assigned to one of the employees listed in the shift’s prohibited employees collection.

Score analysis justification example:

Employee can define several unavailable time spans. The span defines a period when the employee cannot work (e.g. time off). The constraint triggers if the employee is assigned to a shift that matches optional shift tag criteria and overlaps with one or more unavailable time spans defined by the employee.

If defined, only shifts containing tags defined by unavailable time for employee includeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unavailable time for employee includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the unavailable time for employee includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by preferred time for employee excludeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unavailable time for employee excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the unavailable time for employee excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Employee can define several available time spans. If defined, the spans defines the only periods when the employee is available. Otherwise, the employee is available to be scheduled for the entire schedule (except when prohibited by unavailable time spans). The constraint triggers if the employee is assigned to a shift that is not contained by one or more available time spans defined by the employee that matches the optional shift tag criteria.

If defined, only shifts containing tags defined by available time for employee includeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unavailable time for employee includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the unavailable time for employee includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by preferred time for employee excludeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unavailable time for employee excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the unavailable time for employee excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Score analysis justification example:

Global rules configuration can define one or more shift tag match rules. The constraint makes sure the employees are assigned to the shifts based on their shift type requirement.

Imagine an organization that contains multiple departments. Each department contains multiple teams. We want to create a schedule for shifts that belong to specific departments and teams. For example a shift in Department A. Employees also belong to specific departments and can only work shifts within their department. For example an employee has to work in Department A, not in Department Y

We define a tag hierarchy as described in section Tags and tag types:

We define shifts that reference some of the tags:

We define employees that express requirement to work shifts with some of the tags. This is done via the requiredShiftTags attribute:

We define a rule that validates that employees assigned to shifts that match their required tags. The rule states that whenever a shift is assigned to an employee and the required tag does not match the shift tags, we penalize such assignments.

For example, EmployeeDepartmentA has a required shift tag Department A. If they are assigned to the shift ShiftDepartmentA which has the tag Department A (tag type Department), we don’t penalize such assignments. If they are assigned to the shift ShiftDepartmentB which has the tag Department B (tag type Department), we penalize such assignments.

The constraint triggers if all the conditions below apply:

Score analysis justification example:

Employee contract can define several avoid shift close to day off request rules. The rules define types of shifts that should be avoided before / after a day off. The constraint triggers if all conditions below apply:

Score analysis justification example:

Employee contract can define several minutes between shifts rules. The constraint triggers if all the conditions below apply:

If the value of minimumConsecutivePriorShifts attribute is set to 1:

If the value of minimumConsecutivePriorShifts attribute is set to 2:

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredPriorShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minutes between shifts rule’s requiredPriorShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minutes between shifts rule’s requiredPriorShiftTags attribute has to be present in the shift.

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredAfterShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minutes between shifts rule’s requiredAfterShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minutes between shifts rule’s requiredAfterShiftTags attribute has to be present in the shift.

Score analysis justification example:

Employee contract can define several daily shift pairings. The constraint triggers if all the conditions below apply:

With shiftTagMatches set to ALL, all tags defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute have to be present in the shift to match. With shiftTagMatches set to ANY, at least one tag defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute has to be present in the shift.

Score analysis justification example:

Employee contract can define several daily shift pairings. The constraint triggers if all the conditions below apply:

With shiftTagMatches set to ALL, all tags defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute have to be present in the shift to match. With shiftTagMatches set to ANY, at least one tag defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute has to be present in the shift.

Score analysis justification example:

Employee contract can define several single day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the single day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

Use the constraint configuration’s employeeDoesNotWorkSingleDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several single day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the single day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

Use the constraint configuration’s employeeWorksProhibitedSingleDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several multi day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the multi day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

In case there are multiple shifts on the same day, use the pattern element’s shiftMatches attribute to define the matching behavior. With shiftMatches set to ALL, all shifts need to match the tag criteria of the pattern element on that particular day. With shiftMatches set to ANY, any shift needs to match the tag criteria of the pattern element on that particular day. The default value of shiftMatches attribute is ALL.

Use the constraint configuration’s employeeDoesNotWorkRequiredMultiDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several multi day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the multi day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

In case there are multiple shifts on the same day, use the pattern element’s shiftMatches attribute to define the matching behavior. With shiftMatches set to ALL, all shifts need to match the tag criteria of the pattern element on that particular day. With shiftMatches set to ANY, any shift needs to match the tag criteria of the pattern element on that particular day. The default value of shiftMatches attribute is ALL.

Use the constraint configuration’s employeeWorksProhibitedMultiDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Schedule parametrization can define travel configuration. The constraint makes sure the maximum travel distance between the employee location and shift location does not exceed the maxEmployeeToShiftTravelDistanceInMeters limit defined in the travel configuration. The configuration allows you to exclude some of the shifts from the maximum travel distance limit, based on the employee’s requiredShiftTags and preferredShiftTags attributes. For example, we want to enforce a limit of 100 km between an employee and a shift, but we want to exclude shifts that belong to the same team as the employee.

The constraint triggers if all the following conditions apply:

If defined, only shifts containing tags defined by the travel configuration’s includeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the travel configuration’s excludeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

Configuration example to set the maximum employee travel distance to 40km for all shifts.

Configuration example to set the maximum employee travel distance to 40km for ICU shifts.

Configuration example to set the maximum employee travel distance to 40km for ICU shifts, or Cardiology shifts.

Score analysis justification example:

Schedule parametrization can define travel configuration. The constraint makes sure the minimum number of minutes between shifts that have different locations and are assigned to the same employee follows the minMinutesBetweenShiftsInDifferentLocations limit defined in the travel configuration.

The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the travel configuration’s includeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the travel configuration’s excludeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

Configuration example to set the minimum number of minutes between any employee’s shifts in different locations to 240 minutes.

Configuration example to set the minimum number of minutes between employee’s ICU shifts in different locations to 240 minutes.

Configuration example to set the minimum number of minutes between employee’s ICU shifts, or Cardiology shifts in different locations to 240 minutes.

Score analysis justification example:

The constraint penalizes mandatory shifts (see Mandatory and optional shifts) that are not assigned to any employee. The size of the penalty depends on the shift’s priority and its weight. High priority shifts are more likely to be assigned, compared to low priority shifts.

The model defines 10 built-in priorities, where 1 is the highest priority and 10 is the lowest priority. The default built-in priority is 10. These built-in priorities use exponential penalty weights, where priority 1 is 10 times more important than priority 2, priority 2 is 10 times more important than priority 3 and so on. Optionally, you can override these weights, or define custom priorities in the unassigned shift rule. In case the custom priorities are used, there is no default value for the priority attribute, and you need to provide a value.

Consider a case with two morning shifts:

Whenever the solver is unable to assign both shifts, since that would lead to a hard score violation, it might decide to keep one of the shifts unassigned. In the example above, it potentially leaves 'Morning-trainee-nurse' shift unassigned, since it has a lower assignment priority.

Score analysis justification example:

If 10 built-in priorities are not enough, you can define custom priority levels. These custom priorities are defined in the priorityWeights attribute of the unassigned shift rule. The weights of the priorities need to be defined in descending order, where the first element of the array has the highest weight. All priorities referenced in the dataset need to be defined in the priorityWeights attribute and their weight need to be configured.

Global rules configuration can define one or more minimum maximum shifts per hourly demand rules. The constraint makes sure the total number of shift assignments in hourly intervals, that match tags specified, are in the required range, optionally only for shifts with specific tags.

The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use the constraint configuration’s shiftsWorkedNotInRequiredHourlyDemandRangeWeight attribute to update the weight of the constraint.

Score analysis justification example:

The constraint penalizes optional shifts (see Mandatory and optional shifts) that are not assigned to any employee. The size of the penalty depends on the shift’s priority and its weight. High priority shifts are more likely to be assigned, compared to low priority shifts.

The penalty is calculated the same as for Unassigned mandatory shift, just on the soft level. See Unassigned mandatory shift constraint description for more details.

Use the constraint configuration’s unassignedOptionalShiftWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more disruption rules. The constraint makes sure the disruptions caused by resolving an existing problem are minimized. This includes changes of the employee assigned to a shift, compared to the original schedule. Consider a case where you need to re-plan an already published schedule due to an unexpected employee absence. You want to minimize the impact of the re-planning on the schedule and the employees who might have already made plans based on the original schedule. Disruptions that are close to the time of the re-planning possibly have more impact than disruptions that are further away.

The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the rule’s includeShiftTags attribute are included in the disruption check. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the rule’s excludeShiftTags attribute are included in the disruption checks. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeAssignmentDisruptedOnReplanningWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee possesses several skills. Shift can define one or more preferred skills. The constraint triggers if the employee does not have all the skills defined by the shift. The skills need to be valid for the whole duration of the shift. Use the skill’s validityDateTimeSpans attribute to define the validity of a skill.

Use the constraint configuration’s preferredSkillMissingWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of minutes worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of minutes worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s minutesAssignedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s shiftsAssignedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule includeShiftTags attribute are included in the total number of locations worked. With shiftTagMatches set to ALL, all tags defined by the period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule excludeShiftTags attribute are included in the total number of locations worked. With shiftTagMatches set to ALL, all tags defined by the period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s locationsWorkedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s daysWorkedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several period rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s shiftTypesWorkedPerPeriodNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several consecutive days worked rules. The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by period rule includeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by consecutive days worked rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by consecutive days worked rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by period rule excludeShiftTags attribute are included in the total number of days worked. With shiftTagMatches set to ALL, all tags defined by consecutive days worked rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by consecutive days worked rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The day is considered worked if the employee is assigned to at least one shift that starts on that day. Shifts that start on the previous day and end on the current day are not considered.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s consecutiveDaysWorkedNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more minimum maximum shifts per hourly demand rules. The constraint makes sure the total number of shift assignments in hourly intervals, that match tags specified, are in the required range, optionally only for shifts with specific tags.

The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use the constraint configuration’s shiftsWorkedNotInPreferredHourlyDemandRangeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more minimum maximum shifts per hourly demand rules. The constraint makes sure the total number of shift assignments, that match tags specified, are distributed evenly across the hourly intervals. The constraint takes the minimum demand into account, optionally only for shifts with specific tags. For example, if the minimum demand throughout the whole day is 5 shifts and the shift supply is higher than the demand, the constraint makes sure that the extra shifts are distributed evenly across the day, as opposed to assigning them all in the first hour of the day.

The constraint triggers if all conditions below apply:

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by period rule includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by period rule excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by period rule excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use the constraint configuration’s balanceShiftsWorkedForMinimumHourlyDemandWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more minimum or maximum number of shifts worked per period. This is useful to express a global preference to fulfill a certain number of shifts in a period, optionally only for shifts, or employees with specific tags. The constraint triggers if all conditions below apply:

If defined, only employees containing tags defined by rule’s includeEmployeeTags attribute are included in the total number of shifts worked. With employeeTagMatches set to ALL, all tags defined by the rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the rule’s excludeEmployeeTags attribute are included in the total number of shifts worked. With employeeTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the period rule’s includeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the period rule’s excludeShiftTags attribute are included in the total number of shifts worked. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Configuration example for a preference to staff at most 3 administrative shifts per day, including only full time employees.

Score analysis justification example:

Global rules configuration can define one or more costs rules. The constraint makes sure the total costs of shift assignments, that match tags specified, are in the required range.

The employee defines a cost group. The shift defines a cost group. The costs rule requires a list of employee shift cost details that expresses the cost of assigning the employee to the shift.

The constraint triggers if all conditions below apply:

Note you need to define the cost detail for each employee cost group and shift cost group combination that should be included in the total costs. Undefined employee cost group and shift cost group combinations are not included in the total costs.

If defined, only employees containing tags defined by the rule’s includeEmployeeTags attribute are included in the total costs. With employeeTagMatches set to ALL, all tags defined by the rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the rule’s excludeEmployeeTags attribute are included in the total costs. With employeeTagMatches set to ALL, all tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the rule’s includeShiftTags attribute are included in the total costs. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the rule’s excludeShiftTags attribute are included in the total costs. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use the constraint configuration’s costsPerPeriodNotInPreferredRangeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee can define several preferred employee pairings. The pairings express employees that prefer working together at the same time. The constraint triggers for each shift assigned to the employee that overlaps with a shift assigned to the preferred employee.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeIsPairedWithPreferredEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee can define several unpreferred employee pairings. The pairings express employees that prefer not to work together at the same time. The constraint triggers for each shift assigned to the employee that overlaps with a shift assigned to the unpreferred employee.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeIsPairedWithUnpreferredEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several preferred time spans. The span defines a period when the employee prefers to work. The constraint triggers if the employee is assigned to a shift that matches optional shift tag criteria and overlaps with one or more preferred time spans defined by the employee.

If defined, only shifts containing tags defined by preferred time for employee includeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the preferred time for employee includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the preferred time for employee includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by preferred time for employee excludeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the preferred time for employee excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the preferred time for employee excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksDuringPreferredTimeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several unpreferred time spans. The span defines a period when the employee prefers not to work. The constraint triggers if the employee is assigned to a shift that matches optional shift tag criteria and overlaps with one or more unpreferred time spans defined by the employee.

If defined, only shifts containing tags defined by unpreferred time for employee includeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unpreferred time for employee includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the unpreferred time for employee includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by unpreferred time for employee excludeShiftTags attribute are included. With shiftTagMatches set to ALL, all tags defined by the unpreferred time for employee excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the unpreferred time for employee excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksDuringUnpreferredTimeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more shift tag match rules. The constraint makes sure the employees are assigned to the shifts based on their shift type preference.

Imagine an organization that contains multiple departments. Each department contains multiple teams. We want to create a schedule for shifts that belong to specific departments and teams. For example a shift in Department A and team Team X. Employees also belong to specific departments and teams. Moreover, the employees can work a shift in a different department, or team, if needed. For example an employee preferrably works in Department A and team Team X, but can also take shifts in Department Y. The former assignment should be preferred if possible.

We define a tag hierarchy as described in section Tags and tag types:

We define shifts that reference some of the tags:

We define employees that express preference to work shifts with some of the tags. This is done with the preferredShiftTags attribute:

We define a rule that expresses how likely employees are to be assigned shifts that match their preferred tags. The rule states that whenever a shift is assigned to an employee and the preferred tag matches shift tags, we reward such assignment with a multiplier, depending on the shift type of the tag.

For example, EmployeeTeamX has preferred shift tags Team X and Department A. If they are assigned to the shift ShiftTeamX which has the tags Team X (tag type Team) and Department A (tag type Department), we reward with multipliers 1,000,000 and 1,000 respectively. If they are assigned to the shift ShiftTeamY which has the tags Team Y (tag type Team) and Department A (tag type Department), we reward with multipliers 1,000, since only the department matches. If they are assigned to the shift ShiftDepartmentB which has the tags Department B (tag type Department), we don’t reward, since none of the tags match.

The constraint triggers if all the conditions below apply:

Use the constraint configuration’s employeeWorksShiftWithPreferredShiftTagsWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several avoid shift close to day off request rules. The rules define types of shifts that should be avoided before / after a day off. The constraint triggers if all conditions below apply:

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeHasUnpreferredShiftNearDayOffRequestWeight attribute to update the weight of the constraint.

Score analysis justification example:

Shift can define one or more preferred employees. The constraint triggers if the shift is assigned to one of the employees listed in the shift’s preferred employees collection.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s preferredEmployeeAssignedWeight attribute to update the weight of the constraint.

Score analysis justification example:

Shift can define one or more unpreferred employees. The constraint triggers if the shift is assigned to one of the employees listed in the shift’s unpreferred employees collection.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s unpreferredEmployeeAssignedWeight attribute to update the weight of the constraint.

Score analysis justification example:

Global rules configuration can define one or more balance time worked rules. The constraint makes sure the total number of minutes worked across shifts, that match the specified tags, is balanced across employees that match the specified tags. This avoids situations where some employees work more time than others.

Please see Load balancing and fairness for further information about the fairness concept.

If defined, only employees containing tags defined by the balance time worked rule’s includeEmployeeTags attribute are balanced. With employeeTagMatches set to ALL, all tags defined by the balance time worked rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the balance time worked rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the balance time worked rule’s excludeEmployeeTags attribute are balanced. With employeeTagMatches set to ALL, all tags defined by the balance time worked rule’s excludeShiftTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the the balance time worked rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the balance time worked rule’s includeShiftTags attribute are balanced. With shiftTagMatches set to ALL, all tags defined by the balance time worked rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the balance time worked rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the balance time worked rule’s excludeShiftTags attribute are balanced. With shiftTagMatches set to ALL, all tags defined by the balance time worked rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the balance time worked rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use employeeToPublishedMinutesWorked attribute to specify the number of minutes worked by each employee in the past.

Use the constraint configuration’s balanceTimeWorkedWeight attribute to update the weight of the constraint.

Global rules configuration can define one or more balance shift count rules. The constraint makes sure the total number of shifts worked, that match the specified tags, is balanced across employees that match the specified tags. This avoids situations where some employees work more shifts than others.

Please see Load balancing and fairness for further information about the fairness concept.

If defined, only employees containing tags defined by the balance shift count rule’s includeEmployeeTags attribute are balanced. With employeeTagMatches set to ALL, all tags defined by the balance shift count rule’s includeEmployeeTags attribute have to be present in the employee. With employeeTagMatches set to ANY, at least one tag defined by the balance shift count rule’s includeEmployeeTags attribute has to be present in the employee.

If defined, only employees not containing tags defined by the balance shift count rule’s excludeEmployeeTags attribute are balanced. With employeeTagMatches set to ALL, all tags defined by the balance shift count rule’s excludeShiftTags attribute cannot be present in the employee. With employeeTagMatches set to ANY, any of the tags defined by the balance shift count rule’s excludeEmployeeTags attribute cannot be present in the employee.

The rule can define either includeEmployeeTags or excludeEmployeeTags, not both.

If defined, only shifts containing tags defined by the balance shift count rule’s includeShiftTags attribute are balanced. With shiftTagMatches set to ALL, all tags defined by the balance shift count rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the balance shift count rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the balance shift count rule’s excludeShiftTags attribute are balanced. With shiftTagMatches set to ALL, all tags defined by the balance shift count rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the balance shift count rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both.

Use employeeToPublishedShiftCount attribute to specify the number of shifts worked by each employee in the past.

Use the constraint configuration’s balanceShiftCountWeight attribute to update the weight of the constraint.

Employee contract can define several minutes between shifts rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredPriorShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minutes between shifts rule’s requiredPriorShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minutes between shifts rule’s requiredPriorShiftTags attribute has to be present in the shift.

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredAfterShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minutes between shifts rule’s requiredAfterShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minutes between shifts rule’s requiredAfterShiftTags attribute has to be present in the shift.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s minutesBetweenShiftsNotInPreferredRangeForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several minimize gaps between shifts rules. The constraint makes sure that shifts close to each other are preferred for an employee, in case the employee is eligible to work multiple shifts per day.

Imagine a case, where we have 3 shifts on a day:

In case we assigned an employee to the Morning shift and the Late shift, it leaves them with a 5-hour gap between the shifts, which is undesirable. A preferred solution would be to assign them to the Morning shift and the Afternoon shift, or the Afternoon shift and the Late shift, since those pairs of shifts only have 1-hour gap between them. This constraint prefers closer assignments. The shorter the break between the shifts, the better.

To avoid situations, where we reward pairs of shifts that are separated by multiple days, the constraint requires a definition of a time scope. Only shifts that are close enough to each other are considered. Use the rule’s maximumMinutesBetweenSplitShifts to define the length of the scope. The default value of maximumMinutesBetweenSplitShifts is 120 minutes. Looking at the example above, if the maximumMinutesBetweenSplitShifts is configured to 120 minutes, the Morning shift and the Afternoon shifts match, since they are only separated by 1 hour. The same applies to the Afternoon shift and the Late shift. The combination of the Morning shift and Late shift does not match though, since they are separated by 5 hours, which is above the limit of 2 hours.

The constraint triggers if all the following conditions apply:

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredPriorShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minimize gaps between shifts rule’s requiredPriorShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minimize gaps between shifts rule’s requiredPriorShiftTags attribute has to be present in the shift.

If defined, only shifts containing tags defined by minutes between shifts rule’s requiredAfterShiftTags attribute can be the first shift. With shiftTagMatches set to ALL, all tags defined by the minimize gaps between shifts rule’s requiredAfterShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the minimize gaps between shifts rule’s requiredAfterShiftTags attribute has to be present in the shift.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s minimizeGapsBetweenShiftsForEmployeeWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several daily shift pairings. The constraint triggers if all the conditions below apply:

With shiftTagMatches set to ALL, all tags defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute have to be present in the shift to match. With shiftTagMatches set to ANY, at least one tag defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute has to be present in the shift.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeDoesNotHavePreferredDailyShiftPairingWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several daily shift pairings. The constraint triggers if all the conditions below apply:

With shiftTagMatches set to ALL, all tags defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute have to be present in the shift to match. With shiftTagMatches set to ANY, at least one tag defined by the daily shift pairing rule’s shiftTags/pairedShiftTags attribute has to be present in the shift.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeHasUnpreferredDailyShiftPairingWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several single day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the single day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksPreferredSingleDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several single day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the single day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the single day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksUnpreferredSingleDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several multi day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the multi day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

In case there are multiple shifts on the same day, use the pattern element’s shiftMatches attribute to define the matching behavior. With shiftMatches set to ALL, all shifts need to match the tag criteria of the pattern element on that particular day. With shiftMatches set to ANY, any shift needs to match the tag criteria of the pattern element on that particular day. The default value of shiftMatches attribute is ALL.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksPreferredMultiDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Employee contract can define several multi day shift sequence pattern rules. The constraint triggers if all the conditions below apply:

If defined, only shifts containing tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the multi day shift sequence pattern rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute are included in the sequence. With shiftTagMatches set to ALL, all tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the multi day shift sequence pattern rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, not both. The default value of shiftTagMatches attribute is ALL.

In case there are multiple shifts on the same day, use the pattern element’s shiftMatches attribute to define the matching behavior. With shiftMatches set to ALL, all shifts need to match the tag criteria of the pattern element on that particular day. With shiftMatches set to ANY, any shift needs to match the tag criteria of the pattern element on that particular day. The default value of shiftMatches attribute is ALL.

The rule is more likely to be satisfied for employees with higher employee priority.

Use the constraint configuration’s employeeWorksUnpreferredMultiDayShiftSequencePatternWeight attribute to update the weight of the constraint.

Score analysis justification example:

Schedule parametrization can define travel configuration. The constraint makes sure the distance traveled between employee’s location and shift’s location is minimized.

The constraint triggers if all of the following conditions apply:

If defined, only shifts containing tags defined by the travel configuration’s includeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute have to be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute has to be present in the shift.

If defined, only shifts not containing tags defined by the travel configuration’s excludeShiftTags attribute are included in the maximum travel distance check. With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

Use the constraint configuration’s minimizeTravelDistanceWeight attribute to update the weight of the constraint.

Configuration example to minimize the distance travelled for all shifts.

Configuration example to minimize the distance travelled for all ICU shifts:

Configuration example to minimize the distance travelled for all ICU shifts, or Cardiology shifts.

Score analysis justification example:

Description of Recommend Employee API input.

Description of Recommend Employee API output.