Employee scheduling quick-start and the design patterns

[parsagit]

Hi,

First of all, I'm very happy that TimeFold engine is open source and has received a lot of love from the maintainers.

That said, after playing around with an employee scheduling problem, I ran into quite a few issues when dealing with real employee scheduling task. I had hard time understanding how to design rules such as:

• Someone is off every Tuesday
• Another person works every Wednesday in a morning shift
• Saturday shifts circulate in a "round robin", so the same person is working only one saturday / divided by the number of current employees
• Monday evening shifts are have also similar "round robin" structure
• Some people work only part time
• Everyone has to have work for all hours of the week
  etc...
  There are something like 10 more rules like this, some more obscure.

It was quite tedious to find solutions for this kind of constraint design problems. With trial and error I finally managed to make something that works good enough.

My biggest struggle was actually with under assignment. I would never know the exact number of shifts there has to be each week in advance. I would know the number of mandatory shifts where someone has to be, but not the number of optional shifts that also have to be assigned evenly, and in fair way, so that someone is not always working in morning shifts, while other person always has evening shifts.

I see that the enterprise edition has most likely solutions for all these problems, but as an open source user one to figure those out by themselves. Which is fine and understandable. However, I think personally that if the quick-start solution was improved to support dealing with this kind of problems, it would make planning software more accessible and increase the market size for the enterprise offering.

For example, reading the documentation, I found out that docs suggest a separate planning entity, ShiftAssignment:
https://docs.timefold.ai/timefold-solver/latest/design-patterns/design-patterns

However, the employee scheduling quick start has the Shift as a planning entity, as seen here:
https://github.com/TimefoldAI/timefold-quickstarts/blob/stable/java/employee-scheduling/src/main/java/org/acme/employeescheduling/domain/Shift.java

Furthermore, the quick-start does not also define the contract/shift constraints. I don't really know now if I should redesign the solution, as it is sort of good enough now for running in local and replacing the excel. However, I would really like to make it correct.

This was quite a long story now, but my questions are probably:

• Do you have any plans to improve the quick start to adapt from your enterprise employee scheduling design?
• I might be interested towards contributing making employee-scheduling quick-start better, but I'm not an expert and I don't know if my contribution would be meaningful, especially code-wise, because I don't know what is really a good design. Are you willing to share more information how the different entities are designed? Like, what entities there even are?

Best regards,
Tapio

[Christopher-Chianelli]

• Someone is off every Tuesday
• Another person works every Wednesday in a morning shift
• Saturday shifts circulate in a "round robin", so the same person is working only one saturday / divided by the number of current employees
• Monday evening shifts are have also similar "round robin" structure

Typically, a preferredEmployee field is added to the Shift class to implemented these. Often times, it is easier (and potentially more efficient) to add a new domain object/field that provides context for a constraint.

My biggest struggle was actually with under assignment. I would never know the exact number of shifts there has to be each week in advance. I would know the number of mandatory shifts where someone has to be, but not the number of optional shifts that also have to be assigned evenly, and in fair way, so that someone is not always working in morning shifts, while other person always has evening shifts.

This is why we introduced the load balancing collector:

Constraint fairlyAssignNights(ConstraintFactory constraintFactory) {
    return constraintFactory.forEach(Shift.class)
            .filter(Shift::isNightShift)
            .groupBy(Shift::getEmployee, ConstraintCollectors.count())
             // Need this so unassigned employees are also balanced
            .complement(Employee.class, employee -> 0)
            .groupBy(ConstraintCollectors.loadBalance((employee, count) -> employee, (employee, count) -> count))
            .penalizeBigDecimal(HardSoftBigDecimalScore.ONE_SOFT, LoadBalance::unfairness)
            .asConstraint("balance night shift assignments");
}

A variant of this constraint (without the night shift filter) is included in the employee scheduling quickstart: https://github.com/TimefoldAI/timefold-quickstarts/blob/a8bfbca8695b59944936f3f8b569a25611b75166/java/employee-scheduling/src/main/java/org/acme/employeescheduling/solver/EmployeeSchedulingConstraintProvider.java#L113-L121

