Connector Design

As outlined in the Data & Delivery specifications, the job JSON schema contains all the information needed for Bettermile products like Better Route or Better Tracking. This page discusses when the tenant's connector logic should transmit which fragment of a job to the Bettermile Data Gateway (DGW).

Typical phases of data transmission

  1. “Master Data” for a delivery or pickup becomes available in the tenant's core system, typically when a label is digitally generated and a unique identifier is assigned. This is the earliest possible point in time to send initial job data as pre-advice information. Crucial properties like contact.address should be defined, but also other information like services or contact.timeFrames can be sent with the pre-advice data. Bettermile stores pre-advice/master data for up to 30 days, to be combined with assignment data sent on the actual day of delivery or pickup.
  2. Assignments of jobs to a specific driver or route become final. This typically happens in the destination depot while the driver is loading and scans the parcels for manifest or verification purpose. We recommend to send the assignment data with low latency to the Bettermile DGW, because the driver is about to start his tour and wants to log on to Bettermile App and requests an initial sequence calculation. At this point in time these aspects are crucial:
    • Ensure master data has been provided for each assigned job id. If the master data has changed since the (optional) pre-advice transmission, an update must be sent together with the assignment. If there was no pre-advice transmission of this job beforehand, it must be sent now together with the assignment data.
    • The delivery assignments the tenant connector transmits should reflect exactly what the driver has loaded into his delivery vehicle. Otherwise the drivers' waypoint sequence will be inconsistent with the jobs/tasks to perform. If drivers of different routes exchanges parcels last minute, the tenant system and connector must transmit an update of the assignment immediately. The delivery will be assigned to the driver/route with the latest “created” timestamp. It is also possible to simply revoke an assignment by sending an unassignment.
    • Pickup assignments should be transmitted as well, before the driver loads the initial Better Route sequence for his tour/route in order to consider those jobs in the initial sequence optimization.
  3. After the driver left the depot and started driving according to the optimised sequence of Better Route waypoints, the connector will typically send this information:
    • StatusChanges: confirmation from the tenant's core system that a job/task has been completed. For the best user experience, the status change data should be transmitted with the shortest possible latency.
    • Additional pickup assignments (with job master data included). These new pickup locations will be added at an appropriate position to the existing drivers sequence.

The details of the connector processes need to be considered for each tenant individually, since the IT core system or even the operational processes are different in each country.

Typical Connector Process Setups

Simple setup

This is the minimum required setup in order to be able to use Bettermile products with a tenant's core system. It is suitable as a first step in an integration pilot. The concept of the simple setup is to deliver the minimal required parcel data in one phase, shortly before the data is required by Better Route, when a driver requests the initial sequence for his route. This ensures that data is transferred by the connector as “up to date” as it can be. The data is typically taken from a drivers manifest, when the manifest is being closed or from a loading/verification scan by the driver, before she starts the delivery tour.

Full dynamic setup

This setup is required for tenants with high parcel volumes and advanced feature support. The job data needs to be processed and transferred in three phases / processes as outlined above:

  1. The pre-advice process needs to send all the master data as in the simple setup (without the assignment information). This can be as early as the parcels label or ID is created (e.g. for a pickup) or when the parcels are physically scanned for the first time by the tenant's system. The latest point in time is about 2 hours before the assignment process typically starts. The connector needs to track the last modification timestamp of a jobs source data record and transmit an update job object to DGW, whenever the source data changes. This is true until a job is flagged as done in the tenant's system (see phase 3).
  2. The actual assignment of a job to a driver/route/vehicle is typically happening after a parcel has been scanned in the destination depot for manifest or “out for delivery” status. When transmitting an assignment to DGW, this connector process must ensure that the master data (phase 1) has been transmitted before. Also, if there was an update of a jobs master data (specifically address data) in the tenant's core system, the connector process has to make sure the latest version is transmitted to DGW. In case the master data is up to date the assignment job fragment looks like this:
    Copy
    Copied
    {
    "id" : "54365964-xyz",      // job.id references the jobs  master data
    "date" : "2021-12-07",      // actual delivery/pickup date. "Overwrites" estimated date send in the master data earlier
    "source" : "assignment",    // see D&D description
    "depot" : "ORC",            // same depot id as in master data
    "assignment" : {            // the assignment to a specific driver/route/etc
      "scantime" : "2021-12-06T17:25:51.443-08:00",
      "properties" : {
      "route" : "4711"          // the actual assignment key value pair
    }
 }
  3. Transferring status changes for all assigned jobs until a job is done. Bettermile does not require job status changes before a job has an assignment for the current date. This connector process should aim for very low latency.
    Copy
    Copied
    {
  "id": "54365964-xyz",
  "date": "2022-01-08",
  "source": "scan",
  "depot": "ORC",
  "created": "2022-01-08T10:24:40+01:00",
  "statusChanges": [
    {
      "state": "processed",
      "timestamp": "2022-01-08T10:23:09-08:00",
      "outcome": "success"
    }
  ]
}

Questions to be considered in connector process design

While basic mapping of master data might seem trivial, there are a number of more complex aspects to be discussed and decided in the conceptualisation phase:

  • What is a suitable ID from the tenant's system to be used as unique job ID?
  • Which job types are required? (E.g. one or multiple types of pickup/collection).
  • What are the appropriate triggers for the connector to send master and assignment data?
  • What changes typically occur while the driver is on the delivery tour?
  • What might be different for international / import parcels?
  • What other tenant-specific edge cases need to be covered by the connector logic?
  • How to ensure monitoring & transaction safe recovery of connector processes?