Claiming a Task
Claiming is an optional mechanism that locks a task to a single actor in multi-actor scenarios. When a task is assigned to a role group, multiple team members see it — claiming it signals intent and prevents duplicate responses.
Why Claiming Exists
When a Flow Studio HIL node is configured with a role assignment (e.g., "Finance Approvers" role) rather than a specific user, all members of that role see the task in their inboxes. Without claiming, two colleagues could both attempt to act on the same task simultaneously — causing a race condition.
Claiming solves this: the first actor to claim the task locks it. Other actors see the task but with action buttons disabled, showing "Claimed by [Name]". The claimer can release the claim if they cannot complete it, making it available again.
Claiming is configured per-workflow in the Flow Studio HIL node settings (requireClaim: true/false). For single-actor tasks (assigned to a specific user), claiming is unnecessary and is typically disabled.
Claim Lifecycle
Task Assigned to Role
HIL node suspends workflow. Task appears in inbox of all members of the "Finance Approvers" role. Task status: pending, claimedBy: null.
Actor Claims Task
Actor clicks Claim. WorkDesk sends POST /api/workdesk/tasks/{taskId}/claim. Task status: claimed, claimedBy: "usr-001". Other actors see the task as "Claimed by Alice".
Actor Acts or Releases
The claimer acts on the task (Approve/Submit/Acknowledge) → task completes. Or the claimer clicks Release Claim → task returns to pending and is visible again to all role members.
Workflow Resumes
After action, the workflow receives the response and continues. The task is marked completed and moves to the Completed Tasks history.
Claiming API
// Claim a task (lock to authenticated actor)
POST /api/workdesk/tasks/{taskId}/claim
Authorization: Bearer {token}
// Response: 200 OK
{ "taskId": "...", "claimedBy": "usr-001", "claimedAt": "2026-05-25T11:00:00Z" }
// Response: 409 Conflict (already claimed by someone else)
{ "error": "ALREADY_CLAIMED", "claimedBy": { "name": "Bob Smith", "claimedAt": "..." } }
// Release a claim
DELETE /api/workdesk/tasks/{taskId}/claim
Authorization: Bearer {token}
// Response: 200 OK
{ "taskId": "...", "claimedBy": null }Claim Timeout
Claims can have an optional timeout. If a task is claimed but not acted on within the configured timeout period (e.g., 30 minutes), the claim is automatically released. This prevents tasks from being locked indefinitely if an actor walks away without completing or releasing the claim.
| Claim Configuration | Flow Studio Setting | Default |
|---|---|---|
| Claiming required? | hilNode.requireClaim | false |
| Claim timeout | hilNode.claimTimeoutMinutes | null (no timeout) |
| Auto-assign after timeout? | hilNode.autoAssignOnTimeout | false |
Administrators can forcibly release a claim via the Admin Panel — useful when an actor is absent and the task is urgently needed. The force-release creates an audit log entry.
React UI — Claim Button
function TaskClaimButton({ task }: { task: HilTask }) {
const { claim, release } = useTaskActions();
const currentUserId = useCurrentUser().id;
if (!task.requireClaim) return null;
if (task.claimedBy === null) {
return <button onClick={() => claim(task.taskId)}>Claim Task</button>;
}
if (task.claimedBy === currentUserId) {
return <button onClick={() => release(task.taskId)}>Release Claim</button>;
}
return (
<div className="claimed-indicator">
Claimed by {task.claimerName}
{task.claimedAt && <span> at {formatRelative(task.claimedAt)}</span>}
</div>
);
}