Analyzing Unscheduled Orders

This sample describes how to analyze the reason, why an order remains unscheduled by the xTour service.

Benefits

  • Users learn how to use and integrate the operations of xTour that analyze unscheduled orders.

Prerequisites

Please ensure following prerequisites are fulfilled before you start with the use case:

Concepts

Programming Guide

This example provides information on how to analyze unscheduled orders to find out why they remained unplanned or if the orders are unplannable.

After passing a PlanToursRequest to the planTours operation of the xTour service, a number of orders may remain unplanned. As preparation for the analysis of the unscheduled orders, the plan must be stored using the field storeRequest in the PlanToursRequest. The analysis itself depends on whether the orders are unplanned or unplannable.

Analyze unplanned orders

For an unplanned order whose id is in orderIdsNotPlanned, but not in orderIdsNotPlannable, we can simply send an InsertionPositionsForOrdersQuery. The field orderIds contains the id of the order to analyze. Note that only one order can be analyzed at a time. If you leave targetVehicleIds empty, then all possible insertion positions for all vehicles are proposed. As we expect all insertion positions to be violated, returnViolatedTours has to be set to true.

The resulting proposals contain MoveOrdersActions and AddTripActions. Each proposal only contains the changed tour. The corresponding TourViolationReport contains the violations occurring when inserting the order at the given position. We can use this report to find out what prevented the order from being scheduled. As the order is unplanned but not unplannable, an additional vehicle would always be a feasible way to schedule the order.

The following sample contains a simple way of aggregating the violations in the proposals to find out whether the planning horizon or the opening intervals are the reason for an order being unplanned. You can modify the initial plan by changing useShortPlanningHorizon:

  • Set useShortPlanningHorizon to true, so that an order cannot be planned because of the planning horizon being too short.
  • Set useShortPlanningHorizon to false, so that an order cannot be planned because of an opening interval being too short.

When sending an InsertionPositionsForOrdersQuery for an order referenced in orderIdsNotPlanned, each of the resulting ChangeToursProposals should have at least one of the following properties:

If this is not the case, the algorithm should find the respective insertion position from the very beginning.

Analyze unplannable orders

Contrary to the previous part, unplannable orders cannot be served using additional vehicles. For a reasonable analysis, we need a plan without tours, so that we can find out the reason for the order being unplannable even if the vehicles do not serve any other order.

In the following sample, the request contains an order with a 20-hours service time. Even a completely empty vehicle cannot serve the order, because the planning horizon only has a length of 8 hours. After planning, the id of the unplannable order is in orderIdsNotPlannable. In function createSingleOrderPlan a plan is created which only contains the unplannable order. Function analyzeUnplannableOrders then runs an InsertionPositionsForOrdersQuery like before. Only one AddTripAction per vehicle is created. We again have a look at the TourViolationReport to find out the reason for the order to be unplannable, which in this example is the planning horizon being too short.

Limiting the resulting number of proposals of an InsertionPositionsForOrdersQuery

Running an InsertionPositionsForOrdersQuery yields all possible insertion positions for the given order. While the number of AddTripActions is limited by the number of vehicles and existing trips, many more MoveOrdersActions may be proposed, depending on the size of the plan.

Therefore, you can limit the number of MoveOrdersActions using the field maximumNumberOfMoveOrdersActions so that at most the given number of nearest insertion positions are returned.

Note

We recommend not to exceed the default value of 100, as a larger number hardly increases the quality of the proposals, but increases the computation time and the response size.

Additionally, you can limit the proposed MoveOrdersActions using maximumDistanceOfAdjacentStops to a certain area around the customer site of the given order (or in case of a depot-depot transport to an area around both depot sites). Only stops in this area may be used as neighboring stops for the insertion.