Metrics and optimization goals

Timefold Platform helps you solve complex planning problems by searching for the best possible solution given your constraints. But how do you determine if one solution is better than another?

Each generated schedule is assigned a score based on hard, medium, and soft constraints. However, this score is primarily used by the solver to guide optimization and helps identify the impact of different constraints, but it doesn’t have a meaningful interpretation in your day-to-day operations. Read more about constraints and constraint scores.

That’s why the Timefold Platform provides a set of metrics that help you evaluate and compare different scheduling solutions in a way that aligns with your business objectives.

There are two levels of metrics available. Plan-level metrics assess the quality of a schedule as a whole, giving a high-level view of how well the plan meets your operational objectives. Employee-level metrics examine the impact of the schedule on individual employees, helping you identify which employees are overloaded, underutilized, or not getting their preferences met.

Plan-level metrics

Example metrics

Some example metrics for Employee Shift Scheduling are:

  • Unassigned shifts: The number of shifts that remain unfilled.

  • Working time fairness: A percentage indicating how evenly total working hours are distributed among employees.

  • Average duration of employees' preferences met: The average duration for which employee preferences (such as time spans, or shifts) have been satisfied.

We continuously update and refine the available metrics. You can view the most up-to-date list in the Timefold Platform UI or check the OpenAPI specifications for Employee Shift Scheduling.

Where to find metrics

You can access and analyze metrics in multiple places within Timefold Platform:

  • Dataset Detail Page: The sidebar displays five top-level metrics, with an option to expand and see all available metrics.

  • Plans Overview Table: Customize which metrics appear in the table to compare solutions across multiple datasets. Use tagging and filtering features to focus on certain segments.

  • Dataset Output: Metrics are included as part of the JSON output file for deeper analysis.

Goal alignment

Real-world scheduling is a balancing act between multiple competing objectives. Optimization is not a zero-sum game, improving one objective doesn’t always mean sacrificing another. Instead, constraint weights can be tuned to prioritize different goals. Metrics help you choose between different datasets with different optimization objectives.

Example optimization goals

Some example optimization goals for Employee Shift Scheduling are:

  • Increasing the number of assigned shifts.

  • Reducing overtime.

  • Reducing costs, taking into account the activation costs of freelancers.

  • Focusing on a fair distribution of work between different employees.

  • Increasing employee satisfaction:

    • Fulfilling PTO-requests from employees.

    • Honoring preferred times to work/not to work by employees.

An optimization goal is often a combination of the above. In Timefold the optimization goal is represented by the relative weights of the constraints.

Using configuration profiles for goal alignment

Our platform supports configuration profiles that allow you to define your objectives. This feature allows you to:

  • Compare how different priorities impact the final solution.

  • Identify solutions that balance objectives effectively.

  • Adjust trade-offs dynamically based on evolving business needs.

By using metrics and configuration profiles together, you can gain deeper insights into your scheduling challenges and ensure your optimization efforts align with your strategic goals.

Read more about configuration profiles in the Timefold Platform.

Employee-level metrics

While plan-level metrics assess the overall quality of a schedule, employee-level metrics let you examine the impact of a plan on individual employees. Use them to identify which employees are overloaded, underutilized, or not getting their preferences met.

Some metrics are only returned when the required contract rules or preference data are present for that employee.

Employee-level metrics are experimental and subject to change. There are no guarantees on backward compatibility.

Employee-level metrics are available per employee in the schedule response. You can explore the full schema in the OpenAPI specifications under EmployeeOutputMetrics.

Work metrics

Work metrics are always present for every employee in the schedule.

Metric Description

assignedShifts

The number of shifts assigned to this employee.

durationWorked

The total duration of all shifts assigned to this employee (ISO 8601 format, e.g. PT40H).

Deployment metrics

Metric Description When shown

maximumAvailabilityDuration

The estimated maximum number of hours this employee is available per week, derived from their required weekly hours limit.

Shown when a required weekly period rule is defined for the employee.

Overtime metrics

Metric Description When shown

overtimeThresholdDuration

The overtime threshold for this employee. Any duration worked beyond this threshold is considered overtime.

The threshold is taken from the preferred weekly rule when exactly one is defined. If no preferred rule exists, it falls back to the required weekly rule. Not shown when multiple preferred weekly rules are defined (ambiguous), or when no weekly rules are defined.

overtimeWorked

The duration of the overtime worked (i.e. the time in excess of the overtime threshold).

Calculated as durationWorked minus overtimeThresholdDuration. Not shown when multiple preferred weekly rules are defined (ambiguous), or when no weekly rules are defined.

Preference metrics

Preference metrics reflect how well the schedule aligns with an employee’s stated preferences and unpreferences. They are only present when the relevant preference data is defined for an employee.

Metric Description When shown

durationOfTimePreferencesMet

The total duration of the employee’s assigned shift time that falls within their preferred time slots.

Shown when the employee has at least one preferred time span, preferred shift tag, or preferred pairing defined.

durationOfTimeUnpreferencesViolated

The total duration of the employee’s assigned shift time that falls within their unpreferred time slots.

Shown when the employee has at least one unpreferred time span or unpreferred pairing defined.

Disruption metrics

Disruption metrics track how much a re-optimization changed the existing schedule. They are only present when an existing schedule was provided as input. See Defining disrupted shifts for how disruption is defined, and Minimizing disruption due to real-time planning for how to control it.

Metric Description

disruptedShifts

The total number of disrupted shifts for this employee (both incoming and outgoing).

durationOfDisruptedShifts

The total duration of disrupted shifts for this employee.

incomingDisruptedShifts

Shifts that are now assigned to this employee that were not assigned to them before re-optimization.

durationOfIncomingDisruptedShifts

The total duration of incoming disrupted shifts.

outgoingDisruptedShifts

Shifts originally assigned to this employee that are now assigned elsewhere or unassigned.

durationOfOutgoingDisruptedShifts

The total duration of outgoing disrupted shifts.

Cost metrics

Cost metrics are only present when cost definitions are configured for an employee.

Metric Description

costDefinitionTotalCost

The total cost of this employee’s schedule, as per their cost definitions.

costDefinitionOvertimeDuration

The overtime duration in this employee’s schedule, calculated based on the cost definitions.

Assess and compare employee-level metrics in the UI

The Employee efficiency visualization surfaces four derived metrics per employee (Deployment, Overtime, Preferences, and Unpreferences), each computed from the employee-level metrics described above. See that page for the full mapping and interpretation.