Job queue

This article describes how the job queue works in Business Central. A job queue is basically an abstraction that uses the task scheduler from the platform to enable end users to view, create, or modify jobs that are set to run in the background. These jobs can be set to run on a recurring schedule.

For information about how users work with the job queue in the client, see Use job queues to schedule tasks.


Business Central supports multiple ways to run asynchronous (async) operations, such as job queues, scheduled tasks, new sessions, and page background tasks. For more information, see Async processing overview.

Job queue flow

The following diagram illustrates the flow of the job queue:

Shows the job queue activity flow.

How job queue works

This section describes the flow that a job queue goes through.

General flow

A job is run when the task scheduler's task is run. For more information, see Task scheduler - detailed flow.

Here's a general overview of the process:

  1. When a job queue is created and set to ready state, a scheduled task is created to run, but not before the Earliest Start Date/Time.
  2. When the scheduled task is picked up by the task scheduler to run, a new background session is started.
  3. The background session is run by the Job Queue Dispatcher codeunit:
    1. It first checks whether the job should be run or rescheduled.

      If the job shouldn't run, it's deleted. Or, in the case of an already running "Category Code", it's rescheduled.

    2. The job queue entry is updated to the In-Progress state, and a job queue log entry is created.

    3. The specified Object ID to Run is then started.

      If an exception occurs, none of the subsequent steps in the Job Queue Dispatcher path will be run, but instead, the failure codeunit path will be run.

  4. The failure codeunit path runs as follows:
    1. An exception is raised and surfaced.
    2. The Job Queue Error Handler codeunit is run in a new background session.
      1. The job queue entry is updated to the Error state.
      2. The errors are saved by using Error Message Management.
      3. The job queue entry and job queue log entry are updated with the error.
      4. The job queue then either stays in the Error state or is rescheduled:
        • It stays in Error state if the Maximum No. of Attempts value has been exceeded and it's not a recurring job.
        • It's rescheduled if the Maximum No. of Attempts value hasn't been exceeded and it's a recurring job.

Running codeunits with the job queue

When running a codeunit with the job queue, you must declare the OnRun() trigger, as this defines the code, which the underlying task scheduler will run. The same applies for the failure codeunit.

codeunit 50142 MyCodeunitToBeRunFromTheJobQueue
    trigger OnRun()
        // declare your variables
        // code to be run. Probably calling other methods


If the same code needs to run both in the UI but also in the background (in a scheduled task or with a job queue entry) or in a web service call (SOAP/OData/API), then use if GuiAllowed() then calls to encapsulate AL code that interact with the user. For more information, see System.GuiAllowed() Method.

If you want to do multiple things with a single codeunit using the job queue, consider using a parameter. To achieve this, define the TableNo property and set it to "Job Queue Entry" on the codeunit, then you'll be able to access the parameter string defined on the job queue entry from the codeunit.

codeunit 50143 MyCodeunitToBeRunFromTheJobQueueNowWithParameters
    TableNo = "Job Queue Entry";

    trigger OnRun()
        // declare your variables
        if Rec."Parameter String" <> '' then
            // code to be run. Probably calling other methods

AL methods that throw nonretriable exceptions in job queue entries

When running codeunits in the job queue, you must make sure that the AL code doesn't assume the ability to interact with a user through the UI. You can use the GuiAllowed Method to suppress UI interactions.


The server returns the following exception when trying to invoke a dialog UI through a web service call or in a background session: NavNCLCallbackNotAllowedException: Callback functions are not allowed.

Variables of the Dialog data type or any of the methods listed as dialog methods can cause "callback not allowed" exceptions when they're called from a web service call or a background session. The Message Method (Dialog) is the only method in this category that doesn't cause an exception.

The following table describes how dialog boxes are handled in a background or web service session, which has no UI.

Method that creates the dialog box Behavior
Dialog.Confirm - Dialog box is suppressed.
- The following error occurs on the Business Central instance: Business Central attempted to issue a client callback to show a confirmation dialog box.
Dialog.Error - Dialog box is suppressed.
- AL code execution ends.
- The error is logged to the event log of the Business Central instance.
- The error is added to the Comments field of the Session Event table.
Dialog.Message - Dialog box is suppressed.
- The message is recorded in the event log of the computer that is running Business Central instance. The log entry has type Information and includes the context of the message.
Dialog.Open - Dialog box is suppressed.
- Dialog box text is not displayed or logged.

