Transition from using Cascading Update Shadow to PlanningList

[ronjonsilver]

Hello,

I am new to using timefold and I have been struggling with trying to move over from using CascadingUpdateShadowVariable on my arrivalTime variable because that only gives me specific availabilities although I want to try timeslots instead.

Possibly my model is not setup correctly, the goal of using timefold is to find the best time (or could be changed to timeslot) within a providers availability.

1. I have providers that have specific availability during the day
2. Initially I have orders although most orders will be added by the RecommendAPI with selection, orders have minStart and maxEnd and service duration.
3. Times that are 30 minutes apart (or maybe this could be dynamic)

I started with Cascading because that was the easiest to get working and now my problem is that timefold is not able to select other available times because it either goes for the minStart, previous or next order, so just placing the order in different spots. I like the fact that I Have previous and next order but It seems that it is not supported if I transition to using timeslots ?

I want to score times based on my constraints. This is not that similar to the timestable sample because an order can go in providers tomorrow's schedule or a month from now. Each Day has its own solution but timefold can still move orders to other days.

I want to be able to recommend BEST (Least score with soft score) times or SOONEST (no hard score but date is closest to now) times.

Current Setup:

@PlanningSolution
public class Solution{

    @ProblemFactCollectionProperty
    private List<Provider> providers;
    
    @ValueRangeProvider(id = "orders")
    @PlanningEntityCollectionProperty
    private List<Order> orders;

    @ValueRangeProvider(id = "providerDayScheduleRange")
    @PlanningEntityCollectionProperty
    private List<ProviderDaySchedule> providerDaySchedules;

}

@PlanningEntity
public class Order {

    @PlanningId
    private Long id;
    
    @InverseRelationShadowVariable(sourceVariableName = "orders")
    private ProviderDaySchedule providerDaySchedule;
    
   @PreviousElementShadowVariable(sourceVariableName = "orders")
    private Order previousOrder;

    @CascadingUpdateShadowVariable(targetMethodName = "updateArrivalTime")
    private LocalDateTime arrivalTime;
    
    @NextElementShadowVariable(sourceVariableName = "orders")
    private Order nextOrder;
   
}


@PlanningEntity
public class ProviderDaySchedule {

 @PlanningId
    private String id;

    private Provider provider;

    private LocalDate date;

    private List<LocalDateTime> possibleTimes;
    
    @PlanningListVariable(valueRangeProviderRefs = "orders")
    private List<Order> orders;


}

Now this solution works although I want to use possibleTimes (that generates when ProviderDaySchedule is constructed) AS WELL as the efficient times that my current updateArrivalTime (using previousOrder and nextOrder as time reference) method provides. I tried to use timeslots from other examples but that setup breaks my logic and it is difficult to apply.

Expected end result planning solution:

ProviderDaySchedule: Provider #42 — 2025-07-17
  ├── Order #1001 @ 09:00 (arrives from provider HQ)
  ├── Order #1005 @ 10:15 (after drive + wait)
  └── Order #1010 @ 11:30 (avoiding lunch time block)

ProviderDaySchedule: Provider #42 — 2025-07-18
  ├── Order #1101 @ 08:30
  └── Order #1122 @ 10:00

ProviderDaySchedule: Provider #21 — 2025-07-17
  └── Order #2001 @ 14:00

Any help is appreciated! Thank you

[ace19wre]

Please take my input with a grain of salt, as I'm still in the process of learning Timefold.

I have orders although most orders will be added by the RecommendAPI with selection

Why would you do this? the recommendation API only uses Construction Heuristics so it won't scale well and I believe it can't change the values of already assigned entities, so it has no ability to create other solutions to check their quality(score).

Each Day has its own solution but timefold can still move orders to other days

Are you saying that each Order has a specific due-date, if yes then include it as a problem fact in the Order entity. You can use that information in a constraint to penalise the amount of gap between the arrival-time (which is what I believe you are trying to plan) and the due day (choose a specific time for end of working day).

By doing this you can submit all the orders once and also let the solver make use of Local Search which is its super power.

[ronjonsilver]

Why would you do this? the recommendation API only uses Construction Heuristics so it won't scale well and I believe it can't change the values of already assigned entities, so it has no ability to create other solutions to check their quality(score).

I didn't realize that is the case with recommend API. I am using timefold to display timeslots for users to select from. That is why I am looking to use the recommend API because I will have a set plan in the system and the way orders will come in is through Timeslot selection by the user. Can we enforce the recommendAPI to try and move things around if a solution is not pinned ?

Are you saying that each Order has a specific due-date, if yes then include it as a problem fact in the Order entity. You can use that information in a constraint to penalise the amount of gap between the arrival-time (which is what I believe you are trying to plan) and the due day (choose a specific time for end of working day).

I did give this some thought and I believe that I can remove the ProviderDaySchedule and just have timeslots for all possible providers and let timefold do the sorting.

By doing this you can submit all the orders once and also let the solver make use of Local Search which is its super power.

The issue is I don't have all orders or schedule from the start, orders will come in at any time of the day and I need to recommend them a time and let the user select a time. Does that make sense ? I hope there is a way with timefold to get the highest scoring timeslots and if it can shift other orders around to make room for the one i am trying to add, it would be great.

Looks like it is stated here
https://docs.timefold.ai/timefold-solver/latest/responding-to-change/responding-to-change#assignmentRecommendationAPI

I can run the solution after a user selects a timeslot, although I am not sure how much benefit this will give us if the constraints are tight. Also, I can use a similar approach as timeslot but then generating best possible timeslots will be a challenge because I would need to generate all possible timeslots for the days the orders are set on.

[ronjonsilver]

I tried introducing timeslot generation along with my current solution that way timefold will try to keep the arrivalTime in those timeslots.

Added to solution

    private List<Timeslot> timeslots;

    @ProblemFactCollectionProperty
    @ValueRangeProvider(id = "timeslots")
    public List<Timeslot> calculateAvailableTimeSlots() {

Added to my Order

    @PlanningVariable(valueRangeProviderRefs = "timeslots")
    private Timeslot timeslot;
    

I got

caused by: java.lang.IllegalArgumentException: The config (QueuedValuePlacerConfig(ValueSelectorConfig(orders), ListChangeMoveSelectorConfig(ValueSelectorConfig(null), null))) has no entityClass configured and because there are multiple in the entityClassSet ([class ......provider.ProviderDaySchedule, class ......client.Order]), it cannot be deduced automatically.

Then I move my timeslot list to ProviderDaySchedule

@PlanningEntity
public class ProviderDaySchedule {

    @PlanningId
    private String id;

    private Provider provider;

    private LocalDate date;
    @PlanningListVariable(valueRangeProviderRefs = "orders")
    private List<Order> orders;

    @PlanningListVariable(valueRangeProviderRefs = "timeslots")
    private List<Timeslot> timeslots;

I got

Defining multiple list variables ([ProviderDaySchedule.orders variable, ProviderDaySchedule.timeslots variable]) across the model is currently not supported.