Background jobs and workers

A good deal of GVenta Help Desk runs without anyone clicking anything: mailboxes are polled, reports are emailed, expired tokens are purged and counters are reset. This page lists those jobs, shows where you can watch and control the mailbox workers, and explains how the application tells a healthy worker from a stuck one.

The jobs

Job	What it does
Email sync orchestrator	Continuously polls every active mailbox on a default 20-second cycle and turns new mail into tickets. Described in full in The email pipeline.
Daily report	Fired by the orchestrator at the configured time (default 08:00, server time), once per day. The “already sent today” marker is stored in the database, so a worker restart cannot cause a second report or a missed one.
Report digests	A weekly Overview digest on Mondays and a monthly one on the 1st of the month, each an HTML summary with a CSV attachment, sent to the recipients configured under Settings → SLA & Reports. Supports a dry run. See The SLA engine.
Token cleanup	Purges expired blacklisted tokens and stale rate-limit records. Runs hourly, or as a one-shot task when triggered by an external scheduler, and shuts down cleanly when asked to stop.
Worker auto-recovery	When the application starts, waits for the database, reads which workers are supposed to be running, and restarts them. You do not need to restart mailbox syncing by hand after an upgrade or restart.
Daily counter reset	Resets each worker’s “emails processed today” counter.
Utility jobs	SLA due-date backfill, attachment reprocessing, token encryption migration and audit log purging. These are run on demand rather than on a schedule.

Watching the mailbox workers

Every inbound mailbox has its own sync worker. Their health is shown under Settings → Email Integration → Email Sync Worker Status, which is visible to Super Admins. For each source you can see:

• whether the worker is alive,
• the last heartbeat and the number of seconds since it,
• the last sync time,
• the start time,
• the error count,
• emails processed today, this session and over the worker’s lifetime,
• the last error, and
• the last check.

Aggregated totals across all sources are shown alongside, and a Worker Error Log panel exposes recent errors so you can see exactly what went wrong and on which mailbox.

Start, stop and restart

Workers can be started, stopped and restarted from the same panel. In the Receive Email Sources list, each source also has an Active toggle and can be started and stopped individually, and one source can be marked as the default. See Settings for the rest of the Email Integration screen.

Each worker has an intended state and an actual state, and the worker list reports both. Intended state is what auto-recovery reads at startup to decide what to bring back.

Why it matters: Connect a mailbox in minutes, prove it works before you save, and see at a glance whether mail is actually flowing, with the exact error if it isn’t.

Heartbeats: running versus stuck

A process that is alive is not necessarily doing anything. To tell the difference, each worker publishes a heartbeat at regular intervals while it is working. Health monitoring looks at the age of the most recent heartbeat, not just at whether the process exists, so it can distinguish:

• running: the process exists and its heartbeat is fresh;
• running but stuck: the process exists but the heartbeat has gone stale.

This is why the status panel shows “seconds since heartbeat” rather than a simple on/off indicator.

Alongside the heartbeat, the application keeps per-worker counters (today, this session and lifetime), an error history, and a record of the last check. These are held in the cache/session store and degrade gracefully: if the store is unavailable, the status feature degrades rather than the request failing.

Resuming cleanly

• Per-source last-sync timestamps mean a restarted worker resumes from where it stopped instead of re-reading the whole mailbox.
• Graceful shutdown: when a worker is stopped, it finishes the source it is working on rather than dropping a message halfway through.
• Processed-folder archiving means that even a restore from an older backup will not re-create tickets from mail that was already handled.

When a mailbox keeps failing

The orchestrator isolates failures per source, so one broken mailbox never stops the others. Beyond that:

• A source that fails 20 consecutive times is automatically disabled, and the application automatically tries to re-enable it every 5 minutes once conditions improve.
• An authentication outage with Microsoft 365 is handled differently: the orchestrator applies exponential backoff between cycles, capped at 30 minutes, and leaves your sources active, because disabling them cannot fix an authentication problem. Syncing resumes on its own once the connection is re-authorized.

Both behaviors are described in more detail in The email pipeline.

Controlling workers through the API

Everything the status panel does is available to integrations and monitoring tools:

• GET /api/workers lists all registered workers with their intended and actual running state; GET /api/workers/{name} returns one.
• POST /api/workers/{name}/start and POST /api/workers/{name}/stop control a worker; start optionally accepts configuration overrides.
• POST /api/email-sources/{id}/start-worker and POST /api/email-sources/{id}/stop-worker control the worker for one inbound mailbox.
• GET /api/oauth/microsoft365/worker-status returns the per-source and aggregated health shown in the panel, and GET /api/oauth/microsoft365/worker/errors returns the recent error history. Start, stop and restart endpoints sit alongside them.

All of these require a staff JWT. See the endpoint reference for parameters, and Security and storage for the health and metrics endpoints that external monitoring can poll.