Datastore Queues
Datastore Queues let Wrkflows hand off work to each other. Use them when one Wrkflow needs to add items for another Wrkflow to process, when you want items processed one at a time in a set order, or when you need to track whether each item is waiting, in progress, complete, or failed.
Queues are separate from Datastore Tables. Tables are general-purpose row storage you can view and edit in the Datastore UI. Queues are built for work-item tracking: each item has a status, a priority, and optional tags so you can route and monitor work across Wrkflows.
Five Datastore queue Wrk Actions cover the full queue lifecycle. This page explains how queues work and when to use each action.
How queues work
Queue names
Each queue is identified by a Queue name you provide (for example, Orders or Lead enrichment). Queues are account-level, like environment variables and tables. Any Wrkflow in your account can read from or write to the same queue.
When you Add item to Datastore queue, you can enable Auto-create queue? (default: true) to create the queue automatically on first use. If auto-create is disabled and the queue does not exist, the action fails.
Queue item fields
Every queue item has a consistent set of fields. Most actions return these fields as outputs.
| Field | Description |
|---|---|
| Queue Item ID | Unique identifier for the item. Use this with Update queue item in Datastore and Delete queue item from Datastore. |
| Item name | Optional label for the item. |
| Status | Current lifecycle status (see below). |
| Data | JSON payload for the work item. Store whatever your Wrkflow needs to process the item. |
| Tags | List of text tags for filtering and routing. |
| Priority | Processing order. Lower numbers are processed first. Default is 0. |
| Attempt count | How many times the item has been retrieved for processing. |
| Defer until (UTC) | Item is not picked up until this UTC timestamp has passed. |
| Creation date time (UTC) | When the item was created. |
| Last update date time (UTC) | When the item was last modified. |
| Started date time (UTC) | When processing started. |
| Completed date time (UTC) | When the item was marked complete. |
| Exception date time (UTC) | When the item was marked as an exception. |
| Notes | Freeform notes, such as error details or status commentary. |
All timestamps are stored and returned in UTC.
Status lifecycle
Queue items move through four statuses:
| Status | Meaning |
|---|---|
| Pending | Waiting to be retrieved and processed. |
| In progress | Currently being processed. Set when Retrieve next queue item from Datastore picks up the item. |
| Complete | Successfully processed. |
| Exception | Processing failed. |
Typical flow:
- Add item to Datastore queue creates an item with status Pending.
- Retrieve next queue item from Datastore picks up the next eligible item and sets its status to In progress.
- Your Wrkflow processes the item.
- Update queue item in Datastore marks the item Complete or Exception, or resets it to Pending if you want to try again.
Retrieval order
Retrieve next queue item from Datastore picks the next eligible item using:
- Priority — lower numbers first
- Creation date time (UTC) — oldest first, within the same priority
Only one Wrkflow run can pick up a given item at a time, so the same item is never processed twice at once.
An item is eligible when:
- Its status matches the Item status to retrieve setting
- Its Defer until (UTC) time has passed (if set)
- It has all Required tags (if any are specified)
Data input modes
Add item to Datastore queue and Update queue item in Datastore support two ways to provide the Data payload:
| Mode | Input | When to use |
|---|---|---|
| Custom fields (default) | Use custom fields for Data? = true | Map individual fields with typed inputs. Easier to configure in the Wrkflow designer. |
| JSON blob | Use custom fields for Data? = false | Provide a single JSON object. Useful for dynamic or complex payloads. |
On Update queue item in Datastore, Merge data? (default: true) controls whether new data is combined with the existing payload or replaces it entirely. Merge tags? (default: true) works the same way for tags.
When updating, leaving an input blank does not clear the corresponding field. You can update only the fields you need.
Fields to Capture
After Retrieve next queue item from Datastore, you can use Fields to Capture to expose individual keys from the Data JSON payload as named outputs for downstream Wrk Actions.
Common patterns
One Wrkflow adds work, another processes it
The most common pattern splits work across two Wrkflows:
Producer Wrkflow — runs when new work arrives (webhook, email trigger, scheduled scan, etc.):
- Add item to Datastore queue with the work payload in Data, and optional Priority and Tags
Consumer Wrkflow — runs on a schedule or trigger to process the queue:
- Retrieve next queue item from Datastore
- Process the item (enrichment, API call, notification, etc.)
- Update queue item in Datastore — set status to Complete on success or Exception on failure
- Optionally Delete queue item from Datastore after successful processing
Map the Queue Item ID from the retrieve step into the update step so you update the correct item.
Retrying failed items
When processing fails, update the item to Exception instead of Complete. To try again later:
- Configure Retrieve next queue item from Datastore with Item status to retrieve set to Exception only or Pending and exception
- Set Maximum attempt count to limit how many times a failed item is retried
- To re-queue an item manually, update it back to Pending
Deferred processing
Set Defer until (UTC) when adding or updating an item to delay when it becomes eligible for retrieval. Useful for scheduled follow-ups, processing windows, or waiting before a retry.
Monitoring and reporting
Use Search queue items in Datastore to check queue health, build alerts, or audit activity. Filter by status, tags, date ranges, and priority. By default the search returns full item data; set Exclude data? to true when you only need metadata and want to keep results lean.
Wrk Actions
All queue Wrk Actions belong to the Datastore application. None require credentials. Configure inputs and review outputs directly on each Wrk Action in the Wrkflow designer.
| Wrk Action | What it does |
|---|---|
| Add item to Datastore queue | Add a new item to a queue. Set the payload, priority, tags, and optional defer time. |
| Retrieve next queue item from Datastore | Pick up the next eligible item from a queue. The item moves to In progress so other runs do not process it at the same time. |
| Update queue item in Datastore | Change an item's status, data, priority, tags, or other fields by Queue Item ID. |
| Delete queue item from Datastore | Remove an item from a queue by Queue Item ID. |
| Search queue items in Datastore | Find items using filters such as status, tags, date ranges, and priority. |
Queues vs tables
Both queues and tables live in Datastore and persist across Launches, but they serve different purposes:
| Queues | Tables | |
|---|---|---|
| Best for | Handing off work between Wrkflows with built-in status tracking | Structured records, lookups, logging, UI-visible data |
| Retrieval | Pick up the next item in priority order | Query or retrieve by ID or filters |
| Status tracking | Built-in pending, in progress, complete, and exception | You define columns yourself |
| UI | Managed through Wrk Actions | Editable grid in the Datastore Tables tab |
| Wrk Actions | Five dedicated queue actions (this page) | Create, retrieve, update, delete, and query row actions |
If you need a simple shared list you edit manually in the UI, use a Table. If you need one Wrkflow to pass work to another with status tracking, use a Queue.