Workflow Service
Workflow Service lets you register Execution Workflows using the existing Execution Tasks and Execution Macro. Updating an existing Workflow within the service registers a new version of that Workflow. Moreover, after the Workflow expires, no additional updates to that Workflow are allowed.
With this basic overview, let's get into the details regarding Execution Task, Execution Macro, Execution Workflow, and its Instance.
An Execution Task (ET) is the smallest atomic task that is performed by an operator. The ET has a binary outcome, i.e., it can either succeed or fail. An ET can’t be canceled; only the ET workflow or objective can be canceled.
Some example execution tasks are: scan, collect, verify, capture, stop, start, custody in, custody out, etc.
In an Execution Workflow, there are multiple Execution Tasks. Each task has its own unique ID attached to it.
An execution task has the following components:
Component Name | Description |
ID | This is the ET ID, a unique human-friendly string for the Execution Task. |
Name | Name defined for an Execution Task. Example: Collect, capture, scan, verify, etc. |
Input Parameters | Input parameters allow you to pass a set of information during the invocation of an ET for further use. These parameters vary depending on the ET. Example: ET_COLLECT: Amount to be collected from the consignee or allowed payment gateways. ET_VERIFY: Types of verification, i.e., OTP or ID. ET_CAPTURE: Size of the image to be captured. |
Output Status & Data | An ET has binary outcomes. The two possible terminal statuses are: ET_SUCCESS and ET_FAILURE. Both the status can return additional data with it to represent the outcome. This data doesn't affect the workflow in any way. This is just additional information captured and shared with other applications/systems. Example: Barcode value is returned with the output status in the case of ‘Scan Code’. |
Every Execution Task has a Completion Mode. This completion mode describes the outcome of an Execution Task which can either be a success or a failure. With that, the ET also has a Reason Code that describes the outcome of the task. These are a set of pre-defined descriptions based on the outcome of the task.
The Delivery Agent (DA) mobile app exists on every FE’s device. For every Execution Task, a corresponding pre-coded module is expected in the app as part of SDK. This module executes the Task on the device running the DA app.
In other words, the app already has a set of instructions for the FE telling him what to do at a particular stop. The Mobile App SDK orchestrates the execution of Tasks.
An Execution Task has the following defined states:
- Pending
- Active
- Success
- Failure
- Obsolete
The state of an Execution Task is defined by the task’s prerequisites. The prerequisite field of an Execution Task is a collection of Completion Mode and other Execution Tasks.
The state of the Execution Task is IMPLICIT and does not need to be advanced by command or any other process. It is primarily used by the UI to determine what to show the user.
The following example shows the progression of states of an ET:
Suppose there are two different Execution Tasks, i.e., ET-1 and ET-2. ET-1 has no prerequisites and ET-2 is dependent upon ET-1 having a Completion Mode of type ‘fail’. ET-2 will become active when ET-1 is marked completed with ‘fail’ and a Completion Mode is attached. Here is a simplified representation:
All Execution Tasks must end in success or failure. However, it is possible to set a prerequisite for an Execution Task based on the Reason Code of a Completion Mode for another task. It is, therefore, possible to have more than two divergent paths from a single Execution Task:
To perform Execution Tasks, its state must be ‘active’. If none of the Execution Tasks within a Workflow remain active, the Workflow reaches its terminal state.
The platform provides default Execution Tasks that you can add to your workflow. The table below includes all the Execution Tasks with IDs. Use these IDs while creating an Execution Workflow.
Execution Task | Execution Task ID | Functionality | Input Parameters | Output | On Failure |
VerifyLocation | etask:7f3897da-3a1f-5736-b8e5-5d9f131b13cd | Ability to verify if the rider is at a certain location. | 1. addressString 2. latitude 3. longitude 4. radius (for geofence confirmation) 5. accuracyForGeolocation | 1. Success: true/false 2. eventCode: WfS/WfF 3. reasonCode | Failure |
CaptureImage | etask:9370d00a-8d84-5bf9-94bb-cd8cc73eeeec | Ability to capture an image. | 1. Image Resolution 2. fileSizeLimit 3. captureMode [SINGLE, MULTI] 4. captureCountLimit | 1. Success: true/false 2. captures: [imageUrl, timestamp] 3. eventCode: ImgS/ImgF 4. reasonCode | Failure |
CaptureInput | etask:7b5637cc-570e-5c9d-b184-ecfbbd7c198d | Ability to capture a number or string input. | 1. inputType: String, Number 2. validationRegex | 1. Success: true/false 2. value 3. isValid 4. attemptCount 5. eventCode: CinS/CinF 6. reasonCode |  |
Scan | etask:28cba55d-2aad-5568-863a-9e7e645f8c7b | Ability to scan a barcode or QR Code. | 1. scanType: [Barcode, QRCode, Both] 2. scanMode: SINGLE, MULTI 3. scanCountLimit4. validationRegex | 1. Success: true/false 2. scans: [value, isValid, timestamp] 3. eventCode: ScanS/ScanF 4. reasonCode | Failure |
Doodle | etask:cea7c9a7-3ee7-52e9-ab3e-82849675d745 | Ability to capture a finger-tip trace on the screen. | 1. Pen colour 2. FileSizeLimit 3. Dimension | 1. Success: true/false 2.ImageUrlOfDoodle3. eventCode: DoS/DoF4. reasonCode | Failure |
Form | etask:80446347-ede5-5cf9-8e56-b3d59fda4b5c | Ability to collect multiple information in a custom-defined form. | Custom Form JSON (question, question type, validations) | 1. Success: true/false 2. Response [answers] 3. eventCode: FormS/FormF 4. reasonCode | Failure |
Display | etask:574ff9b0-c49c-5eb5-b550-8548ae0cab44 | Ability to display an alert message, information, warning, etc to the operator. | 1. displayType: [Alert, Warning, Message] 2. Text 3. ImageUrl | 1. Success: true/false 2. eventCode: DisS/DisF 3. reasonCode | Failure |
Pick | etask:04d2414c-ddc1-552e-af02-78073dbb8ff7 | Pick (Execution Task) is when the inventory transfer is Receivables (In). | 1. Items: [{sku, count, productDescription}] 2. allowCustodyExchangeTRUE: double confirmation would be required. Applicable for custody change FALSE: Single confirmation only required. Applicable for normal pickup | 1. Success: true/false 2. Remark: text 3. eventCode: PS/PF 4. reasonCode |  |
Deliver | etask:dcac5d49-c54c-5c38-a780-ad2e9ba5e2e2 | Deliver (Execution Task) is when the inventory transfer is Payables (Out). | 1. Items: [{sku, count, productDescription}] 2. allowCustodyExchange TRUE: double confirmation would be required. Applicable for a custody change FALSE: Single confirmation only required. Applicable for normal pickup | 1. Success: true/false 2. Remark: text 3. eventCode: DS/DF 4. reasonCode |  |
Start | etask:952f3754-12e8-5ff2-93a8-aca383d18e56 | Ability to start a workflow. It is mandatory. |  | 1. Success: true/false 2. eventCode: Start/StartF 3. reasonCode |  |
Completed-Success | etask:134e93b4-49a8-59b9-bc6c-7bd9045728ff | Ability to define if the terminal endpoint of a workflow is successful. |  | 1. Success: true/false 2. eventCode: CSS/CSF 3. reasonCode |  |
Completed-Failure | etask:e04ab83d-2a02-5970-ade9-e2a8a879b200 | Ability to define if the terminal endpoint of a workflow is failure. |  | 1. Success: true/false 2. eventCode: CFS/CFF 3. reasonCode |  |
InitPayment | etask:4eb8d36b-6762-5c53-aca6-95b1f4e3aa3f | To instruct the app layer to initiate the payment flow with payment data. | 1. Amount 2. allowedPaymentMode | 1. Success: true/false 2. transactionID 3. paymentMode 4. eventCode: IniS/IniF 5. reasonCode |  |
ProcessPayment | etask:9a559375-02a5-50fe-9ce4-0a36df6f324e | To process payment and generate transaction IDs. | 1. Amount 2. allowedPaymentMode | 1. Success: true/false 2. transactionID 3. collectedAmount (incl. currency) 4. paymentMetaData 5. eventCode: PPS/PPF 6. reason | |
CompletePayment | etask:0e6c7bd7-c9ab-5b82-85b2-a054249bc1f1 | To record final details of payments (tenant payID, transaction ID, amount, etc). | 1. expectedAmount 2. collectedAmount 3. transactionID 4. tenantTransactionID | 1. Success: true/false 2. eventCode: CPS/CPF 3. reasonCode | |
VerifyInput | etask:6fc10a60-a144-5798-97f3-1f12e77f56e2 | Ability to verify if the given input matches the response from an API or static value. | 1. anyOf Input, value 2. Input, apiURL, JsonPathOfValue 3. maxAttemptAllowed 4. attemptCount | 1. Success: true/false 2. eventCode: ViS/ViF 3. ReasonCode | |
DeliverCash | etask:2fffdf62-62b3-5e70-bd9e-d4d2644ee2fe | Ability to deliver cash. | 1. expectedAmount | 1. Success: true/false 2. eventCode 3. reasonCode |
If needed, it is possible to undo Execution Tasks and go backward. However, some actions or exchanges of custody in the course of executing the task should be reversed.
This allows for the correction of mistakes a worker might have made or reacting to changes in circumstances in the field. Some Execution Tasks are NOT reversible and must be defined as such. If a Reverse Action is defined on an Execution Task, that action must be completed to modify the Completion Mode.
You can combine one or more Execution Tasks together in a logical sequence that can be reused. This is called an Execution Macro.
Execution Macros let the tenant create reusable blocks of templates for business flow components. In other words, there might be a sequence of execution tasks that remain saved for recurring workflows. In that case, rather than manually creating the same workflow over and over, you can create an Execution Macro and attach it wherever you need it in a workflow.
These reusable templates help to define a subset of the bigger logistical process. These templates can be re-used and can be edited in one place to allow the propagation of changes throughout the universe of the Tenant. This helps drive standardization for identical processes.
The Execution Macro has the following components:
Component Name | Description |
ID | This is the EM ID, a unique human-friendly string for the Execution Macro. |
Name | Name defined for an Execution Macro. Example: B2C-POD, VerifyCustomer, DeliverContainer, etc. |
Input Parameters | Input parameters allow you to pass a set of information during the invocation of the first Execution Task in an Execution Macro. |
Output Status | An Execution Macro has binary outcomes. The two possible terminal statuses can be: EM_SUCCESS and EM_FAILURE. Note: Please don’t confuse them with ET_Success and ET_Failure. |
System Defined Macro | Macro ID | Functionality | Input Parameters | Output | On Failure |
CollectPayment | emacro:c014eb65-8944-5320-8e51-dccad861a086 | Ability to collect specified amounts through allowed modes of payment. This system-defined macro is a combination of three tasks InitPayment, Process Payment, and Complete Payment. | 1. Amount 2. allowedPaymentMode: ["CASH", "UPI", "PAYMENT_LINK"] 3. tenantTransactionID 4. transactionID5. collectedAmount | 1. Success: true/false 2. paymentMeta 3. transactionID 4. eventCode: WfS/WfF5. reasonCode | Failure |
Let's suppose, there is a Tenant A with the following Execution Task Workflows in his universe:
- VerifyCustomer: To correctly identify if the person receiving the package is authorized to collect it or not.
- B2C-POD: To take the proof of delivery through a signature or photos.
- DeliverContainer: To verify if the package picked by the Operator is correct and then hand it over to the consignee. A maximum of 3 retries is allowed for the Operator to scan the correct package.
So, the complete Execution Workflow (VerifyCustomer+B2C-POD+DeliverContainer) has multiple Execution Tasks in it. The Execution Tasks within VerifyCustomer ET Workflow are coupled together to form an Execution Macro. Similarly for B2C-POD & DeliverContainer as well.
These Execution Macros can be reused in multiple Execution Workflow. Execution Task Workflows, as a sequence of Execution Tasks, are illustrated below:
These individual templates are used as Execution Macros.
The operator needs to perform a set of tasks in a pre-defined manner. The sequence of these Execution Tasks is defined as Execution Workflow.
Every objective has an Execution Workflow attached to it. To complete the objective, the operator needs to perform the Execution Workflow. This Execution Workflow consists of one or more Execution Tasks and/or Execution Macros.
There is an Execution Workflow Designer which is basically a browser-based drag-and-drop tool. It has all the defined Execution Tasks. The tenant can further use the Execution Workflow Designer to create and store Execution Workflows and Execution Macros.
Here is a graphical representation of multiple Execution Tasks & Execution Macro forming an Execution Workflow:
To create to register an Execution Macro, call the Register Workflow endpoint. Before that, check out Execution Task & Macro Payloads.
Request bodies are specified in JSON format. The following examples show a request body for registering an Execution Workflow:
🚧 Defining Execution Macro in an Execution Workflow
When you define an Execution Macro for a particular Execution Task in an Execution Workflow, please follow this format: Macro_Task. Example: CollectPayment_InitPayment. Here, the CollectPayment is a Macro that is used for the InitPayment Execution Task.
📘 Entity, Event, and Reason Codes
Check out the list of Entity, Event, and Reason Codes here.
Member | Description | Validation | Data type |
name | Name of the Workflow. | minLength: 1 maxLength: 24 pattern: ^[a-zA-Z0-9-_]{1,24}$ | string |
description | Description of the Workflow. | minLength: 1 maxLength: 150 | string |
tag>name | Tag name. | minLength: 1 maxLength: 10 | string |
tag>value | Tag value. | minLength: 1 maxLength: 10 | string |
flows | ETs/EMs for the workflow. |  |  |
flows>next | Display the name of the Execution Task. |  | string |
flows>id | Unique ID of the Execution Task. |  | string |
flows>description | Description of the Execution Task. |  | string |
task | The task is to be performed if the condition is validated. |  | string |
input>$expr | Expression of defined inputs. |  | string |
input>$val | Value of the inputs. |  |  |
oneOf | List of Execution Tasks that are allowed within this Execution Macro. |  | string, boolean, number |
A workflow instance is a workflow ID plus the input data for executing the workflow.
The Execution Workflow Instance are categorized as the following:
Category | Attribute Name | Data Type Expected | Purpose |
Base | Tenant ID | UUID | The ID of the tenant to whom the workflow instance belongs. |
Base | Workflow ID | VarChar | This contains the system-generated unique id for the workflow. |
Base | Inputs | Object | Input values of the variables used in the workflow. |
To create to register an Execution Macro, call the Create Workflow Instance endpoint.
Request bodies are specified in JSON format. The following examples show a request body for creating an instance of a Workflow:
Member | Description | Data type |
workflow | Workflow ID. | string |
inputs | Dynamic inputs are provided at the time of creating workflow instance. | object |
You can manage multi-objective runs in your workflows. This feature allows app developers to process multiple objectives (such as shipments or orders) simultaneously or sequentially.
To enable multi-objective workflows, you'll need to set the enableMultiObjectiveFlow parameter to true while creating a workflow draft. See the example below:
By setting this parameter, the Workflow SDK will expose configuration settings for selected Execution Tasks in the workflow.
When working with multi-objective workflows, ensure the following
- Objective Types: The objectives to be merged are of the same type.
- Grouping Logic: Implement suitable grouping business logic at the app code level, as the Workflow Service doesn't provide its own grouping logic.
- Timing and Actions: Manage the timing of objective grouping and the resulting actions within the app. For example, when dealing with packages requiring OTP validation, group the objectives before generating and sending the OTP. The OTP generation and sending should occur only once.