Lifecycle

This page describes the task lifecycle and how a task progresses from a created to completed state.

Via Task Manager, the operator sends, updates, and monitors tasks, while the taskable agent receives tasks and reports status updates to Lattice.

Task statuses

The task status represents each stage of the task lifecycle.

When an agent receives a task, it should respond to Task Manager with status updates through the UpdateStatusRequest via StatusUpdate. This progresses the task through its lifecycle.

The task lifecycle model is intentionally flexible to support the specific reporting needs of the agent. Operators can update the status of a task to whichever status best describes its state.

For the full list of statuses, refer to the Status protobuf definition.

Lifecycle progression

Taskable agents will only receive tasks with status STATUS_SENT, wrapped appropriately in an Execute, Cancel, or Complete request in a ListenAsAgentResponse.

Name	Number	Description
STATUS_SENT	3	Task Manager sends a task to be executed by the agent.

The agent should report the following task statuses as it progresses through the task:

Name	Number	Description
STATUS_MACHINE_RECEIPT	4	The agent received the task but has not acknowledged receipt.
STATUS_ACK	5	The agent acknowledges receipt of the task.
STATUS_WILCO	6	The agent confirms it "will comply" and intends to execute the task.
STATUS_EXECUTING	7	The agent begins to actively execute the task. All tasks that an agent is actively performing should be in this status.
STATUS_DONE_OK	9	The agent reached a terminal state and completed the task successfully. This can result from operator-initiated requests for task completion.
STATUS_DONE_NOT_OK	10	The agent reached a terminal state but did not complete the task successfully. This can result from operator-initiated requests for task completion or cancellation. The agent should include a descriptive task error when reporting a `STATUS_DONE_NOT_OK`.

The task status an agent reports should always be a descriptive snapshot of what it is currently doing.

Lifecycle example

The following is an example of a task progressing from a sent to canceled state:

The agent receives a task with status STATUS_SENT from Task Manager.
The agent indicates to Task Manager that it received the task. The agent uses the UpdateStatusRequest endpoint to update the status of the task to STATUS_ACK or STATUS_MACHINE_RECEIPT.
When the task is ready to progress to the next stage, the agent uses UpdateStatusRequest to update the status to STATUS_WILCO.
When the agent begins executing the task, it updates the task status to STATUS_EXECUTING to inform Task Manager.
After the agent has successfully completed the task it was executing, it uses UpdateStatusRequest to change the status to STATUS_DONE_OK.
If the agent receives a task with status STATUS_CANCEL_REQUESTED, it immediately stops execution of the task it had received and calls UpdateStatusRequest with status STATUS_DONE_NOT_OK.

Terminal statuses

The STATUS_DONE_OK and STATUS_DONE_NOT_OK statuses are terminal statuses. Once a task's status is terminal, it's complete and can't be updated.

Task errors

If the asset cannot perform the task at a given time or encounters an internal failure, it should report a descriptive error code and error message. Assets can report any task errors or failures through the task_error field, located in the TaskStatus field of StatusUpdate.

For example, an agent might report a status update with the following task_error:

"statusUpdate": {
    "version": {
        "taskId": "my-task",
        "definitionVersion": 1  // This should be the appropriate definition version for your particular task
        "statusVersion": 5  // This should be the appropriate status version for your particular task
    },
    "status": {
        "status": "DONE_NOT_OK",
        "taskError": {
          "code": "ERROR_CODE_FAILED",
          "message": "The asset failed task execution due to an internal error.",
        }
    }
}

The task_error message indicates that the agent encountered an internal error during task execution. Further specifics can be added to the message field as needed.

Operators can view the task_error message field in the Lattice UI task panel.

Identify a task in its lifecycle

To identify a task at any point in its lifecycle, reference the following TaskVersion fields:

task_id: the unique ID for the task.
status_version: increments on changes to TaskStatus.

Status version updates

Whenever a task changes its status, such as from SENT to ACK or EXECUTING to DONE_OK, the task increments its status_version. To update the status of a task, use the UpdateStatusRequest API with the appropriate task_version you wish to update.

For example, if the agent receives a task from Task Manager with status SENT:

"task": {
      "version": {
        "taskId": "my-task",
        "definitionVersion": 1,
        "statusVersion": 1
      },
      "status": {
        "status": "STATUS_SENT"
      }
      ...
}

The agent should respond back with status STATUS_MACHINE_RECEIPT using the UpdateStatusRequest endpoint:

"statusUpdate": {
    "version": {
        "taskId": "my-task",
        "definitionVersion": 1
        "statusVersion": 1
    },
    "status": {
        "status": "STATUS_MACHINE_RECEIPT"
    },
}

When the agent is ready to move the task status to STATUS_ACK, it should send an UpdateStatusRequest with the incremented status_version:

"statusUpdate": {
    "version": {
        "taskId": "my-task",
        "definitionVersion": 1
        "statusVersion": 2
    },
    "status": {
        "status": "STATUS_ACK"
    },
}

With each change in status, you must increment the status_version field accordingly.

Task statuses​

Lifecycle progression​

Lifecycle example​

Terminal statuses​

Task errors​

Identify a task in its lifecycle​

Status version updates​