Queue

The Queue block is a container block in Mandala that processes work items from a durable, shared queue at a configured concurrency. Unlike Loop and Parallel, a Queue is not scoped to a single workflow run: it is a persistent resource that accumulates items across every separate trigger of the parent workflow, and its nested blocks process one queued item at a time, per available concurrency slot.

Overview

The Queue block enables you to:

How It Works

1. Instance created at deploy - Deploying the workflow creates (or updates) one durable queue instance per Queue block. Running or testing the workflow before its first deploy has nowhere durable to enqueue into yet.
2. Items added - Each time the Queue block's own node runs in the parent workflow's execution, it evaluates its Items expression and enqueues the resulting items. Separately, an Agent block anywhere can call queue_push_item at any time to add more, targeting the queue by its configured name.
3. Deduplication (optional) - If a Dedup Key expression is configured, it's evaluated per item before insert; an item whose key already exists for this queue is skipped rather than queued again.
4. Claim and dispatch - Whenever a concurrency slot is free, the oldest eligible pending item is atomically claimed and dispatched for processing. Capacity is enforced with a single conditional update against the queue instance, so it holds correctly no matter how many separate executions or agent pushes are contributing at once.
5. Independent processing - The blocks nested inside the Queue container run as their own completely independent workflow execution -- one per claimed item, with their own execution id -- not as part of the parent workflow's DAG walk that reached the Queue block.
6. Completion or retry - A successful item is marked completed. A failed item is retried with exponential backoff until it either succeeds or exhausts Max Attempts, at which point it becomes dead-lettered. Either way, a slot frees up and the next pending item is claimed immediately.

Configuration Options

How to Use

Creating a Queue

1. Add a Queue block to your canvas
2. Configure Items, Concurrency, Dedup Key, Shared Context, and Max Attempts as needed
3. Drag the blocks that should process each item inside the Queue container, and connect them
4. Deploy the workflow

Adding Items at Runtime

An Agent block can call the queue_push_item tool to push a new item into a Queue block's queue at any time, in addition to whatever the block's own Items expression already enqueues each run. The tool identifies the target by the Queue block's configured name (not its internal id), so give a Queue a clear, distinct name if your workflow has more than one -- nothing currently stops two Queue blocks from sharing a name, and a collision resolves to whichever is active, then whichever was deployed first. queue_push_item also accepts an optional dedupKey, so an agent can avoid pushing the same logical item twice.

Checking Queue Status

The queue_get_status tool returns counts of items that are pending, active, paused, completed, failed (currently retrying), and dead-lettered for a named queue -- across every execution that has contributed to it. Since a Queue is fire-and-forget by construction, this is how an agent (or a human) finds out what happened to items pushed or enqueued earlier, when the result can't simply be handed back inline in the same run.

Referencing the Current Item

Inside the blocks nested in a Queue container, the item being processed and its shared context are available as:

• <queue.item> / <queue.item.someField>: The current item's payload
• <queue.context.someKey>: The shared context snapshot taken when this item was enqueued

These are only resolvable inside a queued item's own independent execution -- referencing <queue.*> anywhere else resolves to nothing.

Example Use Cases

Serializing Calls to a Rate-Limited Dependency

Because the queue is shared and durable, every uploaded invoice lands in the same queue no matter how many arrive concurrently, across however many separate WhatsApp-trigger executions that is. With Concurrency at 1, exactly one item is ever being processed at a time, so the RPA dependency is never hit with more than one request at once -- regardless of upload volume.

Agent-Driven Background Work

Advanced Features

Deduplication

// Dedup Key field -- skip re-queueing the same logical item twice
<item.id>

Deduplication is scoped to the queue instance: matching is against items already in that specific queue, keyed on the expression's evaluated value. If the expression fails to evaluate, or is left empty, that item is never deduplicated.

Retries and Backoff

A failed item is automatically retried with exponential backoff -- an increasing delay between attempts, capped at a fixed maximum -- rather than being re-claimed instantly. This is deliberate: an immediate retry against a still-rate-limited or still-failing dependency just burns the attempt budget without giving it time to recover. Backoff timing itself isn't currently user-configurable; Max Attempts is the one retry parameter you control.

Shared Context Snapshot

// Shared Context field
{
  "tenant": "<variable.tenantId>"
}

This object is captured once per item, at the moment that item is enqueued -- not read live while the item is processing. A batch of items enqueued together all see the same consistent context, even if the block's configuration changes (via redeploy) before every item in that batch has finished.

Concurrency and Ordering

Items are claimed oldest-first as capacity becomes available, and capacity is enforced across every contributing execution, not per-run. A slot frees up the moment an item finishes (success, failure, or dead-letter), so the next pending item is claimed immediately rather than waiting for a periodic sweep.

Human-in-the-Loop Items

Because each queued item runs as its own independent workflow execution, it can contain a human-in-the-loop block like any other workflow. A paused item releases its concurrency slot immediately rather than holding it for as long as the human takes to respond, and resumes -- completing or failing -- once they act.

Nesting

Loop and Parallel blocks nested inside a Queue's own body run normally, self-contained within that single item's independent execution. Nesting a Queue block inside another Queue block is not supported.

Queue vs Loop/Parallel

Inputs and Outputs

Best Practices

• Deploy before relying on it: The queue instance is created at deploy time, so any test run beforehand has nowhere durable to enqueue into.
• Set concurrency to match the downstream dependency, not your traffic: It's a global cap across every trigger of the workflow combined, not a per-run setting -- size it to what the thing you're calling can actually handle.
• Name queues distinctly: queue_push_item and queue_get_status resolve by the Queue block's configured name, and nothing currently prevents two Queue blocks from sharing one.
• Add a Dedup Key whenever the same logical item could arrive twice: Without one, every item -- including retried triggers or duplicate uploads -- is always treated as brand new.
• Raise Max Attempts deliberately: It defaults to 1, i.e. no retry, so a transient failure dead-letters immediately unless you explicitly configure headroom.