For example, reading the documentation, I found out that docs suggest a separate planning entity, ShiftAssignment:
https://docs.timefold.ai/timefold-solver/latest/design-patterns/design-patterns

However, the employee scheduling quick start has the Shift as a planning entity, as seen here:
https://github.com/TimefoldAI/timefold-quickstarts/blob/stable/java/employee-scheduling/src/main/java/org/acme/employeescheduling/domain/Shift.java

The example in https://docs.timefold.ai/timefold-solver/latest/design-patterns/design-patterns is for point 5: "If there is an orange many-to-many relationship, replace it with a one-to-many and a many-to-one relationship to a new intermediate class." The "Shift" in that example is just a date/location pair. So Shift in the Employee Scheduling quickstart = ShiftAssignment (employee) + Shift (date + location) in that example. FWIW, the references to ShiftAssignment should probably be removed from the docs and replaced with a different example.

[parsagit]

Thank you for the throughout response. That constraint is clear, and I got those rules working as expected (for the most part). Without going into too much detail about each solution, I have added several rules to my constraint solver such as:

  @Override
   public Constraint[] defineConstraints(ConstraintFactory constraintFactory) {
       return new Constraint[] {
               // Hard constraints (in order of importance)
               noOverlappingShifts(constraintFactory),
               atLeast10HoursBetweenTwoShifts(constraintFactory),
               oneShiftPerDay(constraintFactory),
               unavailableEmployee(constraintFactory),
               maxDaysPerWeek(constraintFactory),
               requiredShift(constraintFactory),
               unavailableShift(constraintFactory),
               saturdayRoundRobin(constraintFactory),
               fridayCheckPreviousSaturday(constraintFactory),
               mondayRoundRobin(constraintFactory),
               mondayNotSameWeekAsSaturday(constraintFactory),
               // Soft constraints
               desiredDayForEmployee(constraintFactory),
               undesiredDayForEmployee(constraintFactory),
               desiredShiftForEmployee(constraintFactory),
               undesiredShiftForEmployee(constraintFactory),
               balanceEmployeeShiftAssignments(constraintFactory),
               encourageOptionalShiftAssignments(constraintFactory),
               minimizeShiftOverlaps(constraintFactory)
       };
   }

but what I struggle with is whether this is the right way of solving these problems. Whether I'm following the "right" design patterns. In that regard, a concrete question would be that:

• How to define the correct number of shifts when that depends on the number of employees?

I solved it by adding optional shifts to every day and adding @PlanningVariable(allowsUnassigned = true), so that there is enough shifts to satisfy every employees full hours, and then added a rule to encourage assigning them as long as they don't violate any other rules. It works, but it feels like some sort of hack.

[Christopher-Chianelli]

If I understand your question correctly, you are adding virtual shifts to satisfy employee minimum hours? That is the correct approach that is mentioned in our docs: https://docs.timefold.ai/timefold-solver/latest/responding-to-change/responding-to-change#overconstrainedPlanning ; (although it is in reverse: instead of having too few employees to assign all shifts, you have too few shifts to assign all employees).

[tomashauser]

FWIW, the references to ShiftAssignment should probably be removed from the docs and replaced with a different example.

It's even worse since the ShiftAssignment solution isn't even many-to-many. That would be the first case which is marked as bad model (it would include null values in the search space though). The presented solution implements a one-to-many relationship from Employee to Shift. Assuming that the Employee has a corresponding @ValueRangeProvider and Shift is a problem fact.

So Shift in the Employee Scheduling quickstart = ShiftAssignment (employee) + Shift (date + location) in that example.

Agreed. Then I see no point in creating the ShiftAssignment class since it can be flattened without loss of information or functionality.

Moreover, I'm interested in the Employee Rostering starter application they're referring to in the linked docs. Since this is from the Optaplanner days, I assume it was released as open source. Maybe we would find the answer there. Is it this perhaps?

[triceo]

The "Employee Rostering starter application" has no Timefold equivalent and has no business being in the docs - thanks for pointing this out.

For the record, it is describing this long-abandoned repository. (It was already abandoned by OptaPlanner even before Timefold forked.)