Skip to main content

Plan, Assign and Track orders with Self-improving routes (Beta)

Introduction

The lifecycle of last mile fulfillment of orders includes the Plan, Assign and Track stages.

The 'Plan' stage involves batching and sequencing orders for available drivers. The 'Assign' stage involves finding the specific driver to fulfill the order based on live location, drive time to the order destination, profile data, etc and dispatching the order for fulfillment. The 'Track' stage involves live tracking the order to fulfillment and sharing live progress with your operations team and end customers. Further, tracking requires your teams to proactively be informed about orders at risk so they can investigate and take remediating action to improve your end customer's experience and logistics efficiency.

HyperTrack's 'Self-improving Routes' feature enables you do do all of this and this guide will walk you through how you can use the feature.

Getting started

1. Setup Operations Groups

The first step to get started is to setup the planning parameters for your operation. Planning of orders in HyperTrack is scoped to individual 'Operations Groups'. Operations groups represent the level at which orders and drivers are grouped for assignment.

For example, in different contexts for different businesses, operations group can be defined at a store, warehouse or even city level. The fields required to setup your operations groups are described below.

NameRequiredDescriptionTypeExamples
Operations Group LabelrequiredOrder Planning for a business is scoped to entities like warehouses, hubs, regions etc. This parameter specifies the entity your business uses as operations groups.string"store"
Operations Group HandlerequiredThis is the unique identifier for a specific operations group that manages ordersstring"ny_grocery_store"
Operations Group Homerequired for dispatches from a warehouseThis is the location of the operations groupGeoJson Point
ModerequiredThis specifies if how operation primatily plans orders. on_demand is for operations that primarily assign to the nearest available driver without any batching. pool is for operations that batch and sequence orders for the nearest available driver. scheduled is for operations that batch and sequence orders based on driver schedulesENUMon_demand OR scheduled OR pool
Route Start LocationrequiredThis specifies the location at which an order for the specific operations group will startENUMdriver_home OR ops_group_home OR live_location
Default shift start timerequired for scheduledThis specifies the default shift start time for driversTime string08:00:00
Default shift lengthrequired for scheduledThis specifies default driver shift length in minutes for planningINT480
Route capacityoptionalThis is the maximum order quantity a driver can fulfill on a single route. When ingesting orders, we also accept the capacity used by the order which will need to be in the same unit as this parameter for collect results. For instance if you prefer your drivers do not fulfill more than 5 orders in a route and route capacity can be 5 and each order's used capacity can be 1.INT5
Route maximum distanceoptionalThis is the maximum distance in miles a single route can have.INT30
Objective FunctionrequiredThis specifies the objective function for route optimizationENUMminimise_time OR minimise_distance OR maximise_fairness OR maximise_utilisation
Product TypesoptionalThis specifies all the product types the operations groups can fulfill. Orders and drivers associated with an operations group must have one of the product types that can be fulfilled by the operations groupstring[]['alcohol', 'ice-cream', 'grocery']
Route completion typerequiredThis specifies the rules for how a route should be completed.ENUMmanual OR end_at_last_order OR return_to_start_location. Default is end_at_last_order.

Please contact your HyperTrack support team to setup.

2. Setup Drivers and their availability

If you are using the HyperTrack Visits app as your driver app, you will need to invite your drivers and have them install Visits app to get the Device ID as described here.

The HyperTrack Drivers API lets you ingest and manage your drivers. You can POST to /drivers with the parameters below to get started.

