# Work Requests

See Work requests for a detailed overview.

Technically, scheduled workflows are Work Requests with children work requests (see the `parent` field).

Work Requests have the following important properties:

- task_type: the type of the task (`Worker`, `Server`, `Internal`, or `Workflow`; see Tasks)

- task_name: the name of the task to execute (used to figure out the Python class implementing the logic)

- task_data: a JSON dict representing the input parameters for the task

- configured_task_data: a copy of `task_data` with task configuration applied. This is set by `apply_task_configuration` when the work request becomes `PENDING` and is guaranteed to be set when a work request is in status `PENDING` or `RUNNING`.

- scheduler_tags_provided: a list of task tags provided by the work request for scheduling purposes. It is set when the work request becomes `PENDING`, and it is guaranteed to be set for all `PENDING` work requests.

- scheduler_tags_required: a list of worker tags required by the work request for scheduling purposes. It is set when the work request becomes `PENDING`, and it is guaranteed to be set for all `PENDING` work requests.

- dynamic_task_data: a JSON dict storing resolved values for task input fields (see Task input fields) and other derived information about the task, set by `compute_dynamic_data` based on its `configured_task_data` when a worker is assigned to the work request.

  This is guaranteed to be set when the worker is in status `RUNNING`.

  One special key is always supported here:

  - `parameter_summary` (optional): a string describing the most important parameters to this work request (for example, a workflow to build and test version `1.0-1` of the `hello` source package might have the parameter summary `hello_1.0-1`). This can be used in visual representations of the work request.

- status: the processing status of the work request. Allowed values are:

  - blocked: the task is not ready to be executed

  - pending: the task is ready to be executed and can be picked up by a worker

  - running: the task is currently being executed by a worker

  - aborted: the task has been cancelled/aborted

  - completed: the task has been completed

- result: the processing result. Allowed values are:

  - success: the task completed and succeeded

  - failure: the task completed and failed

  - error: an unexpected error happened during execution

- workspace: foreign key to the workspace where the task is executed

- worker: foreign key to the assigned worker (is NULL while work request is pending or blocked)

- unblock_strategy: specify how the work request can move from `blocked` to `pending` status. Supported values are:

  - `deps`: the work request can be unblocked once all the dependent work requests have finished (usually completed, but they may also be aborted if the dependency allows failure)

  - `manual`: the work request must be manually unblocked

  - `incremental`: the work request can be unblocked at any time to make incremental progress, either on creation or when a dependency has completed; this is only relevant to workflow callbacks

- parent: workflow hierarchy tree (optional, NULL when scheduled outside of a workflow); foreign key to the containing WorkRequest. The parent hierarchy will eventually reach a top-level node of type `WORKFLOW` which is the node that manages this `WorkRequest` hierarchy, possibly including sub-workflows. See Workflows.

- dependencies: order of execution within a workflow hierarchy (optional, hierarchy is run in parallel unless otherwise constrained); ManyToMany relation with other `WorkRequest` (from the same workflow) that need to complete before this one can be unblocked (if using the `deps` unblock_strategy)

- workflow_template: for workflows created from a workflow template, foreign key to that template; may be set to NULL if the template is deleted

- workflow_data: JSON dict controlling some workflow specific behaviour; it is expected to support the following keys:

  - `allow_failure` (optional, defaults to False): boolean indicating what to do with the parent workflow and reverse-dependencies if the work request fails. If true, they can continue, otherwise they are aborted.

  - `allow_dependency_failures` (optional, defaults to False): boolean indicating whether this work request should be aborted if any of its child work requests or dependencies fail. (This is related to `allow_failure`: `allow_failure` is checked on the failed work request, while `allow_dependency_failures` is checked on work requests that are waiting for the failed work request. Work requests are only aborted if both of these are false.)

  - `display_name`: name of the step in the visual representation of the workflow

  - `step`: internal identifier used to differentiate multiple workflow callbacks inside a single workflow. It acts like a machine equivalent for `display_name`, to allow the orchestrator to encode the plan about what it is supposed to do at this point in the workflow. This must be unique across all children of a given workflow.

  - `group` (optional): name of the group within this workflow containing this work request.

  - `workflow_template_name` (optional): for workflows created from a workflow template, the name of that template, cached here for convenience.

  - `manual_unblock` (optional): data stored for work requests with `unblock_strategy` set to `manual`.

  - `needs_input` (optional): for Wait tasks, whether this task requires user input.

  - `retry_count` (optional, defaults to 0): the number of times this task has been retried automatically.

  - `visible` (optional, defaults to True): whether this task should be shown in the visual representation of the workflow.

  - `expanded` (optional, defaults to True): whether this task’s descendants should be expanded by default in the visual representation of the workflow.

- event_reactions: JSON dict describing actions to perform in response to specific events.

- internal_collection: (only for workflow work requests): reference to a debusine:workflow-internal collection that holds artifacts produced during this workflow

- expiration_delay: retention time for this work request in the database

- supersedes: optional work request that has been superseded by this one: this is used to track previous attempts when retrying tasks.

Blocked work requests using the `deps` unblock strategy may have dependencies on other work requests. Those are only used to control the order of execution of work requests inside workflows: the scheduler ignores `blocked` work requests and only considers `pending` work requests. The `deps` unblock strategy will change the status of the work request to `pending` when all its dependent work requests have completed.