Skip to main content

Background Jobs

The Background Jobs section runs long-running work outside the request/response cycle — things that take too long to do while someone waits, or that should happen on a recurring schedule. The first example is Refresh AI insights, which recomputes analytics insights (several model calls), but the system is general.

It's powered by a Postgres-backed queue, so there's no extra infrastructure to run — it uses the same database as everything else.

Where to find it​

Sidebar → Monitor → Background Jobs.

Key idea: job types vs. jobs​

  • A job type is a kind of background work plus the code that performs it (for example, "Refresh AI insights"). Job types are defined in code — they show up as cards at the top of the page.
  • A job (or run) is a single execution of a job type, with a payload. You create jobs; you don't create job types from the UI.

Think of the job type as a recipe and a job as one time you cook it.

The page​

Job Types​

One card per available job type. Each card shows:

  • Live counts — how many jobs of this type are currently active (running) or queued (waiting).
  • Schedule — the recurring schedule in plain English (e.g. "At 03:00 AM"), or "Not scheduled".
  • Run now — queue one job immediately. A dialog lets you edit the JSON payload (pre-filled with a sensible example).
  • Schedule / Edit schedule — create, change, or remove the recurring schedule (see below).

Runs​

A table of every job in the system, newest first. Filter by job type and by state. Each row shows the state, retry count, and timestamps; open a row's menu → View details to see the full payload and output (or the error, if it failed).

Row actions depend on state:

StateMeaningAvailable actions
Created / Queuedwaiting to runCancel, Delete
Activerunning nowCancel
Retryingfailed, will run againCancel, Delete
Completedfinished successfullyRetry, Delete
Failedexhausted its retriesRetry, Delete
Cancelledstopped before finishingResume, Retry, Delete

Failed jobs are retried automatically according to the job type's retry policy before they land in Failed.

Scheduling a job​

Click Schedule on a job type's card. Pick a preset (Hourly, Daily, Weekly, Monthly) or type a cron expression — the dialog shows a live plain-English description so you can confirm it does what you expect.

A cron expression has five fields: minute hour day-of-month month day-of-week.

ExpressionRuns
0 3 * * *every day at 03:00
0 * * * *every hour, on the hour
*/15 * * * *every 15 minutes
0 6 * * 1every Monday at 06:00

Each job type has one schedule; saving again replaces it, and Remove schedule clears it. Schedules are stored in the database and survive restarts.

Scheduled runs use the server's timezone (UTC by default).

Default schedule for Refresh AI insights​

Refresh AI insights runs every night at 02:00 UTC unless you set a different schedule. The nightly run refreshes the all-experiences view and then each experience with activity in the last 30 days, so the analytics overview's "What needs attention" list is current each morning.

The default is set once, the first time the app starts with it. After that the schedule is yours: change it or remove it in the UI and it stays that way across restarts. To start without the nightly run at all, set INSIGHTS_REFRESH_CRON=off before the first start. To change the default time or zone, set INSIGHTS_REFRESH_CRON (a cron expression) and INSIGHTS_REFRESH_TIMEZONE (for example Europe/Copenhagen).

A run refreshes every active experience in turn, so it may take a while. It is allowed up to 4 hours and is not retried if it fails; the next night's run picks up where it left off.

Default schedule for Health check​

Health check checks the database, search engine and AI providers every 10 minutes and keeps the result for a day. The dashboard's health line shows the latest result, so the page never waits on the checks itself; if no check has run in the last 30 minutes, the dashboard says the result is out of date.

Like the insights refresh, the default is set once and then the schedule is yours. Set HEALTH_CHECK_CRON to a different cron expression (UTC) to change it, or to off before the first start to skip it. Without it, the dashboard shows "Health not checked yet"; Monitor → Health Monitoring still checks on demand.

Notes​

  • Admin only. Viewing, running, scheduling, and managing jobs all require the admin role.
  • The engine runs in-process with the app and is safe across multiple replicas — each scheduled or queued job runs exactly once regardless of how many app instances are running.
  • To disable background jobs entirely, set ENABLE_JOBS=false.

For developers: adding a job type​

Adding a new job type is a small code change (no migration, no new API route, no UI change):

  1. Write a worker in src/features/jobs/handlers/ — an async function that receives a batch of jobs and does the work.
  2. Add the queue name to QUEUE in src/features/jobs/job-queues.ts.
  3. Add one entry to JOB_TYPES in src/features/jobs/job-registry.ts (label, description, example payload, worker).

On the next start the engine creates the queue and attaches the worker; the new type appears in the UI with Run now, scheduling, and run history working automatically.