Task Inbox
The Task Inbox is the heart of WorkDesk — the queue of HIL tasks pending your action. Tasks arrive when Flow Studio workflows suspend at a HIL node targeting you or your role.
What Is a HIL Task?
A Human-in-the-Loop (HIL) task is created when a workflow running in Flow Studio reaches a node that requires human input before it can continue. The workflow pauses, and a task record is written to the WorkDesk database targeting the actor (you) or a role group you belong to.
When the task appears in your inbox, acting on it sends a response back to the workflow engine, which then resumes execution automatically.
Three Task Types
Approval
Binary decision: Approve or Reject. Optional comment field. Used for purchase requests, leave approvals, access grants.
Form
An Atlas Form rendered inline. You fill fields and submit. Used for data collection, onboarding steps, structured input at a workflow stage.
Review
Read-only content review. You review displayed content (document, report, data) and Acknowledge. Optional comment.
Task Card (Visual Anatomy)
Each task in the inbox is rendered as a card. Here is a representative approval task card:
Marketing department expense report for Q1 totaling $12,450. Please review the attached summary and approve or reject with a comment.
Task Properties
| Property | Type | Description |
|---|---|---|
taskId | string (GUID) | Unique identifier for the HIL task record |
executionId | string (GUID) | The workflow execution this task belongs to |
type | approval | form | review | Determines which UI is rendered for this task |
title | string | Human-readable task title from workflow config |
description | string | Context or instructions for the actor |
dueAt | ISO 8601 datetime | Optional deadline — shown as urgency indicator |
assignedTo | actorId or roleId | Who the task is assigned to |
claimedBy | actorId or null | Which actor has claimed the task (if claiming enabled) |
formId | string or null | Atlas Form ID — only for type form |
status | pending | claimed | completed | expired | Task lifecycle state |
createdAt | ISO 8601 datetime | When the HIL node suspended the workflow |
Inbox API
// Fetch pending inbox tasks for the authenticated user
GET /api/workdesk/inbox
Authorization: Bearer {token}
// Query parameters
?type=approval // filter by task type
?status=pending // pending | claimed | completed
?page=1&pageSize=20 // pagination
// Response
{
"items": [
{
"taskId": "3fa85f64-...",
"executionId": "7bc12d45-...",
"type": "approval",
"title": "Expense Report Approval — Q1 Marketing",
"description": "...",
"dueAt": "2026-05-28T17:00:00Z",
"status": "pending",
"assignedTo": { "type": "actor", "id": "usr-001" },
"claimedBy": null,
"workflowName": "Expense Approval Flow",
"requester": { "name": "Sarah Chen", "email": "sarah@acme.com" }
}
],
"totalCount": 7,
"page": 1,
"pageSize": 20
}Submitting a Response
When an actor acts on a task (approve, reject, submit form, acknowledge), the response is POSTed to the execution resume endpoint:
POST /api/executions/{executionId}/resume
Authorization: Bearer {token}
Content-Type: application/json
{
"taskId": "3fa85f64-...",
"response": {
"decision": "approved", // for type: approval
"comment": "Looks good, approved.",
"formData": null // for type: form — Atlas Form field values
}
}After a successful POST to /resume, the Process Engine picks up the response and the workflow continues from the HIL node with the actor's decision as node output data.