Jobs and Objectives

11min

Introduction to Jobs
A Job is the sequence of workflows to be executed to complete a single leg of an expected path of an order (point to point). An expected path is a path/route for the movement of the Participants and/or Containers to fulfill an order. Each segment of the route is referred to as a Job (Legs).
Examples:
For the order ‘Pickup shipment from location A and deliver it to location B’, the expected path could have three legs/jobs:
﻿
For the order ‘Go to location B and install the refrigerator, the expected path could have just one leg/job:
﻿
To create a Job, call the Create a new job endpoint.
Request bodies are specified in JSON format. The following examples show a request body for creating a Job:
Member
Description
Validation
Data type
jobWorkflowId*
Job workflow ID
minLength: 1
maxLength: 64
string
jobRef
(Optional)
External job reference
minLength: 1
maxLength: 64
string
objectives
(Optional)
List of all objectives within the job.
minItems: 1
﻿
objectiveRef*
Reference ID for individual objectives.
minLength: 4
maxLength: 36
string
objectives>location
(Optional)
Location can be passed as the Location ID
minLength: 1
maxLength: 64
string
location>address*
Address where the job needs to be executed.
﻿
﻿
location>geolocation>long*
The range of longitude is -180 to 180 and can be upto 6 decimal places.
pattern: ^(\+|-)?(?:180(?:(?:\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\.[0-9]{1,6})?))$
string
location>geolocation>lat*
Range of latitude is -90 to 90 and can be upto 6 decimal places.
pattern: ^(\+|-)?(?:90(?:(?:\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\.[0-9]{1,6})?))$
string
contact>ContactID
(Optional)
SDS can be passed in contact.
minLength: 1
maxLength: 64
string
contact>name*
Contact name.
﻿
string
contact>phone>countryCode*
Country code of the mobile it belongs.
pattern:  ^\+(\d{1}\-)?(\d{1,3})$
string
contact>phone>number*
Phone number of the user.
minLength: 4
maxLength: 13
string
contact>phone>isMobile*
Whether the phone is of type mobile or telephone.
﻿
boolean
contact>phone>areaCode
(Optional)
In case of type telephone, areaCode of the telephone it belongs.
pattern: ^\+(\d{1}\-)?(\d{1,3})$
string
objective>input*
﻿
﻿
﻿
containers
(Optional)
List of Containers
﻿
string
batchID
(Optional)
Batch ID
minLength: 1
maxLength: 64
string
jobTypeName
(Optional)
Job Type Name
minLength: 3
maxLength: 36
string
jobTypeId*
Job Type ID.
minLength: 4
maxLength: 64
string
_event_meta
(Optional)
Metadata.
﻿
﻿
scheduledFor
(Optional)
Time slot scheduled for the job.
﻿
﻿
scheduledFor>startDateTime*
Start Date time.
﻿
number
scheduledFor>endDateTime
(Optional)
End Date time.
﻿
number
The attributes marked with (*) are mandatory attributes.
JSON
{
    "jobWorkflowId": "jobWorkflow:e768f61e-42bf-4aa6-8ff6-5030114d4307",
    "jobTypeId": "pickuptest:44d87031-f1f7-56b8-9a47-783dc874d2b6",
    "jobRef": "jobRef:02",
    "objectives": [
        {
            "objectiveRef": "Pickup",
            "contact": {
                "name": "Worldlogistic",
                "phone": {
                    "countryCode": "+91",
                    "number": "9900889900",
                    "isMobile": true,
                    "areaCode": "+91"
                }
            },
            "location": {
                "address": {
                    "buildingNumber": "746",
                    "apartmentNumber": "1234",
                    "addressLine1": "housing board colony",
                    "addressLine2": "new housing board colony",
                    "addressLine3": "old street late",
                    "city": "pune",
                    "state": "maharashtra",
                    "zipCode": "112356",
                    "country": {
                        "code": "IND",
                        "name": "india"
                    }
                },
                "geolocation": {
                    "lat": "86.74739",
                    "long": "24.7283"
                }
            },
            "input": {
                "items": [
                    {
                        "skuId": "id1"
                    }
                ],
                "title": "title1"
            }
        }
    ]
}
{
    "jobWorkflowId": "jobWorkflow:e768f61e-42bf-4aa6-8ff6-5030114d4307",
    "jobTypeId": "pickuptest:44d87031-f1f7-56b8-9a47-783dc874d2b6",
    "jobRef": "jobRef:02",
    "objectives": [
        {
            "objectiveRef": "Pickup",
            "contact": {
                "name": "Worldlogistic",
                "phone": {
                    "countryCode": "+91",
                    "number": "9900889900",
                    "isMobile": true,
                    "areaCode": "+91"
                }
            },
            "location": {
                "address": {
                    "buildingNumber": "746",
                    "apartmentNumber": "1234",
                    "addressLine1": "housing board colony",
                    "addressLine2": "new housing board colony",
                    "addressLine3": "old street late",
                    "city": "pune",
                    "state": "maharashtra",
                    "zipCode": "112356",
                    "country": {
                        "code": "IND",
                        "name": "india"
                    }
                },
                "geolocation": {
                    "lat": "86.74739",
                    "long": "24.7283"
                }
            },
            "input": {
                "items": [
                    {
                        "skuId": "id1"
                    }
                ],
                "title": "title1"
            }
        }
    ]
}
﻿
Attributes of a Job
A job has the following attributes:
Attribute Name
Data Type Expected
Purpose
Tenant ID
UUID
The ID of the tenant to whose data domain the Job belongs.
Job ID
UUID
The system-generated ID of the Job.
Instructions (Optional)
Array of JSON
The instruction JSON schema is as follows:
1. id: Unique ID for instruction.
2. containers: List of containers associated with this instruction.
3. location: Location ID of the location where the instruction is to be performed.
4. contact: Name and contact number of the customer (a secure data ID if the real phone number is passed. Masked phone number can be passed directly).
5. timeSlot: Defines the preferred time slot for executing this instruction. Has two keys from and to which have the start & end epoch time of the time slot.
6. workflow: Workflow instance ID (Workflow instance is workflow id plus the input data for executing the workflow. The instance is stored in the Workflow service and passed as an ID here.).
7. next: Has two keys onSuccess and onFailure whose values denote the next instruction to be executed in case of current instruction success and failure respectively.
To create a custom Job Attribute, call the Post attribute config for Job endpoint.
Request bodies are specified in JSON format. The following examples show a request body for creating a custom Job Attribute:
Here's your data converted into a markdown table:
Member
Description
Validation
Data type
attributes
﻿
minItems: 1
﻿
name
Attribute name.
minLength: 1  
maxLength: 32  
pattern: ^[a-zA-Z]{1,32}$
string
description
Attribute description.
minLength: 0  maxLength: 256
string
tags
Tag to be associated with the attribute.
﻿
string
dataType
Data type.
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.
﻿
﻿
JSON
{
  "attributes": [
    {
      "name": "Job Attribute",
      "description": "Description of Job Attribute",
      "tags": [
        "job"
      ],
      "dataType": "number",
      "indexed": false,
      "defaultValue": { "no" : 10 },
      "validation": {
          "range" : {
              "min" : 1,
              "max" : 50
          },
        "required": true
      }
    }
  ]
}
{
  "attributes": [
    {
      "name": "Job Attribute",
      "description": "Description of Job Attribute",
      "tags": [
        "job"
      ],
      "dataType": "number",
      "indexed": false,
      "defaultValue": { "no" : 10 },
      "validation": {
          "range" : {
              "min" : 1,
              "max" : 50
          },
        "required": true
      }
    }
  ]
}
﻿
Objectives
An Objective is one or more execution tasks to be performed as a workflow for a Container or set of Containers at a given location.
It is possible that an objective can consist of one or more Service IDs and service IDs in turn can contain one or more Containers. For example, a warehouse pickup can have multiple service ids and associated Containers to pick up.
To complete a shipment, the operator needs to execute a sequence of Jobs (set of actions) associated with it. A Job has the following entities in it: Customer, Location, and Time Slot.
The following describes two different jobs:
Pick up shipment s1 from Location-A (between 9 AM & 10 AM) and Deliver to Location-B
Pick up shipment s2 from Location-A (between 9 AM & 10 AM) and Deliver to Location-C
If we examine these two jobs, we can see that they contain common areas such as Location-A and the Time Slot for pick-up.
Based on these common areas, we can convert these jobs into Objectives. The Objective can then be defined as a group of jobs to be performed at a particular location.
In this example 4 different jobs are converted into objectives:
Job-1: Pick up shipment s1 from Location-A (between 9 AM & 10 AM) and Deliver to Location-B
Job-2: Pick up shipment s2 from Location-A (between 9 AM & 10 AM) and Deliver to Location-C
Job-3: Pick up shipment s3 from Location-D and Deliver to Location-C
Job-4: Pick up shipment s4 from Location-A (between 3 PM & 4 PM) and Deliver it to Location-E
These jobs are now converted into Objectives based on location & time slots:
Stop
Objective(s)
Location-A
Pick up shipment s1; Pick up shipment s2
Location-B
Deliver shipment s1
Location-D
Pick up shipment s3
Location-C
Deliver shipment s2; Deliver shipment s3
Location-A
Pick up shipment s4
Location-E
Deliver shipment s4
📘 INFO
The Objectives are grouped together by the customer, location, and time slot. For simplicity of explanation, the customer part has been excluded in the above examples.
The purpose of creating Objectives is to enhance the working efficiency of operators and to eliminate areas of human errors. You can pass multiple objectives within a workflow.
Lifecycle of a Job
The platform provides a default of five states for an Objective:
Created: This state denotes that an Objective has been created.
Assigned: This state denotes that the objective has been assigned to a dispatch.
In-Progress: The state denotes that the Job is in progress. The event store can give the exact sub-state of this state.
Completed: This state denotes that the instruction list of the Job was completed by the Operator.
Canceled: This state denotes that the Job has been canceled. It simply states that the job the Operator had to perform was added to a parent job.
﻿
﻿

