Planning Employee Shifts like a Pro with Timefold and Bryntum

Employee shift scheduling is a classic yet complex optimization problem faced by many industries. How best can organizations balance employee preferences, shift coverage, labour regulations, and fairness during work assignments? This blog post demonstrates how effortless shift planning becomes with Timefold’s advanced constraint-solving capabilities and Bryntum’s powerful scheduling UI.

This video showcases a Timefold and Bryntum integration used to build an intelligent, user-friendly planning solution.

We highlight some key considerations for creating a shift scheduler and explain how Timefold’s Employee Shift Scheduling (ESS) model addresses the technical aspects of each consideration, while Bryntum Scheduler handles the visual aspects in the UI.

Availability

Employees aren’t always available for work. To ensure that employees are only assigned to shifts during their available hours, you may want your schedule to automatically consider their shift preferences. For example, an employee may request morning shifts on Wednesdays so that they have time for their kids in the afternoon.

The goal isn’t just to create a feasible schedule, but to create one that aligns with individual preferences where possible, striking a balance between operational needs and employee well-being.

Bryntum

Bryntum Scheduler uses visual cues and UI constraints to communicate employee availability to planners. You can input employees’ preferred hours and convey the information using availability calendars, time ranges, or background highlights that indicate when each employee (or resource) is available.

Bryntum provides multiple ways you can enhance the usability of schedules:

• Visually block off unavailable time slots to prevent accidental assignment.
• Use tooltips, colored tags, or the showMeta config under each resource to display shift preferences.
• Restrict drag-and-drop assignments to valid availability windows to improve planning accuracy and reduce manual errors.

These visual aids give planners immediate insight into who can work when, helping them ensure that shift assignments respect both hard constraints, like availability, and soft constraints, like shift preferences, before sending the data to the backend for validation.

Timefold

There are two ways to express employee availability in the Timefold ESS model:

• Use unavailableTimeSpans to define when an employee cannot work (for example, during vacations).
• Use availableTimeSpans to specify explicitly when an employee can work (this approach is ideal for part-time or flexible staff).

These time spans act as hard constraints. Shifts assigned outside the designated windows are considered invalid and immediately flagged during the solving process.

In addition to availability, Timefold supports the following soft preferences, which improve schedule quality:

• UsepreferredTimeSpans and unpreferredTimeSpans for expressing time-based preferences.
• Use preferredShiftTags for shifts that align with employee interests or strengths.

These preferences help guide the Timefold Solver toward more employee-friendly outcomes without compromising the overall feasibility of the plan.

By combining hard constraints for availability with soft constraints for preferences, Timefold ensures that shift assignments are both valid and aligned with employee well-being.

Work Limits

Limiting the number of hours employees work is important for meeting contractual obligations and promoting employee happiness.

Work limits can be managed in different ways depending on the requirements. For example, the planner could manage contractual hours by minute, by day, or by shift, across either fixed periods or rolling windows.

Bryntum

While it hasn’t yet been implemented in the Timefold x Bryntum demos, Bryntum Scheduler includes options for representing workload limits visually (for example, by using maximum allocations). These visual markers give planners immediate insight into how the workload is distributed across the team.

Using the showMeta config of the ResourceInfoColumn, you can display additional contextual data, such as current vs maximum allocations, skill tags, or any other resource-specific metadata.

In the Skill Matching demo, showMeta is used to display allocated hours per resource. Similar techniques can be used to highlight over- or under-used resources at a glance, helping planners make informed decisions quickly.

showMeta(resourceRecord) {
	const
	{ skillNames }         = resourceRecord,
	{ startDate, endDate } = this.grid,
	bookedHours            = resourceRecord.getBookedHours(startDate, endDate),
	overAllocated          = bookedHours > resourceRecord.hoursPerWeek;

	return `<ul class="skills">${skillNames.map(skill => `<li>${StringHelper.encodeHtml(skill)}</li>`).join('')}</ul>
	<div data-btip="${bookedHours}h / ${resourceRecord.hoursPerWeek} allocated"><i class="b-fa ${overAllocated ? 'b-fa-triangle-exclamation' : 'b-fa-clock'}"></i>${bookedHours} / ${resourceRecord.hoursPerWeek}</div>`;
},

