Skip to main content
The Employee Utilization constraint allows you to control how much work employees receive, either measured in FTE hours or in number of shifts. You can set minimum targets, ideal targets, and maximum limits for any combination of employees, shifts, and time periods.

Constraint schema

​
employeeUtilizationConstraint
object
Used to set targets and limits for the amount of hours or shifts worked by employees within given periods.

​
How targets work

The constraint supports three types of targets for both hours and shifts:
  • Minimum targets (minHours, minShifts): The solver will try to ensure employees work at least this amount. These are treated as soft targets and may not always be met if other constraints conflict.
  • Ideal targets (idealHours, idealShifts): The solver will try to assign exactly this amount. This is useful when you want employees to work a specific number of hours or shifts.
  • Maximum limits (maxHours, maxShifts): These are hard limits that will never be exceeded. The solver will strictly enforce these bounds.
You don’t need to specify all targets - only include the ones relevant to your use case. For example, you can set only maxHours to cap the total hours, or only idealShifts to target a specific number of shifts.

​
Global utilization targets

Set utilization targets for the entire planning horizon. This is useful for ensuring employees receive a fair distribution of work across the entire schedule.
The constraint below sets targets for employee-1 across the entire planning horizon:
  • The employee should work at least 80 hours (soft target)
  • The employee should ideally work exactly 120 hours
  • The employee may work no more than 160 hours (hard limit)
{
  "id": "euc-total-hours",
  "targets": {
    "minHours": 80,
    "idealHours": 120,
    "maxHours": 160
  },
  "filters": {
    "employees": {
      "ids": ["employee-1"]
    }
  }
}

​
Period-based utilization targets

All targets are applied to each period separately. By defining periods, you can create constraints that apply to specific time windows, such as weekly or monthly targets.
The constraint below sets a weekly target for all employees. Each employee should ideally work 40 hours per week, with a minimum of 32 hours and a maximum of 48 hours.
{
  "id": "euc-weekly-hours",
  "targets": {
    "minHours": 32,
    "idealHours": 40,
    "maxHours": 48
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}

​
Shift-based limits

You can limit the number of shifts of a specific type that employees can work. This is particularly useful for controlling undesirable shifts like night shifts or weekend work.
The constraint below sets a strict upper bound of 2 night shifts per week for all employees. After an employee has worked 2 night shifts in a week, they cannot be assigned any more night shifts that week.
{
  "id": "euc-night-shifts-per-week",
  "targets": {
    "maxShifts": 2
  },
  "filters": {
    "shifts": {
      "labels": ["night"]
    }
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}

​
Minimum shift requirements

You can also set minimum shift requirements to ensure employees receive a certain amount of work.
The constraint below ensures that each employee works at least 3 shifts per week, with an ideal target of 5 shifts. This helps prevent employees from being underutilized.
{
  "id": "euc-min-shifts-per-week",
  "targets": {
    "minShifts": 3,
    "idealShifts": 5
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}

​
Combining hours and shifts targets

You can combine both hours and shifts targets in a single constraint to create more nuanced requirements.
The constraint below ensures employees work between 3-5 shifts per week, with each shift ideally being around 8 hours. This creates a balanced schedule where employees get enough shifts but not too many.
{
  "id": "euc-balanced-weekly",
  "targets": {
    "minShifts": 3,
    "idealShifts": 4,
    "maxShifts": 5,
    "minHours": 24,
    "idealHours": 32,
    "maxHours": 40
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}

​
Setting limits on specific roles

You can set limits on the number of hours or shifts that employees can be assigned to specific roles.
The constraint below limits employees to a maximum of 50 hours per week worked with role role-1, while aiming for them to work at least 35 hours.
{
  "id": "euc-role-1-max-50-hours",
  "targets": {
    "minHours": 35,
    "idealHours": 40,
    "maxHours": 50
  },
  "filters": {
    "work": {
      "roleIds": ["role-1"]
    }
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}
The constraint below ensures that employees work at least 2 weekend shifts per month, helping to distribute weekend work fairly.
{
  "id": "euc-weekend-shifts",
  "targets": {
    "minShifts": 2,
    "idealShifts": 3
  },
  "filters": {
    "shifts": {
      "labels": ["weekend"]
    }
  },
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 30
    }
  }
}