Flow Control commands
step · runtask · stoptask · pausetask · resumetask · queue · humantask
step Step
Groups commands into a named step. It does nothing itself: the commands inside run in order.
Block command: step … endstep.
Parameters
| Parameter | Value | Default | Description |
|---|---|---|---|
--description | text | What this step does, e.g. "Log in to the portal" |
runtask Run task
Calls another task. Map inputs with --inputName:value and outputs with --outputNameTo:variable.
Parameters
| Parameter | Value | Default | Description |
|---|---|---|---|
--name required | text | Task to call: its name, or its folder path when several folders have a task of that name (Finance/Invoices/Import) |
Examples
runtask --name:"ProcessOrder" --orderId:$currentOrder$ --customerName:$name$ --resultTo:taskResult --totalAmountTo:amountstoptask Stoptask
Stops the run here, successfully: the commands after it do not run (finally sections still do) and the outputs are returned. With --name it stops the running runs of another task instead.
Parameters
| Parameter | Value | Default | Description |
|---|---|---|---|
--message | text | Why the run stops, written to the log | |
--scope | one of run, task | run | run: the whole run, including the tasks that called this one. task: only this task; a called task returns to its caller |
--name | text | Another task to stop: every run of it that is waiting or running, on any agent (its name, or folder path when several folders have it) | |
--output | variable name | With --name: variable that receives how many runs were stopped |
Examples
stoptask --message:"No orders today" # ends the run, Completed (finally runs, catch does not see it)
stoptask --scope:task # ends only this task: a called task returns to its caller
pausetask --message:"Check the invoice" --timeout:600
stoptask --name:"Finance/Import" --output:stopped
pausetask --name:Export
resumetask --name:Exportpausetask Pausetask
Pauses the run until someone resumes it: Run in the progress window on the agent machine, Resume on the run’s page in the web app, or resumetask. With --name it pauses the running runs of another task instead.
Parameters
| Parameter | Value | Default | Description |
|---|---|---|---|
--message | text | Shown while the run waits, e.g. "Check the invoice, then press Run" | |
--timeout | number | 0 | Seconds after which the run goes on by itself; 0 waits until resumed |
--name | text | Another task to pause: every run of it that is running, on any agent (resume it with resumetask or in the web app) | |
--output | variable name | With --name: variable that receives how many runs were paused |
resumetask Resumetask
Resumes the paused runs of another task (paused by pausetask, in the progress window or in the web app).
Parameters
| Parameter | Value | Default | Description |
|---|---|---|---|
--name required | text | The task to resume: its name, or folder path when several folders have it | |
--output | variable name | Variable that receives how many runs were resumed |
queue Queue
Work queues: items (invoices, orders…) added by one task and processed one at a time by others, with retries. Queues are created on the Queues page.
Actions (--action)
--action:add
Adds a work item; --output receives its id.
| Parameter | Value | Default | Description |
|---|---|---|---|
--queue required | text | Name of the work queue (Queues page) | |
--data required | any value | The item: a record ($invoice$) or any value | |
--reference | text | Business key (invoice number…): an item with the same reference that is new, in progress or completed is not added again | |
--priority | number | 0 | Higher runs first |
--output | variable name | Variable that receives the result |
--action:next
Takes the next new item (highest priority, oldest first) and marks it in progress for this run; the record has Found false when the queue is empty.
| Parameter | Value | Default | Description |
|---|---|---|---|
--queue required | text | Name of the work queue (Queues page) | |
--output required | variable name | Record: Found, Id, Reference, Data, Attempt, Priority |
--action:complete
Marks the item taken by this run as completed.
| Parameter | Value | Default | Description |
|---|---|---|---|
--item required | $variable$ | The work item taken with queue --action:next or the loop variable of loop --type:queue | |
--result | any value | Outcome kept with the item |
--action:fail
Marks the item as failed. By hand this is final (a business decision); with --retry:true it goes back to the queue while the queue has retries left.
| Parameter | Value | Default | Description |
|---|---|---|---|
--item required | $variable$ | The work item taken with queue --action:next or the loop variable of loop --type:queue | |
--reason required | text | Why it failed, e.g. $err.Message$ of a catch --error:err | |
--retry | true / false | false | true: a technical failure, try the item again later (within the queue’s retries) |
--action:count
| Parameter | Value | Default | Description |
|---|---|---|---|
--queue required | text | Name of the work queue (Queues page) | |
--status | one of new, inprogress, completed, failed | All items when empty | |
--output required | variable name | Variable that receives the result |
Examples
queue --action:add --queue:Invoices --data:$invoice$ --reference:$invoice.No$ --priority:1 --output:itemId
queue --action:next --queue:Invoices --output:item
if --type:boolean --value:$item.Found$ --is:false
log --message:"Nothing to do"
endif
queue --action:complete --item:$item$ --result:$bookingNo$
queue --action:fail --item:$item$ --reason:$err.Message$
queue --action:count --queue:Invoices --status:new --output:pendinghumantask Human task
Asks a person in the Inbox of the web app: a form to check, correct or fill in (e.g. an invoice the ai command read, next to its PDF) and buttons such as Approve and Reject. The result record has the fields, Outcome (the button pressed), CompletedBy, CompletedAt, TaskId and TaskStatus.
Actions (--action)
--action:ask
Creates the task and waits until someone completes it; --output receives the result record.
| Parameter | Value | Default | Description |
|---|---|---|---|
--title required | text | What the person is asked, e.g. "Check invoice $invoice.InvoiceNo$" | |
--fields required | text | The form: Name[:type], comma separated; types text (default), multiline, number, date, boolean, choice(A|B|C). E.g. "InvoiceNo, Total:number, Date:date, Status:choice(Open|Closed)" | |
--values | any value | Values to start with: a record ($invoice$) or {"Total": 120} | |
--required | text | Fields that must be filled in, comma separated | |
--readonly | text | Fields shown but not changeable, comma separated | |
--outcomes | text | Done | The buttons, comma separated, e.g. "Approve, Reject"; the one pressed is $result.Outcome$ |
--assignee | text | Who may complete it: user names and role names, comma separated; anyone with the Inbox when empty | |
--description | text | Instructions shown above the form | |
--file | text | A file on the agent machine shown next to the form: PDF, picture or text (up to 10 MB) A file on the agent machine. | |
--timeout | number | 0 | Minutes to wait; then the command fails (the task of ask expires). 0 waits without limit |
--output required | variable name | Record: the fields, Outcome, CompletedBy, CompletedAt, TaskId, TaskStatus |
--action:create
Creates the task and goes on at once; --output receives its id, for wait or get later.
| Parameter | Value | Default | Description |
|---|---|---|---|
--title required | text | What the person is asked, e.g. "Check invoice $invoice.InvoiceNo$" | |
--fields required | text | The form: Name[:type], comma separated; types text (default), multiline, number, date, boolean, choice(A|B|C). E.g. "InvoiceNo, Total:number, Date:date, Status:choice(Open|Closed)" | |
--values | any value | Values to start with: a record ($invoice$) or {"Total": 120} | |
--required | text | Fields that must be filled in, comma separated | |
--readonly | text | Fields shown but not changeable, comma separated | |
--outcomes | text | Done | The buttons, comma separated, e.g. "Approve, Reject"; the one pressed is $result.Outcome$ |
--assignee | text | Who may complete it: user names and role names, comma separated; anyone with the Inbox when empty | |
--description | text | Instructions shown above the form | |
--file | text | A file on the agent machine shown next to the form: PDF, picture or text (up to 10 MB) A file on the agent machine. | |
--timeout | number | 0 | Minutes after which the task expires; 0: it stays until completed |
--output required | variable name | Variable that receives the result |
--action:wait
Waits until the task is completed (or cancelled, or expired); --output receives the result record.
| Parameter | Value | Default | Description |
|---|---|---|---|
--id required | number | The task id from humantask --action:create | |
--timeout | number | 0 | Minutes to wait; then the command fails (the task of ask expires). 0 waits without limit |
--output required | variable name | Record: the fields, Outcome, CompletedBy, CompletedAt, TaskId, TaskStatus |
--action:get
Reads the task now without waiting: TaskStatus is Open, Completed, Cancelled or Expired.
| Parameter | Value | Default | Description |
|---|---|---|---|
--id required | number | The task id from humantask --action:create | |
--output required | variable name | Variable that receives the result |
--action:cancel
Takes an open task out of the Inbox.
| Parameter | Value | Default | Description |
|---|---|---|---|
--id required | number | The task id from humantask --action:create |
Examples
humantask --action:ask --title:"Check invoice $invoice.InvoiceNo$" --fields:"InvoiceNo, Total:number, Date:date, Category:choice(Office|Travel|IT)" --values:$invoice$ --readonly:InvoiceNo --required:"Total, Category" --outcomes:"Approve, Reject" --assignee:"User" --file:$pdf$ --timeout:1440 --output:review
humantask --action:create --title:"Confirm the address" --fields:"Street, City, Note:multiline" --output:taskId
humantask --action:wait --id:$taskId$ --timeout:60 --output:answer
humantask --action:get --id:$taskId$ --output:state
humantask --action:cancel --id:$taskId$