Timefold

The Timefold ESS model allows you to configure fine-grained rules for managing various types of employee work limits, including:

• Minutes worked per day, week, or month
• Shifts worked within a fixed or rolling window
• Days worked per period or consecutively

These limits can be defined as hard constraints to prevent over-scheduling or as soft constraints to allow for minor deviations. For example, you can enforce a maximum of 32 hours per week and simultaneously avoid assigning employees more than five consecutive working days.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max32HoursPerWeek",
          "period": "WEEK",
          "minutesWorkedMax": 1920 //32h * 60 minutes per hour
        }
      ]
      "consecutiveDaysWorkedRules": [
        {
          "id": "Max5ConsecutiveShifts",
          "maximum": 5,
        }
      ]
    }
  ]
}

With this flexibility, Timefold enables planners to build schedules that are operationally feasible and align with legal, contractual, and employee health considerations.

Skills and risk factors

Assigning the right employees to the right shifts is critical to ensuring operational efficiency, safety, and quality of service. Matching required skills with employee qualifications minimizes risk, prevents performance issues, and ensures compliance with role-specific demands.

Bryntum

The Bryntum Scheduler Skill Matching demo also illustrates how tasks can only be reassigned to employees who possess the required skills. For instance, a task requiring the Surgery skill cannot be assigned to an employee without that skill.

To improve usability, you can display required skills in multiple locations, such as beneath employees’ names, using the showMeta config (as discussed earlier), or within task tooltips. These immediate visual reminders alert planners to skill requirements and help prevent invalid assignments during drag-and-drop operations.

Timefold

The Timefold ESS model allows you to define the skills and risk factors for each shift. By setting required skills and checking them against employee qualifications, you ensure that shifts are assigned only to suitably qualified employees. This improves operational safety, compliance, and task efficiency.

Define required skills by including a list of skills for each employee object and specifying which skills are mandatory for each shift. For example, if a shift requires "Surgery" or "CPR" skills, only employees who possess those skills will be considered valid candidates. This is enforced as a hard constraint, ensuring no invalid assignments.

{
 "employees": [{
  "id": "Beth",
  "skills": [
    {
      "id": "Surgery"
    }]
  }],
  "shifts": [
    {
      "id": "MondaySurgery",
      "start": "2027-02-02T09:00:00Z",
      "end": "2027-02-02T16:00:00Z",
      "requiredSkills": [
        "Surgery"
      ]
    }
  ]
}

The Timefold ESS model also supports preferred skills, which act as soft constraints. These allow the Timefold Solver to prefer, but not strictly enforce, assignments based on skill alignment.

Beyond skills, the Timefold Solver can model risk factors, allowing it to apply constraints that help mitigate safety issues by preventing incompatible or unsafe assignments. For example, you could use risk factors to prevent assignments that would place employees with medical vulnerabilities in high-risk environments.

Together, these capabilities allow Timefold to generate intelligent schedules optimized for both safety and qualification-based assignments.

Manual Changes

Planners may occasionally want to override the optimized schedule and make manual adjustments. Human intuition and expertise remain relevant, especially when the schedule confronts the unwieldy nature of daily operations.

However, when making manual edits you can unintentionally break constraints, for example, by assigning a task to someone who is unavailable, lacks the required skills, or exceeds their work limit.

By combining Bryntum with Timefold, you can build systems that give planners AI-driven insights while also giving them the option to ignore these insights and trust their intuition.

Bryntum

Bryntum Scheduler enables easy manual modifications to the schedule through intuitive drag-and-drop interactions, direct editing, and context menus. In the demo, tasks can be reassigned to different employees or times directly in the UI. This is particularly useful when planners need to make on-the-fly decisions that reflect real-world priorities.

When a task is manually adjusted, such as when it is moved to a different resource or timeslot, Bryntum immediately reflects the change in the UI while maintaining responsiveness and user feedback (such as snapping, validation, and visual cues). It then passes the edits back to the Timefold planning engine for real-time evaluation.

This seamless interaction allows planners to experiment and intervene when necessary, without breaking the user experience or losing connection with the underlying optimization logic.

Timefold