Member	Description	Validation	Data type
jobWorkflowId*	Job workflow ID	minLength: 1 maxLength: 64	string
jobRef (Optional)	External job reference	minLength: 1 maxLength: 64	string
objectives (Optional)	List of all objectives within the job.	minItems: 1
objectiveRef*	Reference ID for individual objectives.	minLength: 4 maxLength: 36	string
objectives>location (Optional)	Location can be passed as the Location ID	minLength: 1 maxLength: 64	string
location>address*	Address where the job needs to be executed.
location>geolocation>long*	The range of longitude is -180 to 180 and can be upto 6 decimal places.	pattern: ^(\+\|-)?(?:180(?:(?:\.0{1,6})?)\|(?:[0-9]\|[1-9][0-9]\|1[0-7][0-9])(?:(?:\.[0-9]{1,6})?))$	string
location>geolocation>lat*	Range of latitude is -90 to 90 and can be upto 6 decimal places.	pattern: ^(\+\|-)?(?:90(?:(?:\.0{1,6})?)\|(?:[0-9]\|[1-8][0-9])(?:(?:\.[0-9]{1,6})?))$	string
contact>ContactID (Optional)	SDS can be passed in contact.	minLength: 1 maxLength: 64	string
contact>name*	Contact name.		string
contact>phone>countryCode*	Country code of the mobile it belongs.	pattern: ^\+(\d{1}\-)?(\d{1,3})$	string
contact>phone>number*	Phone number of the user.	minLength: 4 maxLength: 13	string
contact>phone>isMobile*	Whether the phone is of type mobile or telephone.		boolean
contact>phone>areaCode (Optional)	In case of type telephone, areaCode of the telephone it belongs.	pattern: ^\+(\d{1}\-)?(\d{1,3})$	string
objective>input*
containers (Optional)	List of Containers		string
batchID (Optional)	Batch ID	minLength: 1 maxLength: 64	string
jobTypeName (Optional)	Job Type Name	minLength: 3 maxLength: 36	string
jobTypeId*	Job Type ID.	minLength: 4 maxLength: 64	string
_event_meta (Optional)	Metadata.
scheduledFor (Optional)	Time slot scheduled for the job.
scheduledFor>startDateTime*	Start Date time.		number
scheduledFor>endDateTime (Optional)	End Date time.		number

