# Job queue
This article describes how the job queue works in Business Central. A job queue is basically an abstraction that uses the devenv-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</admin-job-queues-schedule-tasks>.
> NOTE
> Business Central supports multiple ways to run asynchronous (async) operations, such as job queues, scheduled tasks, new sessions, and page background tasks. See Async processing overview<devenv-async-overview>.
## Job queue flow
The following diagram illustrates the flow of the job queue:
 <https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/job-queue-activity-flow.png>
## 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. See devenv-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.
```al
codeunit 50142 MyCodeunitToBeRunFromTheJobQueue
{
    trigger OnRun()
    var
        // declare your variables
    begin
        // code to be run. Probably calling other methods
    end;
}
```
> TIP
> 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. See methods-auto/system/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.
```al
codeunit 50143 MyCodeunitToBeRunFromTheJobQueueNowWithParameters
{
    TableNo = "Job Queue Entry";

    trigger OnRun()
    var
        // declare your variables
    begin
        if Rec."Parameter String" <> '' then
        begin
            // code to be run. Probably calling other methods
        end
    end;
}
```
### 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 methods-auto/system/system-guiallowed-method to suppress UI interactions.
> NOTE
> 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 methods-auto/dialog/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 methods-auto/dialog/dialog-message-method 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
methods-auto/dialog/dialog-confirm-method|- Dialog box is suppressed.<br />- The following error occurs on the Business Central instance: Business Central attempted to issue a client callback to show a confirmation dialog box.
methods-auto/dialog/dialog-error-string-joker-method|- Dialog box is suppressed.<br />- AL code execution ends.<br />- The error is logged to the event log of the Business Central instance.<br />- The error is added to the Comments field of the Session Event table.
methods-auto/dialog/dialog-message-method|- Dialog box is suppressed.<br />- 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.
methods-auto/dialog/dialog-open-method|- Dialog box is suppressed.<br />- 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</ui-define-granular-permissions> 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<../administration/telemetry-enable-application-insights>
> NOTE
> 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 is enqueued to run at or 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 request finished|AL0000E26|Finished successfully|Occurs when a job queue request completes successfully.
Job queue run finished|AL000082C|Finished successfully|Occurs when a job queue run completes successfully. This event is sent only to the extension publisher's telemetry resource.
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 sign-in|AL0000I49|N/A|Emitted when an eligible recurring job queue entry without a scheduled task is rescheduled after sign-in.
Job queue entry run once by a user|AL0000FMG|N/A|Emitted after a user selects Run once (foreground) on the Job Queue Entries or Job Queue Entry Card page and confirms the action.
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.
Job queue entry cancelled|AL0000KZV|N/A|Emitted when a job queue entry is cancelled. The event has normal severity (`1`).
For more information about job queue telemetry, see Analyzing Job Queue Telemetry<../administration/telemetry-job-queue-lifecycle-trace>
#### 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 devenv-task-scheduler.
For more information about task scheduler telemetry, see Analyzing Task Scheduler Telemetry<../administration/telemetry-task-scheduler-trace>
### 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: https://businesscentral.dynamics.com/?table=2000000111<https://businesscentral.dynamics.com/?table=2000000111>.
## 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 <br> Runs once <br> Any server in a cluster can start it <br> Survives server restarts <br> No logging in Business Central <br> Has telemetry.<br> No user interface for administration.
Job queue|Scheduled <br> Supports recurrence <br> Any server in a cluster can start it <br> Survives server restarts <br> Logging of results in Business Central <br> Has telemetry. <br> Has a user interface for administration.
See Async processing overview<devenv-async-overview>
## Related information
Use Job Queues to Schedule Tasks</admin-job-queues-schedule-tasks>
Analyzing Job Queue Telemetry<../administration/telemetry-job-queue-lifecycle-trace>
devenv-task-scheduler
Async processing overview<devenv-async-overview>
Performance Articles for Developers<../performance/performance-developer>
Developing Extensions<devenv-dev-overview>
Get Started with AL<devenv-get-started>

Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-job-queue, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact. https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-job-queue/