When planners manually override an optimized schedule, Timefold’s real-time planning capabilities ensure they get feedback about the impact of their changes on the overall schedule. Using Timefold’s score analysis capability, the new schedule is instantly evaluated for any constraint violations.

{
  "constraints": [
    {
      "name": "Employee works during unpreferred time",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/-960soft",
      "matches": [
        {
          "justification": {
            "shift": "MorningShift",
            "employee": "Dan Jones",
            "overlappingTimeSpans": [
                {
                    "start": "2027-03-19T08:00:00Z",
                    "end": "2027-03-29T16:00:00Z",
                    ...
                }
            ]
          }
        }...

By executing score analyses when tasks are changed manually and by reflecting these changes in the Bryntum UI, the integrated app allows planners to see whether their changes accidentally violate any policies. This feedback loop maintains control and transparency, enabling manual interventions while preserving schedule feasibility and quality.

Replanning and pinning

An optimized plan is great, but it becomes worthless if it doesn’t adjust to unexpected changes, like an employee falling ill or an unpredicted increase in demand. With Timefold and Bryntum, you can enable planners to partially replan their schedules.

Planners can Pin certain assignments to prevent them from being moved during replanning, ensuring that certain external commitments, manual overrides, and confirmed assignments remain honoured.

Additionally, configurable anti-disruption mechanisms ensure that changes are minimized during replanning. This prevents situations like all employees having to work different tasks just because one employee got sick.

These two features give planners the flexibility to lock in business-critical decisions while still benefiting from optimized and automated scheduling.

Bryntum

Bryntum Scheduler flexibly supports pinning in the UI. You can implement a custom Pin option in the context menu (which appears when a user right-clicks on a task), for toggling tasks into a pinned state. For added clarity, you can visually indicate pinned tasks using a pin or lock icon.

However, this UI interaction must be followed by an update to the backend. The pinned state should persist and should be included as part of the planning problem sent to Timefold. Only then will the Timefold Solver exclude pinned tasks from re-optimization.

Use the following code to implement a custom Pin option in the context menu:

processItems({ eventRecord, items }) {
        // Pinning forces the assignment, so Timefold will plan around it.
        items.lock = {
        text   : eventRecord.pinned ? 'Unpin' : 'Pin',
        icon   : 'b-fa b-fa-fw b-fa-thumbtack' + (eventRecord.pinned ? '-slash' : ''),
        weight : 121,
        onItem({ eventRecord }) {
	      eventRecord.pinned = !eventRecord.pinned;
	    }
		}
	}
}

Display a pin icon on pinned tasks to help planners identify them at a glance:

    eventRenderer({ eventRecord, renderData }) {
        renderData.cls['b-sch-event-with-problems'] = eventRecord.problems?.length > 0;
        return [
            eventRecord.pinned ? { class : "pinned-icon b-fa b-fa-thumbtack" } : undefined,
            {
                class    : 't-event-meta',
                children : (eventRecord.requiredSkills || []).map(skill => ({
                        class : "badge",
                        text  : skill,
                        style : `background-color:${BadgeColumn.colorPalette[skill]}1a;color:${BadgeColumn.colorPalette[skill]}`
                    })
                )
            }
        ]
    }

Timefold

The Timefold ESS model ensures that the schedule remains as stable as desired when shifts are recalculated due to absences, last-minute requests, or changes in availability.

Shifts and tasks are pinned when they are marked as fixed ("pinned": true) in the model input that is sent to the model API. The ESS model then treats these shifts as immutable and only reassigns unpinned tasks during re-optimization.

You can also configure additional disruption rules, which act as soft constraints that tell the model it should prefer to preserve existing assignments. Each rule defines a time window and a multiplier that, together, define how costly it is to change a shift in a certain period.

For example, to protect near-term stability while still allowing longer-term optimization, you could apply a high multiplier to shifts in the next few days and a lower multiplier to later shifts. The ESS model also provides KPIs such as disruptionPercentage to help you monitor how much a schedule changes during replanning.

Conclusion

We’ve covered just a few of the constraints, features, and visual tools you can use when combining the Timefolder ESS model with Bryntum Scheduler components. Gather inspiration for your use case by exploring the many possibilities in the Bryntum Scheduler demos and Timefold’s model documentation.