Attribute Name	Data Type Expected	Purpose
Tenant ID	UUID	The ID of the tenant to whose data domain the Job belongs.
Job ID	UUID	The system-generated ID of the Job.
Instructions (Optional)	Array of JSON	The instruction JSON schema is as follows: 1. id: Unique ID for instruction. 2. containers: List of containers associated with this instruction. 3. location: Location ID of the location where the instruction is to be performed. 4. contact: Name and contact number of the customer (a secure data ID if the real phone number is passed. Masked phone number can be passed directly). 5. timeSlot: Defines the preferred time slot for executing this instruction. Has two keys from and to which have the start & end epoch time of the time slot. 6. workflow: Workflow instance ID (Workflow instance is workflow id plus the input data for executing the workflow. The instance is stored in the Workflow service and passed as an ID here.). 7. next: Has two keys onSuccess and onFailure whose values denote the next instruction to be executed in case of current instruction success and failure respectively.

Member	Description	Validation	Data type
attributes		minItems: 1
name	Attribute name.	minLength: 1 maxLength: 32 pattern: ^[a-zA-Z]{1,32}$	string
description	Attribute description.	minLength: 0 maxLength: 256	string
tags	Tag to be associated with the attribute.		string
dataType	Data type.	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.

Stop	Objective(s)
Location-A	Pick up shipment s1; Pick up shipment s2
Location-B	Deliver shipment s1
Location-D	Pick up shipment s3
Location-C	Deliver shipment s2; Deliver shipment s3
Location-A	Pick up shipment s4
Location-E	Deliver shipment s4

Updated 08 Aug 2023

Did this page help you?

Dispatch Service

Integrate with Dispatch