API Documentation

Settings let you control how the solver weighs different constraints when generating schedules. Want to prioritize employee preferences over even distribution? Adjust the weights. Need to enforce strict contract compliance? Increase those priorities.

How settings work

Each setting represents a constraint the solver considers. Every constraint has four priority levels, each with a weight from 0 to 20:

{
  "settings": {
    "desired": {
      "firstPriorityWeight": 20,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

Priority levels are evaluated in order:

  1. First priority (hardest constraint) - Violations here have the most impact
  2. Second priority - Important but less critical than first
  3. Third priority - Nice to have
  4. Fourth priority (softest constraint) - Least important

Weights (0-20) determine how much the solver cares within that priority level. Higher weights mean stronger enforcement.

Example interpretation

"unavailable": {
  "firstPriorityWeight": 20,
  "secondPriorityWeight": 0,
  "thirdPriorityWeight": 0,
  "fourthPriorityWeight": 0
}

This configuration makes employee unavailability a hard constraint with maximum weight. The solver will avoid violating this at almost any cost.

Key constraint categories

Employee preferences

desired - Honor employee requests to work during specific periods

  • Default: High first priority
  • Use case: Keep employees happy by respecting their preferred work times

unavailable - Respect employee unavailability (vacation, appointments)

  • Default: Maximum first priority (hard constraint)
  • Use case: Never schedule someone when they can't work

undesired - Avoid scheduling employees when they prefer not to work

  • Default: Medium second priority
  • Use case: Balance preferences with coverage needs

Shift assignment

assignShift - Fill mandatory shifts

  • Default: Maximum first priority
  • Use case: Ensure all required coverage is met

assignOptionalShift - Fill optional shifts when beneficial

  • Default: Lower priority
  • Use case: Add coverage when it doesn't hurt solution quality

correctSkill - Assign employees with required skills

  • Default: High first priority
  • Use case: Ensure qualified staff for specialized work

correctTeam - Assign employees from allowed teams

  • Default: High first priority
  • Use case: Respect organizational boundaries

Work-life balance

maxHoursDay / maxHoursWeek / maxHoursMonth - Enforce hour limits

  • Default: High first priority
  • Use case: Comply with labor laws and prevent burnout

maxConsecutiveWorkingDays / minConsecutiveWorkingDays - Control work streaks

  • Default: Medium priority
  • Use case: Balance consecutive work days for rest and efficiency

atLeastTwoContinousDaysOffAWeek - Ensure weekend-like breaks

  • Default: Medium priority
  • Use case: Provide meaningful rest periods

hoursBetweenShift - Enforce minimum rest between shifts

  • Default: High first priority
  • Use case: Prevent fatigue from back-to-back shifts

Shift patterns

alternatingShiftTypes - Vary shift types (morning/evening/night)

  • Default: Medium priority
  • Use case: Avoid monotonous schedules

maxConsecutiveLateShifts / maxConsecutiveNightShifts - Limit challenging patterns

  • Default: Medium priority
  • Use case: Prevent excessive late or night work

sameTimeOfDayForConsecutiveShifts - Group similar shift times together

  • Default: Lower priority
  • Use case: Build routine and reduce adjustment stress

singleShiftPerDay - Limit employees to one shift per day

  • Default: High priority
  • Use case: Prevent split shifts unless necessary

Fairness

distributeShiftsEvenly - Balance workload across employees

  • Default: Medium third/fourth priority
  • Use case: Ensure fair distribution of work

minimizeEmployeeUsage - Use fewer employees when possible

  • Default: Lower priority
  • Use case: Reduce scheduling complexity or costs

Employee suggestions

useSuggestedEmployee - Prefer suggested employees for shifts

  • Default: Medium priority
  • Use case: Leverage manager insights about good fits

useDislikedEmployee - Avoid disliked employees for shifts

  • Default: Medium priority
  • Use case: Respect manager preferences about poor fits

Special rules

dayOffAfterShiftInRoomWithRequiredRest - Enforce rest after demanding spots

  • Default: High priority
  • Use case: Ensure recovery after high-stress shifts

singleEmployeePerWeekSpotAssignment - Maintain continuity at spots

  • Default: Medium priority
  • Use case: Reduce handoffs and build context

workEveryNthWeekend - Distribute weekend work fairly

  • Default: Medium priority
  • Use case: Honor weekend work frequency from contracts

penalizeScheduleDisruptionOnReplanning - Minimize changes when re-planning

  • Default: High priority when re-planning
  • Use case: Provide schedule stability

Complete settings reference

If you omit settings, the solver uses sensible defaults. To customize, include only the settings you want to change:

{
  "settings": {
    "unavailable": {
      "firstPriorityWeight": 20,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    },
    "desired": {
      "firstPriorityWeight": 15,
      "secondPriorityWeight": 0,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    }
  }
}

All available settings

  • alternatingShiftTypes
  • atLeastTwoContinousDaysOffAWeek
  • dayOffAfterShiftInRoomWithRequiredRest
  • restAfterShiftInRoomWithRequiredMinutes
  • dayOffInAWeekAfterWeekendShift
  • maxHoursDay
  • maxHoursMonth
  • maxHoursWeek
  • employeeHourlyPatternCompactness
  • continousWorkDays
  • employeeShiftConflict
  • desired
  • hoursBetweenShift
  • unavailable
  • undesired
  • lateFridayNeverWithEarlyMonday
  • lateShiftWithDayOffNextDayNeverWithEarlyShift
  • distributeShiftsEvenly
  • maxConsecutiveLateShifts
  • maxConsecutiveNightShifts
  • maxConsecutiveWorkingDays
  • workEveryFifthWeekend
  • maxNHoursInKWeeks
  • minNHoursInKWeeks
  • minConsecutiveWorkingDays
  • noConsecutiveFiveWorkdayWeeks
  • assignShift
  • assignOptionalShift
  • correctSkill
  • correctTeam
  • sameTimeOfDayForConsecutiveShifts
  • singleEmployeePerWeekSpotAssignment
  • singleShiftPerDay
  • undesiredEmployeeCoworkerPreference
  • useDislikedEmployee
  • useSuggestedEmployee
  • minMinutesPerShift
  • maxMinutesPerShift
  • minWeeklyRestMinutes
  • workBothWeekendDays
  • weekendBundle
  • workEveryNthWeekend
  • minimizeEmployeeUsage
  • penalizeScheduleDisruptionOnReplanning
  • categoryShiftQuota
  • loadBalanceCategoryShifts
  • shiftDependencyRules
  • competencyRequired
  • minSeniorityLevel

Tuning tips

  1. Start with defaults - Only override what you need
  2. Test incrementally - Change one setting at a time to see effects
  3. Balance priorities - Don't make everything first priority
  4. Consider your domain - Healthcare needs differ from retail
  5. Monitor violations - The solver reports constraint violations in responses

Need help tuning settings for your use case? Contact [email protected].