Queue Job
| Name (singular): | Queue Job |
| Name (plural): | Queue Jobs |
| Alias (uri): | queue_job |
| Identifier (ID): | cerb.contexts.queue.job |
- Progress tracking
- Log
- Cancellation
- Permissions
- Records API
- Dictionary Placeholders
- Search Query Fields
- Worklist Columns
A queue job groups a batch of queue messages under a single record so workers can monitor progress against long-running background work. Jobs are initiated by a worker (e.g. a bulk update, worklist export, search re-index) and complete when all of their linked messages have been processed. Opening a job's card displays a live progress widget until it finishes.
A singleton_key ensures that only one job with a given key can be active at a time – for example, search re-indexing for a particular index.
Progress tracking
The job's count_* totals sum each message's cardinality (its work units) rather than counting raw messages. A message's cardinality defaults to 1, so single-op messages behave the same as a simple count. Producers that bundle many records per message – such as cerb.records.bulk_update, cerb.records.export, and search re-indexing – can set a higher cardinality (typically 100), and the monitor will report progress in record-equivalent units.
Log
Each successful or failed queue message can write a summary entry into a permanent job log alongside the live counters. The log captures a short message plus arbitrary metadata – for instance, the affected record_ids on a worklist bulk update – and survives after the job completes for an audit trail.
Cancellation
A queue job can be paused (stop processing but keep pending messages), canceled (immediately remove pending messages and mark the job done), or deleted (remove the job and its log).
Permissions
Only the worker who initiated a queue job and administrators can view the job's details or download attachments linked to it (e.g. an export's resulting file). Other workers can see the job exists but not its contents.
Records API
These fields are available in the Records API and packages:
| Req'd | Field | Type | Notes |
|---|---|---|---|
created_at |
timestamp | The date/time when this record was created | |
id |
number | The ID of this queue job | |
links |
links | An array of record type:id tuples to link to. Prefix with - to unlink. |
|
name |
text | The name of this queue job | |
| x | queue_id |
number | The ID of the parent queue |
singleton_key |
text | An optional unique key that prevents multiple jobs from running concurrently | |
status_id |
number | The status of the job: 0 running, 1 paused, 2 done |
|
updated_at |
timestamp | The date/time when this record was last modified | |
worker_id |
number | The ID of the worker who initiated this job |
Dictionary Placeholders
These placeholders are available in dictionaries for automations, snippets, and API responses:
| Field | Type | Description |
|---|---|---|
_context |
text | Record type extension ID |
_label |
text | Label |
_type |
text | Record type alias |
count_available |
number | Work units still waiting to be processed |
count_done |
number | Work units that completed successfully |
count_failed |
number | Work units that failed |
count_inflight |
number | Work units currently being processed |
count_total |
number | Total work units in this job |
created_at |
date | Created |
id |
number | Id |
name |
text | Name |
queue_id |
number | Queue ID |
record_url |
text | Record URL |
singleton_key |
text | Singleton key |
status_id |
number | Status |
updated_at |
date | Updated |
worker_id |
number | Worker ID |
These optional placeholders are also available with key expansion in dictionaries and the API:
| Field | Type | Description |
|---|---|---|
comment_count |
number | Comment count on the record |
comments |
comments | Comments |
custom_<id> |
mixed | Custom Fields |
links |
links | Links |
queue_ |
record | The parent Queue |
watchers |
watchers | Watchers |
worker_ |
record | The Worker who initiated the job |
Search Query Fields
These filters are available in queue job search queries:
| Field | Type | Description |
|---|---|---|
count.available: |
number | Available count |
count.done: |
number | Done count |
count.failed: |
number | Failed count |
count.inflight: |
number | In-flight count |
count.total: |
number | Total count |
created: |
date | Created |
fieldset: |
record | Fieldset |
id: |
number | Id |
links: |
links | Record Links |
name: |
text | Name |
queue: |
record | Queue |
singleton.key: |
text | Singleton Key |
status: |
text | Status (running, paused, done) |
status.id: |
number | Status ID |
updated: |
date | Updated |
worker: |
record | Worker |
Worklist Columns
These columns are available on queue job worklists:
| Column | Description |
|---|---|
cf_<id> |
Custom Field |
qj_count_available |
Available count |
qj_count_done |
Done count |
qj_count_failed |
Failed count |
qj_count_inflight |
In-flight count |
qj_count_total |
Total count |
qj_created_at |
Created |
qj_id |
Id |
qj_name |
Name |
qj_queue_id |
Queue |
qj_singleton_key |
Singleton Key |
qj_status_id |
Status |
qj_updated_at |
Updated |
qj_worker_id |
Worker |