Jobs — Reference
The Jobs surface is the background-task plane for SGEN. It owns the queue of work that runs outside the request cycle — scheduled reports, deferred sends, batch imports, retries, dead-letter triage — and exposes the visibility and control needed to operate that queue without touching the worker host.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a monitoring layer. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Jobs lives under the System module in SG-Admin. The module renders three primary views — the queue list, the per-job detail view, and the schedule list — and exposes a small set of write operations for re-run, cancel, retry, dead-letter triage, and schedule edit.
The module is paired by convention: one half renders the views and prepares the queue data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
A secondary surface — dead-letter — lives adjacent to the queue list. The dead letter is the holding pen for jobs that failed past their retry budget. It is a separate surface because the actions available against a dead-lettered job (manual replay, permanent dismissal, edit-and-replay) differ from the actions available against a live queue entry.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → System → Jobs
- URL prefix:
/sg-admin/jobs/ - View templates:
application/views/Admin/System/Jobs/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → System → Jobs [ Queue | Schedules ] │├──────────────────────────────────────────────────────────────────────┤│ ID Task State Attempts Next run ││ ──── ──────────────────── ────────── ──────── ──────────────────││ 4218 email.digest running 1 of 3 — ││ 4217 report.weekly queued 0 of 3 in 2 minutes ││ 4216 import.products failed 3 of 3 dead-letter ││ 4215 cache.warm succeeded 1 of 3 — ││ 4214 webhook.dispatch retrying 2 of 5 in 1 minute ││ ││ Throughput (1h): 142 succeeded · 6 failed · 2 dead-lettered ││ [ Re-run ] [ Cancel ] [ Open detail ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Jobs surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List jobs
Returns the queue paginated, with task name, state, attempt count, scheduled-for timestamp, last-error excerpt, and originating operator (where applicable). Supports filter by state, by task name, and by date range. The default view excludes succeeded jobs older than the retention window — they remain queryable via the explicit filter.
View job detail
Returns the full record for a single job — payload, full error log, attempt history with per-attempt timing and exit reason, the schedule entry that produced it (if applicable), and the worker that last picked it up. The payload is rendered with sensitive fields masked according to the per-task masking rule.
Re-run job
Resets a job's state to queued, clears the attempt counter, and returns it to the live queue. Available for jobs in failed, succeeded, or dead-letter state. The re-run reuses the original payload; if the payload referenced state that has since changed, the operator is responsible for confirming the resulting work is still valid.
Cancel job
Marks a queued or retrying job as cancelled. The job does not execute. A cancelled job is not retried. Cancellation of a running job is best-effort — the surface flags the job for cancellation, and the worker honors the flag at the next safe checkpoint. Tasks without checkpoints run to completion and are marked cancelled afterwards.
Retry now
For a job in the retrying state with a future scheduled-for timestamp, brings the scheduled run forward to immediate. The retry budget is not consumed by the timing change.
Send to dead letter
Moves a job from the live queue to the dead-letter holding pen without running further retries. Manual dead-lettering is used when an operator has identified a job as broken and wants to triage it without waiting for the retry budget to exhaust.
Replay from dead letter
Returns a dead-lettered job to the live queue with a fresh attempt counter. Same shape as re-run, scoped to the dead-letter state.
Edit and replay
Reads a dead-lettered job into the schedule form, allows edits to the payload, and submits a new queue entry from the edited shape. The original dead-lettered record is retained for audit.
Dismiss
Permanently removes a job from the dead letter. The record is purged from the live store but retained in the audit log. Dismiss is irreversible.
Create schedule
Registers a recurring job — task name, cron expression or interval, payload template, retry budget, retention setting. The schedule emits a new queue entry on each tick.
Edit schedule
Updates an existing schedule. Pausing a schedule is a special edit — the schedule remains registered but emits no queue entries until resumed.
Run schedule now
Manually emits a queue entry from a schedule out-of-band. The next regular tick is unaffected.
View throughput stats
Returns aggregate counts over a configurable window — succeeded, failed, dead-lettered, cancelled — broken down by task name. Read-only; used by the queue dashboard and by external monitoring integrations.
Data model
A job record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
task | string | Task slug. Routes the payload to a handler. |
payload | object | Task-specific. Sensitive fields masked in views per the task masking rule. |
state | enum | queued, running, retrying, succeeded, failed, dead-letter, cancelled. |
attempts | integer | Count of attempt records below. |
max_attempts | integer | Retry budget. From the schedule or the task default. |
attempt_history | array | One entry per attempt — started_at, finished_at, exit, error excerpt. |
scheduled_for | timestamp | Earliest allowed run time. Used for delays and backoff. |
priority | enum | low, normal, high. Routes within the worker pool. |
schedule_id | integer | Optional. Set when the job was emitted by a schedule. |
originating_user_id | integer | Optional. Set when an operator triggered the job. |
created_at | timestamp | Set on queue insert. |
updated_at | timestamp | Touched on state change. |
queued → running → (succeeded | failed). failed → retrying → queued until the attempt budget is exhausted, after which failed → dead-letter. Manual operations can produce cancelled from any non-terminal state and can rewind from dead-letter to queued.Schedule record shape: a separate model. Holds the task slug, the cron or interval expression, the payload template, the retry budget defaulted onto emitted jobs, and an enable flag.
JOB STATE MACHINEqueued ───▶ running ───┬─▶ succeeded▲ ││ └─▶ failed│ ││ ▼└───────── retrying ◀──── (under budget)│▼(budget exhausted)│▼dead-letter ──▶ replay → queued│└─▶ dismiss → (purged)any non-terminal ──▶ cancelled (manual or best-effort)Permissions
Access to the Jobs surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Jobs surface.
Layer 2 — per-action capability. Within SG-Admin, each Jobs action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List jobs | ✔ | ✔ | ✔ |
| View job detail | ✔ | ✔ | (masked) |
| Re-run job | ✔ | ✔ | — |
| Cancel job | ✔ | ✔ | — |
| Send to dead letter | ✔ | — | — |
| Replay from dead letter | ✔ | — | — |
| Edit and replay | ✔ | — | — |
| Dismiss | ✔ | — | — |
| Create schedule | ✔ | — | — |
| Edit schedule | ✔ | — | — |
| Run schedule now | ✔ | ✔ | — |
| View throughput stats | ✔ | ✔ | ✔ |
Payload masking. Each registered task declares which payload fields are sensitive. Sensitive fields are masked in the detail view for every role except Administrator, regardless of the underlying capability. The audit log records the masked shape for non-administrator views.
Audit. Every write — re-run, cancel, dead-letter, dismiss, schedule create, schedule edit, manual run — emits an Activity Log entry. The log records the acting operator, the target job or schedule, and the shape of the change. Automatic state transitions emitted by the worker are recorded in the job's attempt history but do not write to the Activity Log to keep that log focused on operator action.
JOB OPERATION REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Payload masking │ non-admin → mask sensitive│ (per-task masking rule) │ admin → full view└─────────────┬─────────────┘│▼action executes│▼Activity Log entry(operator-driven changes only)Related references
- System — Reference. Hosts the Jobs surface alongside cache, cron, and maintenance surfaces. The worker process configuration lives here.
- Settings — Reference. Owns the default retry budget, retention window, and per-environment worker concurrency.
- Activity Log — Reference. Stores audit events emitted by Jobs writes.
- Webhooks — Reference. Webhook dispatch is a registered task; failed dispatches surface in the Jobs queue under the
webhook.dispatchtask name. - Imports — Reference. Batch imports run as jobs; the import surface kicks off the work and the Jobs surface tracks the run.
- Reports — Reference. Scheduled reports register as schedules; each tick emits a job that produces the report artifact.
/docs/system/jobs.