Manual Edit Actions

During the daily planning lifecycle, dispatchers and planners frequently need to interpret unexpected events, manually shift workloads, or execute precise adjustments that optimization models might not handle automatically or immediately. Manual Edit Actions refer to discrete endpoints and directives provided through the APIs to force changes directly onto routes, vehicles, and bookings.

This document outlines each action supported by SWAT's manual edit module, including its real-world utility, rules, and limitations.

You can reference the detailed schema variables and parameters necessary to make these API calls under the Manual Edit Actions API documentation.

Routing & Sequencing Adjustments

These actions allow operators to physically restructure how and when vehicles arrive at physical stops.

Re-arrange Stops on a Route

Provides an intuitive override of a driver's ongoing trip to account for human knowledge, such as avoiding a specific congested bridge or taking a familiar detour.

• Action Name: vehicle_reorder_nodes
• Use Case: A dispatcher recognizes a poor algorithmic sequence and physically drags-and-drops the sequence of assigned stops to something more intuitive for the driver, forcing the trip order to match their expectations.
• Limitations & Rules:
  • Pickup nodes must structurally remain before their corresponding Dropoff nodes.
  • If a vehicle is "live" (has non-zero coordinates), the immediate next assigned node after any completed or in-service node cannot be reordered. (If node grouping is enabled, the entire group is considered the "next upcoming node" and cannot be rescheduled).
  • It is possible to specify COMPLETED nodes in the sequence, provided they remain grouped at the beginning and do not intertwine with ASSIGNED nodes.
  • If strict_time_windows is enabled, the new manually arranged sequence must satisfy the nodes' static time window constraints, or the edit will be rejected.

Balance Load Across the Fleet

Address massive workload imbalances visually, ensuring operations execute smoothly and drivers are working fair hours without overutilizing single units.

• Action Name: vehicle_complex_rearrange
• Use Case: Viewing a timeline of all fleet vehicles, a dispatcher realizes that "Vehicle A" has a highly overloaded afternoon while "Vehicle B" is entirely idle. They multi-select five stops from Vehicle A and pull them onto Vehicle B's timeline to synchronously manual load-balance the afternoon shift.
• Limitations & Rules:
  • A dropoff node cannot be reassigned to a different vehicle or placed back into the unassigned pool if its corresponding pickup node has already been completed or is actively being served.
  • Within the new routes, a dropoff node must always be placed structurally after its pickup node.
  • Vehicle capacity limitations are explicitly not validated during this action.

Assignment Management

These actions govern the relationship between orders (bookings) and the vehicles executing them.

Force-Assign Specific Bookings

Eliminate algorithmic distribution for urgent ad-hoc pickups by locking unassigned work to a specific, active driver in the area.

• Action Name: vehicle_assign_booking_list
• Use Case: A planner has a pool of local deliveries that haven't been routed yet, but knows that a specific local contractor with an empty truck is actively waiting for work. Setting hard assignments ensures those particular orders are assigned exactly to that driver.
• Limitations & Rules:
  • If a vehicle is "live", nodes cannot be inserted before the node that is next on the ongoing route. Similar to re-ordering, if node-grouping is active, the entire group encompasses the "next upcoming node."
  • You can strictly inject new pickups or dropoffs into precise locations in the route by specifying what node to insert before/after. Alternatively, you can have the solver optimize the insertion location based on routing efficiency by omitting these structural parameters.
  • Options such as strict_capacity and strict_time_windows control whether the solver rejects the assignment if the vehicle is incapable of executing it legally.

Return Bookings to the Unassigned Pool

Quickly relieve an incapacitated driver of their workload so the engine can immediately re-dispatch the orders to healthy vehicles.

• Action Name: vehicle_unassign_bookings
• Use Case: A driver experiences a mid-route breakdown or gets held up unexpectedly at a delivery. The remaining stops on that route are unassigned in bulk so the optimization engine can re-distribute them to other nearby, active drivers to ensure they aren't missed.
• Limitations & Rules:
  • Just like routing insertions, if a vehicle is "live", the API will prevent unassigning a booking if the immediate next required node on the driver's route belongs to that booking.
  • You can issue partial success directives; meaning if ten bookings are ordered to unassign, and one fails because the driver is currently executing it, the action will successfully unassign the remaining nine rather than reverting the entire payload.

Timing Modifications