ParameterRequiredDescriptionTypeRequired
Driver HandlerequiredThis is the unique identifier for a driver in your system like the driver name or idstringdriver_id_1
Operations Group HandlerequiredThis is the identifier of the operations group to which this driver is associatedstringny_grocery_store
ProfileoptionalThis specifies profile parameters for the driverdictvehicle_type:2-wheeler
Device IDoptional for creationThis is the ID of the device on which the driver app including the HyperTrack SDK is installed. At a time, a driver can only be associated with one device. However the historical values of the device are stored in case the driver changes the device.string00000000-1B3F-4957-AAA1-5E86A266ABA9
Product TypesoptionalThese are the product types that the driver can fulfill. These must be a subset of the product types enabled for the operations group to which the driver is associatedstring[]['ice-cream', 'grocery']
HomeoptionalThis is the home destination of the driver which will be used in case the driver is expcected to start routes from homeGeoJSON Point
ScheduleoptionalThis describes the default work schedule of the driver by day.object[Date string]2022-04-11
Unavailable onoptionalThis is to define temporary leaves the driver might take that need to be managed.array[Date string]["2022-07-12", "2022-07-13", "2022-07-14"]

Drivers are considered for planning depending on the planning mode of the operations group. For ops groups that have scheduled mode, drivers will be considered based on the driver schedules in the driver profile described in the table above. This is used for planning orders in the future (like next day orders) where schdeules are more important as opposed to live location at the time of planning.

For ops groups that have on_demand or pool mode, driver availability is decided using the live availability parameter as described here. Drivers in the available state will be considered for planning. If an available driver is currently on a route, that will be taken into account when they are included in planning. When drivers are no longer accepting new orders, they should be made unavailable as described here.

3. Order Planning and Assignment

This step provides the orders to be planned for last mile fulfillment and batches and sequences them for the relevant drivers who are available based on the driver setup parameters defined.

Note as a pre-requisite for order planning you will need to setup webhooks as describe here to receive planning updates.

For orders in an operations group, HyperTrack will auto-include drivers who are available for planning. To batch and sequence orders for the available fleet, you will need to POST to the /orders endpoint with the following parameters:

ParameterRequiredDescriptionTypeExamples
intentrequiredThis specifies which HyperTrack feature you would like to use for the order.ENUM stringself_improving
ops_group_handlerequiredThis specifies the operations group for which this order is being plannedstringny_grocery_store
ordersrequiredArray of orders that need to be plannedArraysee sample API docs here
order.destinationrequiredObject to define the order destinationObject
order.destination.geometryrequired to define the order destination geofence geometry. You can also use a Geofence id if you are managing Geofences separately through HyperTrack.GeoJSON Point
Order.destination.addressoptionalThis provides the text address of the order destinationstring
Order.scheduled_afteroptionalThis specifies the start of the time window within which an order must start fulfillmentDatetime string2022-12-07T18:24:00.000Z
Order.scheduled_atoptionalThis specifies the end of the time window within which an order must start fulfillmentDatetime string2022-12-07T19:24:00.000Z
Order.expected_service_timerequiredThis specifies expected service time for the order in seconds. Default value is 300sint300
Order.metadataoptionalmetadata related to the orderdict
Order.capacity_usedoptionalThis specifies how much of fulfillment capacity will be utilized by this order. It is used to constrain the number of orders in a single routeint1
Order.typeoptionalThis can be used for delivery or pick up orders. The default value is nullENUM stringpickup OR drop
Order.product_typeoptionalThis specifies product type of the order. Only drivers who can service this product type will be considered for assignment and optimizationstring[]['grocery', 'alcohol']

Order planning is an async process. A successful planning request will receive a response with a message indicating order planning has been initiated. When planning is completed you will receive a order_planning_completed webhook after which you can fetch your routes from /orders/routes with the ops group handle to get the routes planned for it.

Each route will have a route_id which can be used to dispatch it for live tracking.

4. Dispatch route and start tracking

To start live tracking of the route planned through HyperTrack make the following API call: POST /orders/{route_id}/dispatch

5. Track the orders dispatched and share live tracking with customers

Live tracking of an ongoing route can be viewed on the map in your HyperTrack Dashboard. Each order has a shareable URL that can be sent to the customer to allow them to view the live location of the driver who is on the way to deliver their package. To learn more please visit this guide.

Questions?

For questions or comments about orders view, please do not hesitate to contact us.