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

Most settings represent a constraint the solver considers. Constraint settings have 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.

Some settings are scalar controls instead of priority weights. For example, weekendUnassignedMultiplier and weekendMandatoryCoverageFloorPercent tune weekend coverage pressure directly.

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: Medium second priority
• Use case: Prefer required coverage while still allowing unassigned shifts when legality or stronger constraints would otherwise be worse
• Note: Individual mandatory shifts can raise or lower their own unassigned cost with assignmentPriority; the setting still controls the priority layer.

weekendUnassignedMultiplier - Multiplies mandatory weekend unassigned penalties

• Default: 1
• Use case: Make weekend gaps more expensive than weekday gaps without changing the base assignShift weight

weekendMandatoryCoverageFloorPercent - Requires a minimum assigned percentage of mandatory weekend shifts

• Default: 0
• Use case: Apply an explicit weekend coverage floor. The target is rounded up; for example 60% of 7 weekend shifts requires 5 assigned shifts.

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 runs

• Default: maxConsecutiveWorkingDays is first-priority hard when omitted by the consumer model; minConsecutiveWorkingDays is third-priority soft.
• Use case: Enforce or prefer consecutive work-day limits for rest and efficiency. See Maximum consecutive working days for how maxConsecutiveDays and minWeeklyRestMinutes work together.

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

Maximum consecutive working days

maxConsecutiveWorkingDays limits how many working dates an employee can have in one continuous work run.

A work run ends only when the employee has a rest gap long enough to reset the run. The reset threshold comes from the employee contract:

The solver counts working dates by shift start date. Multiple shifts starting on the same local date count as one working date.

Enable or tune the constraint with the standard setting object:

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

When the setting is enabled, these examples show how the contract changes the result.

Six days followed by a full rest gap

Six days followed by only 24 hours of rest

Same schedule without minWeeklyRestMinutes

One-day maximum with 24 hours between shifts

Overnight shifts

Disabling the employee-level limit

Set both fields when a specific legal or contractual rest period should end a work run:

{
  "contract": {
    "maxConsecutiveDays": 6,
    "minWeeklyRestMinutes": 2100
  }
}

This means the employee can work at most six working dates before receiving at least 35 hours of rest.

Shift patterns

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

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

shiftTimeOfDayRotationPattern - Enforce a week-to-week time-of-day rotation based on contract patterns

• Default: Disabled
• Use case: Follow planned rotations like E-L-N or E-L

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

sameTimeOfDayWithinWeek - Keep the same time of day within each week

• Default: Disabled
• Use case: Keep non-historic shifts aligned within a week, while allowing weekly rotation

sameTimeOfDayForNonHistoricShifts - Keep the same time of day for non-historic shifts

• Default: Disabled
• Use case: Keep non-historic shifts aligned across the schedule for each employee

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

weeklyWorkTargetDeviation - Keep each employee close to their weekly required minutes

• Default: Disabled
• Use case: Spread a period work target across weeks when contract.weeklyRequiredMinutes is provided

weeklyWorkTargetUnderAssignment - Keep each employee from falling below the schedule-period required minutes

• Default: Disabled
• Use case: Prefer filling the sum of contract.weeklyRequiredMinutes across the request period. The setting name is legacy; this does not penalize an under-target employee-week when the employee reaches the period total.

mandatoryBeforeOptionalCoverage - Keep optional coverage unassigned while mandatory coverage in the same bucket is unassigned

• Default: Disabled
• Use case: Enforce mandatory-before-optional staffing within the solver. A bucket is the same local date and shift time-of-day; day/evening buckets are scoped by shared team, while night buckets are shared across teams.

freePeriodRequirementMissingUnitCount - Cover generic free-period unit requirements

• Default: Disabled
• Use case: Require duty-to-duty free intervals without pre-building the free period outside the solver

freePeriodRequirementMissingDateCoverage - Cover specific required free dates

• Default: Disabled
• Use case: Ensure required local dates are fully covered by qualifying duty-to-duty free intervals

freePeriodRequirementPreferredLocalDateShortfall - Prefer selected dates for generic free periods

• Default: Disabled
• Use case: Prefer satisfying generic free-period unit requirements on dates such as weekends while still allowing weekday fallback when coverage needs itminimizeEmployeeUsage - 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

workBothWeekendDays - Pair weekend assignments

• Default: Disabled
• Use case: Prefer assigning Saturday and Sunday to the same employee when that employee works the weekend
• Note: This setting only controls weekend pairing. It does not increase the cost of unassigned weekend shifts.

penalizeScheduleDisruptionOnReplanning - Minimize changes when re-planning

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

Common patterns

Make weekend coverage harder to leave open

Use this when Saturday and Sunday gaps are operationally worse than weekday gaps. Keep assignShift as the base cost, then add weekend-specific pressure:

{
  "settings": {
    "assignShift": {
      "firstPriorityWeight": 0,
      "secondPriorityWeight": 10,
      "thirdPriorityWeight": 0,
      "fourthPriorityWeight": 0
    },
    "weekendUnassignedMultiplier": 4,
    "weekendMandatoryCoverageFloorPercent": 80
  }
}

weekendUnassignedMultiplier changes the relative cost of leaving mandatory weekend shifts empty. weekendMandatoryCoverageFloorPercent adds a floor across mandatory weekend shifts in the request. workBothWeekendDays is separate; enable it only when you want paired Saturday/Sunday assignments.

• workEveryFifthWeekend
• maxNHoursInKWeeks
• minNHoursInKWeeks
• weeklyWorkTargetDeviation
• weeklyWorkTargetUnderAssignment
• mandatoryBeforeOptionalCoverage
• freePeriodRequirementMissingUnitCount
• freePeriodRequirementMissingDateCoverage
• freePeriodRequirementPreferredLocalDateShortfall
• minConsecutiveWorkingDays
• noConsecutiveFiveWorkdayWeeks
• assignShift
• assignOptionalShift
• correctSkill
• correctTeam
• sameTimeOfDayForConsecutiveShifts
• sameTimeOfDayWithinWeek
• sameTimeOfDayForNonHistoricShifts
• singleEmployeePerWeekSpotAssignment
• singleShiftPerDay
• undesiredEmployeeCoworkerPreference
• useDislikedEmployee
• useSuggestedEmployee
• minMinutesPerShift
• maxMinutesPerShift
• minWeeklyRestMinutes
• workBothWeekendDays
• weekendBundle
• workEveryNthWeekend
• minimizeEmployeeUsage
• penalizeScheduleDisruptionOnReplanning
• categoryShiftQuota
• loadBalanceCategoryShifts
• loadBalanceDaysOff
• 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 support@datapult.dk.