Job
The Job plugin provides a framework for running long-running or background tasks in Brightspot asynchronously, with built-in retry handling and a full audit trail. Use it when work needs to happen outside the request/response cycle—for example importing content from a third-party feed, synchronizing data with an external system, or processing a batch of assets—and you need visibility into whether each unit of work succeeded, failed, or is still in progress.
The Job plugin provides no job asset of its own. A job only appears in the CMS once another feature or plugin extends Job with a concrete implementation.
Key capabilities
- Asynchronous execution of background tasks, run in configurable batches and in parallel.
- A status state machine (pending, priority, retry, polling, success, permanent failure, max retries) that drives when and how often a task is attempted again.
- An audit log recorded on every job, capturing each status transition with a timestamp and message.
- Job runners that can be enabled or disabled, and pinned to a specific host, without a code deploy.
- A searchable, filterable job listing in the CMS tool, including a completion status filter for finding successful or failed jobs.
How it works
A job execution task runs on a repeating schedule and looks for jobs in the pending, priority, retry, or polling state. For each enabled job runner allowed to run on the current host, it selects a batch of matching jobs and executes them—in parallel, if the job runner allows it. After each execution, the task records the result as a new entry in the job's activity log, updates the job's status, and saves it. Jobs whose status allows retries are picked up again after a configurable delay, up to a maximum number of attempts; jobs that exceed that maximum are moved to a max-retries state instead of being retried indefinitely.
Use cases
Content ingestion
A site periodically receives content—articles, product data, or media—from an external feed or file drop. A job is queued for each incoming item. The job runner parses and validates the item, creating or updating the corresponding asset, and reports success or a specific failure reason (for example, a malformed file or a rejected record) so the ingestion can be retried or investigated.
Third-party API synchronization
A site keeps data in sync with an external system, such as inventory levels or subscriber status. Each sync attempt is represented as a job. Because API calls can be transient failures, the job runner returns a retryable status on network errors, and the job execution task automatically retries after a configurable delay, only escalating to a permanent failure once the maximum number of retries is exceeded.
Long-running or asynchronous operations
Some external operations do not complete immediately—for example, a request to a video transcoding service or an external export tool. The job runner submits the request and returns a polling status. The job execution task periodically checks back on the job on a configurable interval until the external operation reports it is done.
Who this documentation is for
- Searching and monitoring jobs—for anyone who needs to check on the status of a running or completed job in the CMS.
- Technical reference—for developers implementing a job execution pipeline with this plugin.