Skip to main content

Live Operations

This guide covers the workflow for managing live, dynamic operations where orders are received and assigned in real-time (On-Demand) or for Just-In-Time (JIT) scenarios. It details ad-hoc order insertion, dynamic vehicle management, and split assignment configurations.

Overview​

In dynamic operations, orders are received in real-time, and vehicle availability can change unexpectedly (e.g., due to accidents or breakdowns). The API supports these scenarios by allowing seamless updates to running simulations.

Ad-hoc Order Upload​

Integration Workflow Diagram​

The following diagram illustrates the interaction flow for an API consumer managing live operations:

Ad-hoc Order Upload​

To insert orders into an active simulation without restarting it, use the POST endpoint with the simulation_id of the running simulation.

If you need to create a new simulation (e.g., for initial planning or to run a scenario based on a template), you should use simulation_clone_parameters instead of simulation_id. This allows you to leverage pre-configured templates. See How is a Simulation Identified? for details on when a new simulation is created vs reused.

For comprehensive details on booking parameters and templates, refer to:

Request​

Upload ad-hoc bookings
POST {base_url}/api/v2/microservices/logisticsapi

{
    "simulation_id": {{simulation_id}},
    "upload_strategy": "keep_assigned", 
    "immediate_calculation": false, 
    "bookings": [
        {
            "uid": "new_adhoc_order_001",
            "demand": { "parcel": 1 },
            "pickup_location_lat": 13.81722301,
            "pickup_location_lon": 100.5124416,
            "min_pickup_time": "{{current_time_iso}}",
            "max_pickup_time": "{{future_time_iso}}",
            "pickup_service_time": 300,
            "dropoff_location_lat": 13.8353723,
            "dropoff_location_lon": 100.5732801,
            "min_dropoff_time": "{{current_time_iso}}",
            "max_dropoff_time": "{{future_time_iso}}",
            "dropoff_service_time": 300
        }
    ]
}
  • simulation_id: The ID of the currently running simulation. (Or use simulation_clone_parameters to create a new one).
  • upload_strategy: Use "keep_assigned" to ensure existing routes are preserved while new orders are added.
  • immediate_calculation: Set to false. Since we are using continuous on-demand processors for live operations, we do not need to trigger a calculation immediately upon upload; the processor will pick up the new orders automatically.

Managing Vehicle Availability​

For scenarios where a vehicle becomes unavailable (e.g., due to an accident or breakdown) or needs to be reintroduced, you can dynamically update its status using the vehicle_use microservice endpoint.

For comprehensive details on this endpoint, refer to:

Enabling or Disabling a Vehicle​

To change the availability of a vehicle in the active simulation:

Enable/Disable Vehicle
POST {base_url}/api/v2/microservices/vehicle_use

{
    "simulation_id": {{simulation_id}},
    "agent_type": "vehicle",
    "message_type": "vehicle_use",
    "agent_id": "{{vehicle_uid}}", 
    "data": {
        "vehicle_id": {{vehicle_id}},
        "action": "disable" 
    },
    "current_sim_ts": "{{current_timestamp}}",
    "transmit_to_websocket": false
}
  • action: Use "disable" to remove the vehicle from new assignments, or "enable" to make it available again.
  • agent_id: The UID of the vehicle agent, which must be unique within the simulation (often a UUID or string identifier). Note that vehicle_id is a globally unique integer identifier across the system.
  • vehicle_id: The integer ID of the vehicle to update.
  • simulation_id: The ID of the running simulation.

Retrieving Assigned Routes​

There are three valid options to retrieve the assigned route or manifest for a vehicle, depending on the detail level and use case.

To get the full route (sequence of stops) for a vehicle, use the node endpoint filtered by assigned_vehicle.

Get Vehicle Route (Nodes)
GET {base_url}/api/v2/node?simulation={{simulation_id}}&assigned_vehicle={{vehicle_id}}&ordering=scheduled_ts

