Job Scheduling and Notifications
The job system provides asynchronous task execution with scheduling, worker management, and notification delivery. Jobs are the primary mechanism for background processing — anything from score recalculation to data imports to webhook delivery.
Architecture
Programs
A program defines a type of work that can be executed. Programs are registered during tenant setup and referenced by jobs.
| Attribute | Purpose |
|---|---|
| Code | Unique identifier within the tenant |
| Name | Display name with i18n support |
| Priority | Default priority — higher runs first |
| Parameters | Schema defining accepted parameters |
| Timeout | Maximum execution time |
Each program has one or more actions that are invoked when the program executes. This separates the "what to do" (program) from the "how to run it" (actions).
Worker management
Worker managers represent processing pools, each with a configurable concurrency limit.
Workers are individual processing instances registered under a manager. Workers claim jobs and report their status.
Jobs
A job is a runtime instance of a program. When a user or system submits work, a job record is created.
Lifecycle
| Phase | Status | Meaning |
|---|---|---|
PENDING | NORMAL | Waiting to be picked up by a worker |
RUNNING | NORMAL | Actively executing |
COMPLETED | NORMAL | Finished successfully |
COMPLETED | ERROR | Finished with errors |
COMPLETED | WARNING | Finished with warnings |
Key attributes
| Attribute | Purpose |
|---|---|
| Job number | Auto-incrementing identity |
| Program | The program this job runs |
| Parameters | Input parameters for this execution |
| Scheduled start | When the job should start (default: now) |
| Parent job | For child jobs (job chaining) |
| Hold flag | Prevents the job from being picked up |
| Terminated flag | Marks the job as cancelled |
User context
Jobs capture the submitting user's context at creation time. This allows the job to execute with the same permissions as the user who submitted it.
Job schedules
Recurring jobs use cron-style schedule definitions. Each schedule specifies minute, hour, day-of-month, month, and day-of-week fields, following standard cron syntax. An optional random jitter factor can be applied to the minute field to distribute scheduled jobs evenly and avoid spikes.
Notifications
Notification groups and rules
Notification groups bundle notification rules together. A program references a notification group, and the group contains individual rules that define when and who to notify based on job lifecycle events (e.g. notify on COMPLETED + ERROR).
Notification templates
Templates use Liquid syntax for variable substitution from job parameters and result data. A set of default templates is provided during tenant setup and can be customised. Templates support i18n.
Job logs
Structured log entries for job execution, including severity level and human-readable message.