Dispatch Service

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 dispatch service docid\ kjdpcl9yep5kbek1isxku and the associated jobs and objectives docid\ bewqlcaf54oqv9pmeonxw 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 this signifies that the dispatch is currently being processed by the participants pending closure the dispatch is ready for any required reconciliation and dispatch service docid\ kjdpcl9yep5kbek1isxku closed the custody ledger of the dispatch is reconciled and the dispatch has been completed 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 string dispatch id base a system generated unique id for the dispatch this is maintained for every dispatch created by the platform uuid dispatch reference 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 (optional) base a list of participants that execute the dispatch this list can involve users, vehicles, devices, or any other types of participants defined by the tenant the participant list can consist of either a list of participantids or the complete details of participants mentioned in graphql 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” staate 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 for the dispatch endpoint request bodies are specified in json format the following examples show a request body for creating a custom dispatch attribute member description validation data type attributes dispatch/job type attributes configuration minitems 1 name name of the attribute minlength 1 maxlength 32 pattern ^\[a za z]{1,32}$ string description (optional) description of the attribute minlength 0 maxlength 256 string datatype data type of the attribute valid values string, number, boolean, object, array string indexed default false boolean validation specifies all the validations to be performed on an attribute, when a participant of this type is created/updated range field to specify the range that the attribute value must lie in the case of the "string" datatype, the range will be the length of the string value this validation allowed only for string and number type of attributes number regex field to specify the regex pattern that the value of an attribute must match this validation is allowed only for string type of attributes minlength 1 maxlength 512 string valueoneof field to specify enum values for an attribute list of valueoneof should be homogeneous minitems 1 string required field to specify if the value for the attribute is mandatory or not if true, the value must be provided default false boolean creating 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 } } ] } 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 the dispatch service provides endpoints to create an empty dispatch you can add jobs and objectives docid\ bewqlcaf54oqv9pmeonxw 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 new dispatch endpoint request bodies are specified in json format the following examples show a request body for creating a dispatch member description validation data type dispatchref external dispatch reference minlength 4 maxlength 64 string dispatchtypeid dispatch type id minlength 4 maxlength 64 string { "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 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 jobs and objectives docid\ bewqlcaf54oqv9pmeonxw 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 custody in dispatch objective workflows can include a physical transfer of inventory for example, the field executive must pick up a shipment and then deliver it to successfully complete the workflow or you might also need to capture cash or some kind of document(s) as a part of the workflow keeping a general ledger book keeping of what inventory is picked or delivered at any point of an active dispatch is important this introduces the concept of custody custody is an implicit mechanism to keep a ledger or record of what inventory (physical objects) is 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) graphql queries os1 app developers can use graphql dispatch queries docid 8amtzimlfthvelo0uij1l and jobs using a single api