Introduction

A Dispatch is a generic construct that represents the movement of the resources (eg. operator, vehicle) to multiple locations to perform pre-defined objectives at each location. Within a Dispatch, there are a set of tasks that the field operator needs to perform.

We can also say that the manifestation of the intent to move goods from or to a location(s) in order to perform a unit of action, i.e., a task or set of tasks is Dispatch.

The Platform Dispatch Service is to be built as a component of the OS1 Platform. The Dispatch Service provides abstract models, interfaces, and event stores for managing and monitoring the lifecycle of a dispatch and the associated objectives and jobs.

19201920

Lifecycle of a Dispatch

The Dispatch Lifecycle defines a set of states through which a Dispatch proceeds as it develops.

The platform provides a default of five states for a Dispatch:

  • Initiated: The Dispatch is being prepared.
  • Assigned: The required Participants have been assigned to the Dispatch.
  • In-Progress: Signifies that the dispatch is currently being processed by the Participants.
  • Pending Closure: The dispatch is ready for any required reconciliation and custody transfer.
  • Closed: The custody ledger of the dispatch is reconciled and the dispatch has been completed.
19201920

Creating a Dispatch

To create a new dispatch, you need to consider the following components:

  • Creating an empty dispatch
  • Adding jobs to a dispatch
  • Allocating resources to a dispatch
19201920

The Dispatch Service provides endpoints to create an empty dispatch. You can add jobs to the dispatch either in bulk (e.g. via the batching system) or one at a time (manually). Jobs can also be removed from an existing dispatch.

The Dispatch service also provides endpoints to allocate participants and resources to a Dispatch. All locations and workflows are provided as reference IDs in a Job.

To create a Dispatch, call the Create a new dispatch endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating a Dispatch:

{
    "dispatchRef" : "dispatchRef:test2",
    "dispatchTypeId" : "lmtest:87b30cf4-115a-50cb-8cc4-48e305ad5f04"
}

The Dispatch Service fetches the corresponding workflow data and location data from respective services. The Dispatch Service further validates the workflows and whether the required input data has been provided for the execution of the workflows.

The dispatch service doesn't take care of a few things:

  • It doesn't check the Dispatch execution feasibility in terms of the number of jobs added, the distance between locations, the load to be carried, Dispatch execution time, etc.
  • It also doesn't check if the allocated resources exceed or fall short of the actual resource requirement.

All such limitations, if any, should be computed/determined before adding jobs to a Dispatch by applications or services that are external to Platform Dispatch Service.

Pre-processing a Dispatch

After creating a Dispatch and allocating resources to it, the Dispatch is ready to publish. Publishing a Dispatch is triggers pre-processing of the Dispatch which includes the following:

  • Extract all of the reference IDs for locations, contacts, and workflows to actual data from the respective services.
  • Extract the objectives from the jobs and group them by location, time slot, and customer.
  • Merge one or more grouped objectives for a given location/time-slot/customer at the workflow level if they have the same workflow associated with them and the workflow id designed for grouping.

The pre-processing provides an option to call an external route optimization engine.

Track a Dispatch

After creation, the Dispatch is transferred to the Dispatch App installed on authenticated mobile devices of Users allocated to the Dispatch.

Dispatch execution functions through a standard SDK for mobile devices comprising the following modules:

  • Dispatch Module
  • Workflow Execution Module
  • Status Update Module
  • Incoming Notification Handler
  • Location Tracking

Objective status updates flow back as objective events to the Dispatch Service through API calls made by the SDK and they are stored in the Objective Events Store.

Objective and Dispatch events are translated into Job events and stored in the Job Events Store.

Location Tracking

Motion Tracking System (MTS) Service provides a way to capture streaming location data from GPS-enabled devices (e.g., mobile devices, vehicle GPS modules, etc.). In the case of the dispatch mobile app, the Location Tracking module of the SDK provides a configurable way to capture and stream location data from the mobile device to the MTS service, without any user intervention.

The Location Tracking module captures the following events along with location data:

  • Objective status change event
  • Device health data & user intervention on device settings (e.g., battery, mobile data connectivity, GPS enabled/disabled, etc).

MTS Service provides APIs and Pub-Sub mechanisms for continuous tracking of device location or geofence entry and exit events.

Attributes of a Dispatch

Attributes of a Dispatch are divided into one of the following categories:

  • Base: These are the attributes mandated by the platform for the Objective. Some of these attributes are mandatory.
  • Custom: These are the attributes that the Tenant defines for the Objectives, to enhance their usability. Tenants can define custom validations, and specify whether they are indexed or non-indexed.

