Work queues

A work queue holds work items (one invoice, one order, one request) that a task or a person adds and one or more robots process one at a time, each item ending as completed or failed on its own, with retries.

#How queues work

• A queue has a name, a description and a number of Retries.
• A work item carries its data (a record or any value), an optional reference (a business key such as the invoice number) and a priority.
• A producer adds items: a task with queue --action:add, a person on the Queues page, or another system through the API.
• A worker task takes items one at a time. Several agents can work the same queue at once; an item is never given to two runs.
• Items are taken by priority (highest first), then in the order they arrived.

Queues are stored in the Botream database; no extra component is needed.

#Item statuses

#References prevent duplicates

When you add an item with a reference, and an item with the same reference is already New, In progress or Completed, the item is not added again. A Failed item with that reference does not block a new one, so you can submit it again.

#Create a queue

Open Queues and click New queue:

• Name: tasks refer to the queue by this name, for example --queue:Invoices.
• Description: what the items are and which task processes them.
• Retries: how many times a failed item goes back to the queue before it stays failed (0: never, up to 100).

The list shows each queue with its item counts (new, in progress, completed, failed), its Retries and when it changed. Users with the Manage queues permission (Developer by default) can edit or delete a queue.

Warning: Deleting a queue deletes all its items. Tasks that use it fail until a queue with that name exists again.

#Add items from a task

Use queue --action:add. --output receives the new item's id.

loop --type:datatable --table:$invoices$ --variable:invoice
    queue --action:add --queue:Invoices --data:$invoice$ --reference:$invoice.No$ --priority:1 --output:itemId
endloop

• --data: the item, a record ($invoice$) or any value.
• --reference (optional): the business key; see above.
• --priority (optional, default 0): higher is taken first.

#Process items with a loop

Most worker tasks use loop --type:queue. It takes one item per round until the queue has no new items:

loop --type:queue --queue:Invoices --variable:item
    log --message:"Invoice $item.Data.InvoiceNo$ (attempt $item.Attempt$)"
    runtask --name:"BookInvoice" --invoice:$item.Data$
endloop

• A round that ends normally completes its item.
• A round that fails with an error fails its item, and the loop goes on with the next one, so one bad item never stops the batch.
• A system error (element not found, timeout, network) puts the item back while the queue has retries left. A business error (raised with throw) fails the item for good: retrying would not change the data. See Error handling.
• Inside the round you can close the item yourself with queue --action:complete or queue --action:fail; the loop then leaves it alone.
• break ends the loop after the current item.

The loop variable is a record:

#The queue command

queue has five actions. See the queue command reference for every parameter.

#Processing items by hand

Instead of the loop, you can take and close items yourself:

queue --action:next --queue:Invoices --output:item
if --type:boolean --value:$item.Found$ --is:false
    log --message:"Nothing to do"
else
    try
        runtask --name:"BookInvoice" --invoice:$item.Data$ --bookingNoTo:bookingNo
        queue --action:complete --item:$item$ --result:$bookingNo$
    catch --error:err
        queue --action:fail --item:$item$ --reason:$err.Message$ --retry:true
    endtry
endif

• next returns a record with Found, Id, Reference, Data, Attempt and Priority. Found is false when the queue has no new item.
• fail without --retry is final: use it for business decisions (the invoice is invalid). With --retry:true the item goes back to the queue while the queue has retries left; use it for technical failures.
• Only the run that took an item can complete or fail it.

queue --action:count --queue:Invoices --status:new --output:pending
log --message:"$pending$ invoices are waiting"

Note: The queue command needs the server: the agent asks Botream Server for every action, and the server checks that the agent is running that execution.

#Retries

An item's Attempt counts its processing rounds. When an item fails with a retry allowed, it goes back to New as long as its attempt is not greater than the queue's Retries; after that it stays Failed with the reason. With Retries set to 2, an item is tried at most three times.

#When a run ends early

When an execution ends while it still has items In progress (it was stopped, it crashed, or its agent was lost), the server releases them: each goes back to New, or to Failed when it has no retries left, with the reason The run ended before the item was completed.

#Manage items on the Queues page

Click the items button (or double-click a queue) to open its items:

• Filter by status: All, New, In progress, Completed or Failed, each with its count.
• Search by Reference.
• Each item shows its reference (or number), when and by whom it was added, its status, attempt and priority, its Data (hover for the whole value) and its Outcome: the error, the result, or a link to the execution processing it.

Users with Manage queues can also:

• Back to the queue: put a Failed item back to New with its attempts reset.
• Delete an item that is not in progress.
• Add items: paste JSON, one item or a list.

#Bulk load items

In Add items, an item is either its data itself, or an object with data, reference and priority:

[
  {"data": {"invoiceNo": "A-17", "total": 120}, "reference": "A-17"},
  {"data": {"invoiceNo": "A-18", "total": 80}, "reference": "A-18", "priority": 5}
]

Tasks read these fields as $item.Data.invoiceNo$. Up to 5,000 items can be added at once. Items whose reference is already in the queue are skipped, and the confirmation tells you how many.

#Who can use queues

Creating, changing and deleting queues is recorded in the audit log.

Tip: Measure how much work a queue loop does with --measure:true; see Performance measurement.