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.

Note

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:

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()
    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. 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()
    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 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 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

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 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: 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 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