Introduction to Workflow Service

Workflow Service lets you register Execution Task, Execution Macro, or Execution Workflow as new services using the CRUD APIs. 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.

Execution Task

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. Moreover, attributes are set up based on the type of Execution Task.

Components of an Execution Task

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’.

To create to register an Execution Task, call the Register a task endpoint.

Request bodies are specified in JSON format. The following examples show a request body for registering an Execution Task:

{
    "name": "CaptureImage",
    "description": "To capture an image",
    "tag": [
        {
            "name": "usage",
            "value": "Utility"
        }
    ],
    "inputs": {
        "type": "object",
        "properties": {
            "resolution": {
                "title": "Resolution",
                "description": "Resolution of image to be captured",
                "type": "object",
                "properties": {
                    "length": {
                        "title": "Length",
                        "description": "Length (in cm)",
                        "type": "number",
                        "exclusiveMinimum": 0
                    },
                    "breadth": {
                        "title": "Breadth",
                        "description": "Breadth (in cm)",
                        "type": "number",
                        "exclusiveMinimum": 0
                    }
                },
                "required": ["length", "breadth"]
            },
            "fileSizeLimit": {
                "title": "Max file size",
                "type": "number",
                "description": "Maximum Size limit (in kb) of image to be captured",
                "exclusiveMinimum": 0
            },
    },
    "output": {
        "type": "object",
        "properties": {
            "success": {
                "description": "Success flag for the operation performed by user",
                "type": "boolean"
            },
            "captures": {
                "type": "array",
                "description": "Array of captured images",
                "items": {
                    "type": "object",
                    "description": "Object to describe details of single image",
                    "properties": {
                        "url": {
                            "type": "string",
                            "description": "Url of image"
                        },
                        "timestamp": {
                            "type": "number",
                            "description": "Epoch timestamp for the image capture"
                        }
                    },
                    "required": ["url", "timestamp"]
                }
            },
            "eventCode": {
                "type": "string",
                "description": "Event code"
            },
            "reasonCode": {
                "type": "string",
                "description": "Reason code"
            },
            "meta": {
                "type": "object",
                "description": "Meta data related to execution of task",
                "properties": {
                    "startTime": {
                        "type": "number",
                        "description": "Epoch timestamp for the start of task"
                    },
                    "endTime": {
                        "type": "number",
                        "description": "Epoch timestamp for the end of task"
                    },
                    "location": {
                        "type": "object",
                        "description": "Location at start of task",
                        "properties": {
                            "latitude": {
                                "type": "string",
                                "description": "Latitude"
                            },
                            "longitude": {
                                "type": "string",
                                "description": "Longitude"
                            }
                        }
                    },
                    "userDetails": {
                        "type": "string",
                        "description": "Unique identifier of user performing the action"
                    }
                }
            }
        },
        "required": ["success"]
    },
    "canMerge": false
}
19201920

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 the set of instructions for the FE telling him what to do at a particular stop. The Mobile App SDK orchestrates the execution of Tasks.

States of an Execution Task

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:

21942194

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:

19201920

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.

Default Execution Tasks

The platform provides default execution tasks that you can add to your workflow:

Execution Task

Functionality

Input Parameters

Output

On Failure

VerifyLocation

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

Ability to capture 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

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

Ability to scan a barcode or QR Code.

  1. scanType: [Barcode, QRCode, Both]*
  2. scanMode: SINGLE, MULTI*
  3. scanCountLimit
  4. validationRegex
  1. Success: true/false
  2. scans: [value, isValid, timestamp]
  3. eventCode: ScanS/ScanF
  4. reasonCode

Failure

Doodle

Ability to capture a finger-tip trace on screen.

  1. Pen colour
  2. FileSizeLimit*
  3. Dimension*
  1. Success: true/false
  2. imageUrlOfDoodle
  3. eventCode: DoS/DoF
  4. reasonCode

Failure

Form

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

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

Pick (Execution Task) is when the inventory transfer is Receivables (In). This is used to maintain track of ownership of goods and cash.

  1. Items: [{sku, count, productDescription}]*
  2. allowCustodyExchange-
    TRUE: 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

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 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

Ability to start a workflow. It is mandatory.

  1. Success: true/false
  2. eventCode: Start/StartF
  3. reasonCode

Completed - Success

Ability to define if the terminal endpoint of a workflow is successful.

  1. Success: true/false
  2. eventCode: CSS/CSF
  3. reasonCode

Completed - Failure

Ability to define if the terminal endpoint of a workflow is failure.

  1. Success: true/false
  2. eventCode: CFS/CFF
  3. reasonCode

InitPayment

To instruct the app layer to initiate payment flow with payment data.

  1. Amount*
  2. allowedPaymentMode*
  1. Success: true/false
  2. transactionID
  3. paymentMode
  4. eventCode: IniS/IniF
  5. reasonCode

Process Payment

To process a 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. reasonCode

Complete Payment

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

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

DropCash

Ability to deposit cash.

  1. expectedAmount*
  1. Success: true/false
  2. eventCode
  3. reasonCode

Reversing Execution Tasks

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.

17481748

Execution Macro (EM)

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 template 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.

Components of an Execution Macro

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

To create to register an Execution Macro, call the Register a macro endpoint.

Request bodies are specified in JSON format. The following examples show a request body for registering an Execution Macro:

{
    "name": "CollectCash",
    "flows": [
        {
            "name": "InitPayment",
            "id": "etask:4eb8d36b-6762-5c53-aca6-95b1f4e3aa3f",
            "description": "initiate payment",
            "next": [
                {
                    "task": "ProcessPayment",
                    "condition": "initSuccess"
                },
                {
                    "task": "macroFailed",
                    "condition": "initFailure"
                }
            ]
        },
        {
            "name": "ProcessPayment",
            "id": "etask:9a559375-02a5-50fe-9ce4-0a36df6f324e",
            "description": "Verify OTP/ Verify Number",
            "next": [
                {
                    "task": "Input OTP",
                    "condition": "process payment"
                },
                {
                    "task": "CompletePayment",
                    "condition": "processSuccess"
                }
            ]
        }
    ],
    "inputs": {},
    "conditions": {},
    "canMerge": false,
    "description": "CollectMoneyCash",
    "tag": [
        {
            "name": "CollectMoneyCash",
            "value": "PAYMENT_MODE/AMOUNT_DISPUTE"
        },
        {
            "name": "CollectMoneyCash",
            "value": "INIT_PAYMENT_FAILURE"
        }
    ],
    "systemGenerated": true
}

System Defined Macros

System Defined Macros

Functionality

Input Parameters

Output

On Failure

CollectMoney

Ability to collect specified amounts through allowed modes of payment.
This system defined macro is combination of three tasks InitPayment, Process Payment, Complete Payment.

  1. Amount
  2. allowedPaymentMode: ["CASH", "UPI", "PAYMENT_LINK"]
  3. tenantTransactionID
  4. transactionID
  5. collectedAmount
  1. Success: true/false
  2. paymentMeta
  3. transactionID
  4. eventCode: WfS/WfF
  5. reasonCode

Failure

VerifyNum

This system-defined macro is a combination of CaptureInput & VerifyInput. Use case to verify OTP/ Verify Number.

  1. Input
  2. inputType
  3. anyOf: apiURl, Value
  4. maxAttemptAllowed
  1. Success: true/false
  2. eventCode: WfS/WfF
  3. reasonCode

Example Execution Macro

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 Workflows. Execution Task Workflows, as a sequence of Execution Tasks, are illustrated below:

17481748

These individual templates are used as Execution Macros.

Execution Workflow

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:

19201920

To create to register an Execution Macro, call the Register a workflow endpoint.

Request bodies are specified in JSON format. The following examples show a request body for registering an Execution Workflow:

{
    "name": "SL_TEAM_CodDropCash",
    "flows": [
        {
            "name": "startET",
            "id": "etask:952f3754-12e8-5ff2-93a8-aca383d18e56",
            "description": "starting ET",
            "next": [
                {
                    "task": "dropCash",
                    "condition": "wfStarted"
                },
                {
                    "task": "workflowFailed",
                    "condition": "wfFailed"
                }
            ]
        },
        {
            "name": "dropCash",
            "id": "etask:10f25617-ee46-5743-b7b2-f71d0e11b5c3",
            "description": "Drop cash et",
            "next": [
                {
                    "task": "workflowSucceeded",
                    "condition": "dropSuccess"
                },
                {
                    "task": "workflowFailed",
                    "condition": "dropFailed"
                }
            ]
        }
    ],
    "inputs": {},
    "conditions": {},
    "canMerge": false,
    "description": "DROP_CASH_FAILED",
    "tag": [
        {
            "name": "wfStarted",
            "value": "WFLOW_FAILED"
        },
        {
            "name": "wfStarted",
            "value": "NOT_ATTEMPTED"
        }
    ]
}

Execution Workflow Instance

A workflow instance is a workflow ID plus the input data for executing the workflow.

Attributes of an Execution Workflow Instance

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
(Optional)

Object

Input values of the variables used in the workflow.

To create to register an Execution Macro, call the Create instance of a workflow endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating an instance of a Workflow:

{
    "workflow": "SL_TEAM_CodDropCash",
    "inputs": {}
}

Did this page help you?