Inbox and human tasks

Some steps need a person: checking an invoice the ai command read, approving an order above a limit, filling in a value no system has. A task asks with the humantask command: a form appears in the Inbox of the web app, optionally next to a file (the invoice PDF, a scanned picture). The person checks or corrects the values and presses a button such as Approve or Reject; the task goes on with what they entered and the button they pressed.

#The Inbox

Inbox is in the sidebar for every role. Its badge counts the open tasks you may complete.

• Open lists the tasks waiting for you, oldest first: the title, the task that asked, who it is for, since when it waits and when it expires (in red when less than an hour is left).
• Done lists the latest completed, cancelled and expired tasks, with the button pressed, who pressed it and when.

Click a task to open it. The form is on the left and the file on the right: PDFs and pictures are shown, text files as text, other files can be downloaded. Fields marked * are required; grey fields were filled in by the task and cannot be changed. The buttons at the bottom complete the task; the first one is highlighted, buttons such as Reject are red.

A task is completed once: if two people open it, the second gets Someone else completed this task a moment ago.

#Who sees a task

The task names who may complete it with --assignee: user names and role names, comma separated. A task naming nobody is for everyone; a task naming a role is for everyone who has that role among their roles. Members of the Admin role see every task. A task meant for others does not appear in your Inbox, and opening it by its address answers not found.

#In a task

ai --action:extract --file:$pdf$ --fields:"InvoiceNo, Supplier, Total:number, Date:date" --output:invoice
humantask --action:ask --title:"Check invoice $invoice.InvoiceNo$" --fields:"InvoiceNo, Supplier, Total:number, Date:date, Category:choice(Office|Travel|IT), Note:multiline" --values:$invoice$ --readonly:"InvoiceNo, Supplier" --required:"Total, Category" --outcomes:"Approve, Reject" --assignee:"User" --file:$pdf$ --timeout:1440 --output:review
if --condition:"$review.Outcome$ = `"Approve`""
    log --message:"Approved by $review.CompletedBy$: $review.Total$ ($review.Category$)"
endif

#The form

In the editor, Fields is a list: add a field, give it a name and a type (a choice list takes its options as tags), and tick Required or Read-only; each row shows how to read it afterwards ($review.Total$). Buttons and Who can complete it are picked the same way (roles, and users for administrators). The list writes --fields, --required and --readonly; Edit as text shows them as written.

--fields lists the fields as Name[:type], separated by commas:

Field names are letters, digits and _, so they can be read as $review.Name$. Outcome, CompletedBy, CompletedAt, TaskId and TaskStatus belong to the result and cannot be field names.

#Waiting or not

With create a task can put many forms in the Inbox at once (one per invoice of a queue, say) and collect the answers later with wait, or another run can read them with get.

While a run waits, its agent is busy: it runs no other task. For decisions that can take hours, prefer create and a later run.

#The result

The result record has every field (as the person left it), plus:

A task that is cancelled or expires before anyone completes it makes ask and wait fail with an error the task can catch.

#Security

Completing a task is recorded in the audit log (HUMAN_TASK_COMPLETE) with the button pressed and the field names, never the values. Files are shown in a sandbox: a file cannot run scripts in the web app.