This returns all nodes (pickups and dropoffs) assigned to the vehicle, ordered by time. This is the best way to visualize the full path.

Option 2: Using the Assigned Nodes API​

For live operations, drivers and operators often focus on upcoming stops. The assigned_nodes endpoint provides a targeted view of the remaining route, excluding completed stops.

Get Upcoming Route
GET {base_url}/api/v2/vehicle/{{vehicle_id}}/assigned_nodes

Option 3: Using the Bookings API​

To retrieve the full details of the orders (bookings) currently assigned to a vehicle (e.g., for generating a manifest with customer details), query the booking endpoint. You can filter for bookings where any of their nodes are assigned to the target vehicle.

Get Vehicle Manifest (Bookings)
GET {base_url}/api/v2/booking?simulation={{simulation_id}}&nodes__assigned_vehicle={{vehicle_id}}

This returns the list of Booking objects. Note that a single booking typically results in two stops (nodes) in the vehicle's route.

Sending Vehicle GPS Position​

To simulate live vehicle movement or integrate with a real telemetry system, you must send GPS updates to a dedicated ingestion endpoint. This triggers the map-matching and simulation update process.

Endpoint: POST / Staging URL: https://mobile-gpslog.d.gcdev.swatrider.com Production URL: https://mobile-gpslog.d.gcprod.swatrider.com (Verify with your project settings)

Payload Structure​

The payload allows sending a batch of GPS points (though typically done in small batches or individually for real-time).

GPS Update Payload
{
  "meta": {
    "vehicle": {
      "id": 12345
    }
  },
  "uid": "device_unique_id_001",
  "data": [
    {
      "direction": 0,
      "speed": 15,
      "coordinateAccuracy": {
        "horizontal": 5,
        "vertical": 5
      },
      "timestamp": 1678886400.123,
      "directionAccuracy": 0,
      "coordinate": {
        "longitude": 103.851959,
        "latitude": 1.290270
      }
    }
  ]
}

Split Assignment with Multiple Processors​

For complex operations, you may want to split the assignment logic across multiple processors. For instance, you might want one processor to handle "express" orders using a specific fleet of vehicles, while another processor handles "standard" orders. This allows for parallel processing and specialized optimization rules.

This is achieved by configuring Simulation Processors with specific filtering expressions for both bookings and vehicles.

Configuring Simulation Processors​

You can create or update a SimulationProcessor to target specific subsets of data.

Create/Update Simulation Processor
POST {base_url}/api/v2/simulationprocessor

{
    "simulation": "/api/v2/simulation/{{simulation_id}}",
    "processor_type": "ondemand",
    "processor_lifecycle_type": "continuous",
    "bookings_filter_expression": {
        "groups__contains": "express_orders"
    },
    "vehicles_filter_expression": {
        "operations_location_groups__code": "express_fleet" 
    },
    "vehicle_selection_in_use": true
}

Key Components​

  • processor_type: "ondemand": Sets the processor mode to "ondemand", optimized for continuous, real-time assignment.
  • processor_lifecycle_type: "continuous": Ensures the processor keeps running and listening for new matching orders, which is standard for live operations.
  • bookings_filter_expression: A JSON object defining criteria to filter which bookings this processor handles. It supports standard field lookups.
    • Simple Example: {"groups__contains": "express_orders"} processes only orders in the "express_orders" group.
    • Complex Example: 
      {
        "state__in": ["prepared"],
        "pickup_operations_location__group__code": "S50"
      }
      This configuration filters for bookings that are currently in the prepared state AND originate from a pickup location that belongs to the operations group with code S50. This is useful for geographically segmenting orders based on their pickup zones.
  • vehicles_filter_expression: Defines which vehicles are available to this processor using standard relation lookups.
    • Example: {"operations_location_groups__code": "express_fleet"} uses only vehicles associated with the "express_fleet" operations location group.

