The job queue: how it works, how to monitor it, and why it stops

The job queue is the part of Business Central that nobody thinks about until the 6am invoice run did not happen, the EDI orders did not come in, or the month-end report was never emailed. It is also where a lot of extension code runs. This is how it works and how to keep it working.

How it runs

A Job Queue Entry says what to run (a codeunit or a report, with a parameter string and optionally a record), when (a one-off date-time, or a recurrence pattern: days of the week, start and end times, minutes between runs), and under whose identity (the user who set it to Ready; see below). Business Central online runs a scheduler that picks up Ready entries whose time has come and executes each in its own background session. Each run writes a Job Queue Log Entry with the outcome. On error, the entry goes to Error status with the message, and depending on settings retries a number of times.

Three things follow that are not obvious. The job runs as the user who last set it to Ready, with that user's permissions and that user's company, language and settings; if that person leaves and their account is disabled, the job stops. Each run is a separate transaction, and an error anywhere rolls back the whole run. And there is no guarantee two scheduled jobs will not overlap, unless you set a Job Queue Category with a category code, which serialises entries in the same category.

Settings that matter

• Maximum No. of Attempts to Run and Rerun Delay (sec.): how many retries and how far apart. Three attempts a few minutes apart suits most integrations; one attempt suits anything that should not be retried blindly (posting).
• Job Queue Category Code: serialise jobs that must not run concurrently (two things that post to the same ledger).
• Timeout: a job that runs past it is cancelled; set it so a stuck job does not hold a lock all night.
• Notify On Error (version 24 and later): send an in-client notification to a named user when the entry fails. Switch it on, and also see monitoring below because a notification nobody reads is not monitoring.
• Run on a dedicated service account. Create a user for scheduled jobs (a real licensed user, not a personal one) with exactly the permissions the jobs need, and set every production entry to Ready as that user. Nobody leaves, nobody is on holiday, and permissions are reviewed once.

Running your own code on the queue

A codeunit with OnRun taking a Job Queue Entry record can be scheduled directly (the parameter string is yours to parse). For work triggered by a user action that should not block the session (send 500 emails, call a slow API), TaskScheduler.CreateTask queues a one-off background run of a codeunit with a failure codeunit; it is the right tool for "do this soon, not now" and it avoids the user waiting on a spinner. For both: make the work idempotent (a retried job must not post twice), log telemetry at start, end and error, and keep each run short enough that a failure loses little.

Why it stops

• The user who owned the entries left. The single most common cause. Service account, above.
• An update. After a major update, entries can be left in a non-Ready state or a codeunit can have changed. Checking the queue is on the release wave checklist for that reason.
• A permissions change. Someone tidied the service account's permission sets.
• An error that retries forever. An integration endpoint is down, the job fails, retries three times, goes to Error, and nobody notices for a week.
• Locks. A long job holding a table while a user tries to post; or two jobs in no category deadlocking each other.
• Sandbox copy. A sandbox created from production has production's job queue entries, which start running against the sandbox's integrations (or worse, production's, if the endpoints are in the data). Set them to On Hold immediately after a copy; better, have an install-time check that puts every entry on hold when the environment is a sandbox (EnvironmentInformation.IsSandbox).
• Too many entries at the same minute. Everything scheduled for 00:00 competes for the same sessions. Spread them.

Monitoring that actually catches it

1. Telemetry. Job queue events (start, finish, error, with the codeunit and duration) go to Application Insights. One alert on "job queue entry failed" and one on "no successful run of job X in the last N hours" (an absence alert) cover most of it. The second is the one that catches a queue that silently stopped.
2. A daily glance. The Job Queue Entries page, filtered to Status = Error or On Hold, on the administrator's role centre. Thirty seconds.
3. A canary. One tiny job that runs every fifteen minutes and writes a timestamp. If the timestamp is old, the queue is not running, whatever else the dashboard says.
4. Log retention. Job Queue Log Entries grow; keep a few weeks and delete older ones with the retention policy.

If something did not happen last night and nobody can say why, the job queue log and the telemetry between them almost always can. If nobody in the business looks at either, that is the first fix, and it takes an afternoon.

More from the blog

• Change management in Business Central implementations: why it matters, why it fails, and how to make it work Projects
• The right project team: business as usual comes first, and that is the problem Projects
• Field types, field lengths and overflow errors: getting the data model right the first time Development