{"title":"Job queue","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-job-queue/","by":"JOP-AL","license":"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.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-job-queue","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn about how the job queue works","date":"2023-12-18","meta":{"topic":"how-to"},"outline":[{"level":2,"title":"Job queue flow","slug":"job-queue-flow","at":671,"chars":193},{"level":2,"title":"How job queue works","slug":"how-job-queue-works","at":864,"chars":1688},{"level":3,"title":"General flow","slug":"general-flow","at":950,"chars":1602},{"level":2,"title":"Running codeunits with the job queue","slug":"running-codeunits-with-the-job-queue","at":2552,"chars":3549},{"level":3,"title":"AL methods that throw nonretriable exceptions in job queue entries","slug":"al-methods-that-throw-nonretriable-exceptions-in-job-queue-entries","at":3931,"chars":2170},{"level":2,"title":"About job queue sessions and permissions","slug":"about-job-queue-sessions-and-permissions","at":6101,"chars":508},{"level":2,"title":"Job queues and performance","slug":"job-queues-and-performance","at":6609,"chars":605},{"level":2,"title":"Monitor and troubleshoot","slug":"monitor-and-troubleshoot","at":7214,"chars":3928},{"level":3,"title":"Job queue telemetry in Azure Application Insights","slug":"job-queue-telemetry-in-azure-application-insights","at":7461,"chars":3415},{"level":4,"title":"Job queue telemetry","slug":"job-queue-telemetry","at":7954,"chars":2262},{"level":4,"title":"Task scheduler telemetry","slug":"task-scheduler-telemetry","at":10216,"chars":660},{"level":3,"title":"Session Event Table","slug":"session-event-table","at":10876,"chars":266},{"level":2,"title":"Characteristics of job queues and scheduled tasks","slug":"characteristics-of-job-queues-and-scheduled-tasks","at":11142,"chars":698},{"level":2,"title":"Related information","slug":"related-information","at":11840,"chars":402}],"text":"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.\nFor information about how users work with the job queue in the client, see Use job queues to schedule tasks</admin-job-queues-schedule-tasks>.\n> NOTE\n> 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>.\n## Job queue flow\nThe following diagram illustrates the flow of the job queue:\n <https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/job-queue-activity-flow.png>\n## How job queue works\nThis section describes the flow that a job queue goes through.\n### General flow\nA job is run when the task scheduler's task is run. See devenv-task-scheduler#detailed-flow.\nHere's a general overview of the process:\n1. 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.\n2. When the scheduled task is picked up by the task scheduler to run, a new background session is started.\n3. The background session is run by the Job Queue Dispatcher codeunit:\n 1. It first checks whether the job should be run or rescheduled.\n  If the job shouldn't run, it's deleted. Or, in the case of an already running \"Category Code\", it's rescheduled.\n 2. The job queue entry is updated to the In-Progress state, and a job queue log entry is created.\n 3. The specified Object ID to Run is then started.\n  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.\n4. The failure codeunit path runs as follows:\n 1. An exception is raised and surfaced.\n 2. The Job Queue Error Handler codeunit is run in a new background session.\n  1. The job queue entry is updated to the Error state.\n  2. The errors are saved by using Error Message Management.\n  3. The job queue entry and job queue log entry are updated with the error.\n  4. The job queue then either stays in the Error state or is rescheduled:\n    It stays in Error state if the Maximum No. of Attempts value has been exceeded and it's not a recurring job.\n    It's rescheduled if the Maximum No. of Attempts value hasn't been exceeded and it's a recurring job.\n## Running codeunits with the job queue\nWhen 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.\n```al\ncodeunit 50142 MyCodeunitToBeRunFromTheJobQueue\n{\n    trigger OnRun()\n    var\n        // declare your variables\n    begin\n        // code to be run. Probably calling other methods\n    end;\n}\n```\n> TIP\n> 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.\nIf 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.\n```al\ncodeunit 50143 MyCodeunitToBeRunFromTheJobQueueNowWithParameters\n{\n    TableNo = \"Job Queue Entry\";\n\n    trigger OnRun()\n    var\n        // declare your variables\n    begin\n        if Rec.\"Parameter String\" <> '' then\n        begin\n            // code to be run. Probably calling other methods\n        end\n    end;\n}\n```\n### AL methods that throw nonretriable exceptions in job queue entries\nWhen 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.\n> NOTE\n> 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.\nVariables 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.\nThe following table describes how dialog boxes are handled in a background or web service session, which has no UI.\nMethod that creates the dialog box|Behavior\nmethods-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.\nmethods-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.\nmethods-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.\nmethods-auto/dialog/dialog-open-method|- Dialog box is suppressed.<br />- Dialog box text is not displayed or logged.\nOther AL methods that you shouldn't use in web service endpoints or background sessions are:\n Page.Run\n Page.RunModal\n Activate\n Report.Run\n Report.RunModal\n Hyperlink\n File.Upload\n File.Download\nYou should also avoid operations on client-side Automation and .NET Framework interoperability objects.\n## About job queue sessions and permissions\nThe 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.\nFor more information about assigning permissions, see Assign Permissions to Users and Groups</ui-define-granular-permissions> in the business functionality help.\n## Job queues and performance\nScheduled 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:\n They run too frequently.\n  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.\n They run heavy jobs while many users are also using Business Central.\n  Consider running them outside working hours. This might decrease locking and deadlock issues both for users and for the task or job itself.\n## Monitor and troubleshoot\nBusiness 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.\n### Job queue telemetry in Azure Application Insights\nYou 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:\nEnable Sending Telemetry to Application Insights<../administration/telemetry-enable-application-insights>\n> NOTE\n> Job queue telemetry in Azure Application Insights also works for Business Central on-premises\n#### Job queue telemetry\nJob queue lifecycle telemetry gathers data about the following operations:\n A job queue entry was enqueued.\n A job queue entry was started.\n A job queue entry finished. Provides information as to whether it was successful or failed.\n A job queue entry was stopped.\n A job queue entry was cancelled.\n A job queue entry was scheduled on login.\n A job queue entry was run by a user.\nThe following table describes the event IDs that are currently emitted by the job queue system.\nEvent|Event id|Job queue status|Description\nJob queue entry enqueued|AL0000E24|Enqueued|Occurs when a job queue entry is enqueued to run at or after the specified alJobQueueEarliestStartDateTime.\nJob 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.\nJob 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`.\nJob queue request finished|AL0000E26|Finished successfully|Occurs when a job queue request completes successfully.\nJob 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.\nJob 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.\nJob 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.\nJob 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.\nJob 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.\nJob queue entry cancelled|AL0000KZV|N/A|Emitted when a job queue entry is cancelled. The event has normal severity (`1`).\nFor more information about job queue telemetry, see Analyzing Job Queue Telemetry<../administration/telemetry-job-queue-lifecycle-trace>\n#### Task scheduler telemetry\nTask 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.\nFor an overview of task scheduler and to understand the flow related to task execution, see devenv-task-scheduler.\nFor more information about task scheduler telemetry, see Analyzing Task Scheduler Telemetry<../administration/telemetry-task-scheduler-trace>\n### Session Event Table\nFrom 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>.\n## Characteristics of job queues and scheduled tasks\nJob queues and scheduled tasks come with different characteristics as described in the following table:\nMethod to start a new asynchronous operation|Characteristics\nTask|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.\nJob 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.\nSee Async processing overview<devenv-async-overview>\n## Related information\nUse Job Queues to Schedule Tasks</admin-job-queues-schedule-tasks>\nAnalyzing Job Queue Telemetry<../administration/telemetry-job-queue-lifecycle-trace>\ndevenv-task-scheduler\nAsync processing overview<devenv-async-overview>\nPerformance Articles for Developers<../performance/performance-developer>\nDeveloping Extensions<devenv-dev-overview>\nGet Started with AL<devenv-get-started>"}