These actions manipulate the specific timeframe intervals bounding deliveries.

Adjust Customer Delivery Windows

Respond proactively to customer availability changes, tightening or widening constraints so the routing engine appropriately reprioritizes subsequent driving ETAs without breaking the route sequencing. This action is also capable of shifting vehicle departure time. The combination of shifting time windows and departure time within a single action allows to achieve the required combination of scheduled times and slacks.

• Action Name: shift_nodes_time_windows
• Use Case: A customer calls in indicating they are leaving their house early, and requests their delivery window be tightened. The dispatcher edits the time window boundaries on the individual spot. The solver subsequently recalculates all timings while trying to accommodate the strict boundaries, pushing subsequent downstream ETAs securely without ripping the delivery out of the current order sequence.
• Limitations & Rules:
  • Currently, the action only supports editing of a single vehicle and its assigned nodes.
  • Nodes must natively possess the ASSIGNED status and be assigned to the same vehicle.
  • Adjusted time windows cannot violate or shift beyond the hard time bounds of the physical simulation schedule or the vehicle's shift boundaries.
  • Updated time windows are propagated to bookings (min_pickup_time and max_pickup_time are also updated).
  • Lateness behaviour is restricted by master simulation parameters (logistics_api_settings.manual_edit_allow_vehicle_late and logistics_api_settings.manual_edit_try_strict_time_windows_request). See the Logistics API Settings documentation for more details.

Shift an Entire Route Schedule

Rectify cascaded delays globally for a vehicle to ensure subsequent ETAs portrayed to downstream customers accurately reflect real-world vehicle lag.

• Action Name: vehicle_shift_nodes
• Use Case: A driver started their route an hour later than planned because of heavy traffic arriving at the depot. Rather than displaying operations ETAs that appear an hour late for every single customer all day, the dispatcher uses this action to slide the scheduled arrival timestamp of the first node an hour forward, which sequentially updates the scheduled ETAs for every subsequent stop identically.
• Limitations & Rules:
  • Nodes are structurally shifted sequentially from the first ASSIGNED node (or a specific designated node inside the route tracker). Because routing engine drive-time calculations govern the transits between nodes dynamically, pushing a stop a full hour forward might alter drive times if traffic patterns differ drastically an hour later.
  • A manually modified timestamp cannot be placed sequentially before the chronological timestamp of its heading node.
  • Only ASSIGNED stops can be moved. Attempting to shift COMPLETED or IN_SERVICE nodes will throw an error.

Cancellations & Data Purging

These actions clean up operational constraints dynamically directly in the system.

Cancel Bookings

Provide a safety valve to securely cancel workflows when real-world logistics (such as inventory shortages) prevent execution.

• Action Name: invalidate_bookings
• Use Case: A customer calls support to completely cancel their order, or the warehouse reports that the order's items are out of stock and cannot be fulfilled today. This performs a soft-deletion of the bookings.
• Limitations & Rules:
  • The booking state is flipped natively to NEW and flagged as is_invalidated.
  • If the booking was currently attached to an active route, it is ripped out immediately alongside its attached nodes, and the remainder of the vehicle's route is computationally rescheduled in place. No constraints are validated.

Mark Vehicles Unavailable

Ensure operations aren't routed to inactive vehicles while maintaining safe historical logs of the vehicle's existence.

• Action Name: invalidate_vehicles
• Use Case: A vehicle broke down before their shift started, or a contractor called in sick, rendering the unit permanently unusable for the day. This performs a soft-deletion of the vehicle.
• Limitations & Rules:
  • By default, this action unassigns all related nodes. Enabling remove_point_nodes will ensure all assigned nodes strictly of the POINT type are permanently deleted from the database alongside the invalidation.
  • A vehicle cannot be invalidated if it has already embarked and possesses live lat/long coordinates, or if it has already partially completed a segment of an assigned booking.

Hard-Delete Vehicles

Wipe faulty testing data or corrupted setup states cleanly before running production configurations.

• Action Name: delete_vehicles
• Use Case: A planner accidentally clicked 'Create' twice or imported a faulty setup payload containing phantom vehicles that must be wiped entirely from the database before routes are calculated.
• Limitations & Rules:
  • Similar to validations, you strictly cannot delete a vehicle that has assigned nodes possessing statuses indicating they are currently active: ASSIGNED or IN_SERVICE.