Attribute Name

Category

Purpose

Data Type Expected

Tenant ID

Base

The ID of the tenant to whose realm the dispatch belongs.

UUID

Dispatch ID

Base

A system-generated unique ID for the dispatch. This is maintained for every Dispatch created by the platform.

UUID

Dispatch Version Number

Base

The version number created by the platform at the time of the creation of dispatch. This version number is communicated to the Generic Dispatch Field app, and any change done to the dispatch will see a change in the version number.

VarChar

External Dispatch ID
(Optional)

Base

This field allows Tenants to give their Dispatch ID that may be generated by their batching & routing system, and this may be used for cross-reference and debugging.

VarChar

Participant List

Base

A list of Participants that execute the dispatch. This list can involve - User, Vehicles, Devices, or any other types of Participants defined by the Tenant.

The list consists of pairs of Participant Types and Participant IDs.

Example:
[{ participantID: 1, participantType:”User”}, { participantID: 45, participantType: ”Vehicle”}]

A minimum of ONE User-type Participant is required to set the dispatch to “ASSIGNED” state, and then to “IN-PROGRESS” state.

Array of JSON

Job List^
(Optional)

Base

This field contains a list of Job IDs.
Required to set the Dispatch to “IN-PROGRESS” state.

Array of JSON

Custom Attributes 1-to-n (Indexed)

Custom

Custom attributes for a Dispatch with indexing. If required, the tenant is able to configure validations for these attributes.

Key-Value

Custom Attributes 1-to-n (Non-Indexed)

Custom

Custom attributes for a Dispatch without indexing. If required, the Tenant is able to configure validations for these attributes.

Key-Value

To create a Custom Dispatch Attribute, call the Post attribute config for dispatch endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating a Custom Dispatch Attribute:

{
  "attributes": [
        {
            "dataType": "string",
            "name": "clientId",
            "description": "ID of client",
            "defaultValue": {
                "clientId": ""
            },
            "validation": {
                "range": {
                    "min": 4,
                    "max": 64
                },
                "required": false
            }
        },
        {
            "dataType": "array",
            "name": "jobTags",
            "description": "Job Tags",
            "tags": [],
            "validation": {
                "required": true
            }
        },
        {
            "dataType": "string",
            "name": "paymentType",
            "description": "payment method",
            "tags": [],
            "defaultValue": {
                "paymentType": ""
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 64
                },
                "required": true
            }
        },
        {
            "dataType": "number",
            "name": "amount",
            "description": "payment amount",
            "tags": [],
            "defaultValue": {
                "amount": 0
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 10000000
                },
                "required": true
            }
        },
        {
            "dataType": "number",
            "name": "weight",
            "description": "weight",
            "tags": [],
            "defaultValue": {
                "weight": 0
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 100000
                },
                "required": false
            }
        },
        {
            "dataType": "number",
            "name": "volume",
            "description": "volume",
            "tags": [],
            "defaultValue": {
                "volume": 0
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 10000000
                },
                "required": false
            }
        },
        {
            "dataType": "number",
            "name": "expectedDate",
            "description": "expected date",
            "tags": [],
            "defaultValue": {
                "expectedDate": 0
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 10
                },
                "required": false
            }
        },
        {
            "name": "priority",
            "description": "priority",
            "tags": [],
            "dataType": "string",
            "indexed": false,
            "defaultValue": {
                "priority": ""
            },
            "validation": {
                "range": {
                    "min": 1,
                    "max": 32
                },
                "required": false
            }
        }
    ]
}

Custody in Dispatch

Objective workflows can include a physical transfer of inventory. For example, the Field Engineer must pick up a shipment and then deliver it to successfully complete the workflow. Or might also need to capture cash or some kind of document(s) as a part of the workflow.

It is important to keep a general ledger book-keeping of what inventory is picked or delivered at any point of an active dispatch. This introduces the concept of Custody.

Custody is an implicit mechanism to keep a ledger or record of what inventory (physical objects) are in the custody of an operator for a given dispatch. Dispatch always starts with zero inventory in custody and also should end with zero inventory in custody.

A Dispatch can only be closed when the general ledger tallies to zero.

Why is Custody required?

Custody transfer is the mechanism to track the transfer of ownership. Custody implies knowing who has what, when, and where. It is a chronological documentation of all parties that came into contact with a shipment, and a history of all trades.

COLLECT (Execution Task) is when the inventory transfer is Receivables (In) and DROP-OFF (Execution Task) is when the inventory transfer is Payables (Out).


Did this page help you?