Employee activation
When scheduling employees, particularly when dealing with external contractors, temporary staff, or managing labor costs, it’s important to optimize which employees are activated and how many shifts they work. For instance, to make sure full-time employees are assigned to shifts before adding contractors.
Employee activation constraints help you:
-
Minimize the number of employees needed to staff a schedule.
-
Reduce costs when using contractors with fixed activation fees.
-
Maintain optimal ratios between different employee groups.
-
Maximize the utilization of activated employees.
This guide explains how to manage employee activation with the following constraints:
1. Minimize activated employees
Learn how to configure an API Key to run the examples in this guide:
In the examples, replace |
Employee cost groups can define an activation cost that represents the fixed cost incurred when an employee is assigned to at least one shift.
This is useful for:
-
Estimating the minimum number of employees needed to staff a schedule.
-
Minimizing costs when using external contractors or temporary staff who have fixed activation fees.
-
Reducing overhead costs associated with activating employees.
1.1. Configuration
Define employee cost groups with activation costs on the top level of the input dataset:
{
"employeeCostGroups": [
{
"id": "external-contractors",
"employeeActivationCost": 200,
"activationShiftInclude": "MANDATORY_SHIFTS"
},
{
"id": "regular-employees",
"employeeActivationCost": 100,
"activationShiftInclude": "MANDATORY_AND_OPTIONAL_SHIFTS"
}
]
}Assign employees to cost groups:
{
"employees": [
{
"id": "Ann",
"costGroup": "external-contractors"
},
{
"id": "Beth",
"costGroup": "regular-employees"
}
]
}1.2. Activation shift include
The activationShiftInclude field determines which shift types count toward employee activation:
-
MANDATORY_SHIFTS: Only mandatory shift assignments trigger activation costs (default). -
MANDATORY_AND_OPTIONAL_SHIFTS: Both mandatory and optional shift assignments trigger activation costs.
The Minimize activated employees soft constraint is invoked when an assigned shift belongs to an employee whose cost group defines employeeActivationCost and the shift matches activationShiftInclude.
The constraint adds a soft penalty to the dataset score when an employee is activated by one or more matching assigned shifts.
The penalty is calculated per activated employee as employeeActivationCost + (employeeActivationCost * shiftCount), where shiftCount is the number of matching assigned shifts for that employee, incentivizing Timefold to activate fewer employees and prefer lower activation-cost employees.
Shifts will still be assigned even if assigning them breaks this constraint.
|
Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints. Learn about constraint weights. |
2. Maximize activated employee saturation
The Maximize activated employee saturation soft constraint is invoked when an assigned shift belongs to an employee whose cost group defines employeeActivationCost and the shift matches activationShiftInclude.
The constraint adds a soft reward to the dataset score when an activated employee receives matching assigned shifts.
The reward is shiftCount * shiftCount per activated employee, where shiftCount is the number of matching assigned shifts for that employee, incentivizing Timefold to consolidate shifts on already activated employees.
Shifts will still be assigned even if assigning them breaks this constraint.
The constraint automatically applies to all employees with a cost group that has an employeeActivationCost defined. The constraint considers shifts based on the activationShiftInclude setting of each cost group.
|
Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints. Learn about constraint weights. |
3. Keep employee activation ratio
Employee cost groups can define an activation ratio weight that helps maintain desired proportions of activated employees between different groups.
This is useful for:
-
Maintaining a healthy mix of permanent and temporary staff.
-
Ensuring core employees form the majority of the workforce.
-
Meeting contractual or policy requirements about staff composition.
-
Balancing experience levels by maintaining ratios between senior and junior staff.
3.1. Configuration
Define employee cost groups with activation ratio weights:
{
"employeeCostGroups": [
{
"id": "regular-employees",
"employeeActivationRatioWeight": 3,
"activationShiftInclude": "MANDATORY_SHIFTS"
},
{
"id": "external-contractors",
"employeeActivationRatioWeight": 1,
"activationShiftInclude": "MANDATORY_SHIFTS"
}
]
}In this example, the solver will attempt to maintain a 3:1 ratio of regular employees to external contractors among activated staff.
The Keep employee activation ratio soft constraint is invoked when assigned shifts involve employees whose cost groups define employeeActivationRatioWeight.
The constraint adds a soft penalty to the dataset score when a cost group’s actual share of activated employees differs from the target ratio.
The constraint calculates the percentage of activated employees in each cost group and compares it to the target percentage derived from the ratio weights. If the actual ratio deviates from the target, a soft penalty is applied. The penalty is proportional to the deviation from the target ratio.
Shifts will still be assigned even if assigning them breaks this constraint.
|
Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints. Learn about constraint weights. |