Filter Syntax Reference​

  • Dictionary: Means AND.
  • List: Means OR.
  • ~and / ~or: Use these keywords with a conditions list for explicit logical operations.
  • ~not: Use this keyword with a condition to negate it.
  • - Prefix (on Key): Means using a value without a key.
  • @ Prefix (on Value): Means a reference to another field.
JSON Field Limitations

Filtering directly on JSON fields (like data or even labels) is not supported in these expressions. You must use standard model fields or relationships, such as groups for bookings or operations_location_groups for vehicles.

Configuring Vehicles for Filtering​

Since you cannot filter vehicles by arbitrary data or labels, the recommended approach is to use Operations Location Groups.

  1. Create an Operations Area/Group: Define an OperationsLocationGroup (e.g., with code express_fleet).
  2. Assign to Vehicles: When creating or updating vehicles, link them to this group using the operations_location_groups field.
  3. Filter in Processor: Use the operations_location_groups__code lookup in your vehicles_filter_expression to target these vehicles.

By setting up multiple processors with mutually exclusive (or overlapping) filters, you can tailor different optimization strategies for different segments of your operation within the same simulation.

Simulation Templates and Processors​

When a new simulation is created from a template (using simulation_clone_parameters), all associated SimulationProcessors are cloned and configured for the new simulation instance.

For more details on simulation templates, see Simulation Templates.

Optimization Parameters for On-Demand​

The behavior of the ondemand processor is controlled primarily by vehicle selection rules and the underlying logistics engine configuration.

1. Vehicle Selection Rules (Processor Fields)​

These attributes on the SimulationProcessor object itself determine which vehicles are candidates for assignment:

  • vehicle_selection_in_use (boolean, default: true): If true, restricts selection to vehicles marked as in_use.
  • vehicle_selection_in_service (boolean, default: true): If true, restricts selection to vehicles currently within their operating shift (start_time to end_time).
  • vehicle_selection_by_emptiness (boolean, default: false): If true, only selects vehicles that are currently empty and have no assigned nodes.
  • gps_timeout (integer, optional): If set, excludes vehicles that haven't reported GPS data within the specified number of seconds (e.g., to avoid assigning to offline vehicles).

2. Core Logistics Parameters​

Since the on-demand processor delegates the core routing and scheduling to the Logistics Engine, it also relies on the Logistics Calculation Parameters. These are defined in a separate LogisticsCalculationParameters object linked to the processor via the calculation_parameters_logistics field. They control:

  • Cost Weights: Balancing distance, time, and service costs.
  • Constraints: Max walking distances, waiting times, and capacity rules.
  • Solver Settings: Time limits and search strategies.

Ensure your processor is linked to an appropriate LogisticsCalculationParameters instance to fine-tune the optimization behavior.

Parameter Copying and Time Adjustments​

The cloning process ensures that the processors are ready for the new time window while preserving logic from the template:

  1. General Processor Settings: Attributes like processor_type and processor_lifecycle_type are copied directly. The processor's start_time and end_time are shifted by the difference between the new simulation's start time and the template's start time.
  2. On-Demand Parameters: The calculation_parameters_ondemand are copied as-is. This means static configuration settings (e.g., cost weights, logic flags) remain unchanged.
  3. Filter Expressions (Smart Adjustment):
    • vehicles_filter_expression: The system recursively scans this JSON for values associated with keys like start_time and end_time. If found, these timestamps are time-shifted to match the new simulation window.
    • bookings_filter_expression: Similarly, keys related to booking times (min_pickup_time, max_pickup_time, min_dropoff_time, max_dropoff_time) are identified and their values are adjusted by the time shift.
  4. Regenerator Settings: If using a regenerator processor, calculation_parameters_regenerator is also recursively adjusted for pickup and dropoff time windows.

This automatic adjustment allows you to define time-relative logic in your templates (e.g., "only pick up vehicles working this morning") that remains valid and correct when instantiated for a future date.