Other AL methods that you shouldn't use in web service endpoints or background sessions are:

  • Page.Run
  • Page.RunModal
  • Activate
  • Report.Run
  • Report.RunModal
  • Hyperlink
  • File.Upload
  • File.Download

You should also avoid operations on client-side Automation and .NET Framework interoperability objects.

About job queue sessions and permissions

The session runs using the same user/credentials that are used when calling AL code. The user that's used is the user that sets the job to ready state. The user must have appropriate permissions to run the job queue and any other objects that are associated with the operation of the specified object.

For more information about assigning permissions, see Assign Permissions to Users and Groups in the business functionality help.

Job queues and performance

Scheduled tasks or job queue entries that are set to run on a recurring schedule can impact the performance of Business Central under either of the following conditions:

  • They run too frequently.

    Consider how often the task or job needs to run. Especially for polling scenarios, you might have better and more performant ways to react, such as using webhooks.

  • They run heavy jobs while many users are also using Business Central.

    Consider running them outside working hours. This might decrease locking and deadlock issues both for users and for the task or job itself.

Monitor and troubleshoot

Business Central offers two ways to monitor the flow of job queues: Azure Application Insights and the Session Event table. These tools let you follow the execution of a job and investigate errors in failure codeunits.

Job queue telemetry in Azure Application Insights

You can set up Business Central to send telemetry traces to an Azure Application Insights resource in Azure. Once set up, telemetry data will be sent to the resource as job queue moves through the flow. For more information, see:

Enable Sending Telemetry to Application Insights


Job queue telemetry in Azure Application Insights also works for Business Central on-premises

Job queue telemetry

Job queue lifecycle telemetry gathers data about the following operations:

  • A job queue entry was enqueued.
  • A job queue entry was started.
  • A job queue entry finished. Provides information as to whether it was successful or failed.
  • A job queue entry was stopped.
  • A job queue entry was cancelled.
  • A job queue entry was scheduled on login.
  • A job queue entry was run by a user.

The following table describes the event IDs that are currently emitted by the job queue system.

Event Event id Job queue status Description
Job queue entry enqueued AL0000E24 Enqueued Occurs when a job queue entry successfully enqueues and will after the specified alJobQueueEarliestStartDateTime.
Job queue entry failed to be enqueued AL0000FNY Enqueued Occurs when a job queue entry fails to enqueue and this happens if no task scheduler is created behind it.
Job queue entry started AL0000E25 Started Occurs right before the Job Queue Start codeunit is triggered and that codeunit will run the specified Object ID to run.
Job queue entry finished AL0000E26 Finished successfully Occurs at the very end of the job queue run.
Job queue entry failed (might be retried) AL0000HE7 Error Occurs when a job queue errors, and this is the first thing that is triggered before the updating of records.
Job queue entry rescheduled on login AL0000I49 N/A Emitted if a job queue entry is rescheduled every time a user logs in.
Job queue entry run once by a user AL0000FMG N/A Emitted when the "Run once (Foreground)" action is clicked in Job Queue Entries/Card pages
Job queue entry failed for the last time and is set to stopped AL0000JRG Error Emitted when the job queue entry fails for the very last time before being set in Error state.

For more information about job queue telemetry, see Analyzing Job Queue Telemetry

Task scheduler telemetry

Task scheduler telemetry gathers information about the execution of scheduled tasks. The data gives insight into what happens in background sessions that are coming from scheduled tasks. It provides information that lets you troubleshoot failures. The data can also help you determine whether tasks would be better scheduled for off hours to limit the load on the service.

For an overview of task scheduler and to understand the flow related to task execution, see Task Scheduler.

For more information about task scheduler telemetry, see Analyzing Task Scheduler Telemetry

Session Event Table

From the Business Central web client, you can open the Session Events table by adding table=2000000111 to the URL. For example:

Characteristics of job queues and scheduled tasks

Job queues and scheduled tasks come with different characteristics as described in the following table:

Method to start a new asynchronous operation Characteristics
Task Queued up
Runs once
Any server in a cluster can start it
Survives server restarts
No logging in Business Central
Has telemetry.
No user interface for administration.
Job queue Scheduled
Supports recurrence
Any server in a cluster can start it
Survives server restarts
Logging of results in Business Central
Has telemetry.
Has a user interface for administration.

For more information, see Async processing overview

See also

Use Job Queues to Schedule Tasks
Analyzing Job Queue Telemetry
Task Scheduler
Async processing overview
Performance Articles for Developers
Developing Extensions
Get Started with AL