{"title":"Task scheduler","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-task-scheduler/","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-task-scheduler, 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-task-scheduler","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 scheduled tasks and how the task scheduler works.","date":"2024-09-09","meta":{"topic":"how-to"},"outline":[{"level":2,"title":"When to use scheduled tasks in AL","slug":"when-to-use-scheduled-tasks-in-al","at":674,"chars":549},{"level":2,"title":"Create and manage scheduled tasks in AL","slug":"create-and-manage-scheduled-tasks-in-al","at":1223,"chars":1578},{"level":2,"title":"How task scheduler works","slug":"how-task-scheduler-works","at":2801,"chars":3080},{"level":3,"title":"General flow","slug":"general-flow","at":2897,"chars":2121},{"level":3,"title":"Detailed flow","slug":"detailed-flow","at":5018,"chars":228},{"level":3,"title":"Retry intervals","slug":"retry-intervals","at":5246,"chars":635},{"level":2,"title":"Error conditions and retriable exceptions","slug":"error-conditions-and-retriable-exceptions","at":5881,"chars":4203},{"level":3,"title":"Retriable exceptions in the main codeunit","slug":"retriable-exceptions-in-the-main-codeunit","at":6922,"chars":612},{"level":3,"title":"Retriable exceptions in the failure codeunit","slug":"retriable-exceptions-in-the-failure-codeunit","at":7534,"chars":376},{"level":3,"title":"AL methods that throw nonretriable exceptions in background sessions","slug":"al-methods-that-throw-nonretriable-exceptions-in-background-sessions","at":7910,"chars":2174},{"level":2,"title":"About task sessions and permissions","slug":"about-task-sessions-and-permissions","at":10084,"chars":929},{"level":2,"title":"Task scheduler and performance","slug":"task-scheduler-and-performance","at":11013,"chars":609},{"level":2,"title":"Operational limits for the task scheduler","slug":"operational-limits-for-the-task-scheduler","at":11622,"chars":420},{"level":2,"title":"Monitor and troubleshoot","slug":"monitor-and-troubleshoot","at":12042,"chars":997},{"level":3,"title":"Task scheduler telemetry in Azure Application Insights","slug":"task-scheduler-telemetry-in-azure-application-insights","at":12305,"chars":468},{"level":3,"title":"Session Event table","slug":"session-event-table","at":12773,"chars":266},{"level":2,"title":"Configure task scheduler for Business Central on-premises","slug":"configure-task-scheduler-for-business-central-on-premises","at":13039,"chars":448},{"level":2,"title":"Characteristics of job queues and scheduled tasks","slug":"characteristics-of-job-queues-and-scheduled-tasks","at":13487,"chars":698},{"level":2,"title":"Related information","slug":"related-information","at":14185,"chars":407}],"text":"The task scheduler enables you to control when certain operations or processes (in other words tasks) are run. Basically, a task is a codeunit or report that is scheduled to run at a specific date and time. Tasks run in a background session between the Dynamics 365 Business Central service instance and database. Behind the scenes, the task scheduler is used by the job queue to process job queue entries that are created and managed from the clients.\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## When to use scheduled tasks in AL\nHere's a few scenarios where you might want to use a scheduled task\n From AL, you can schedule code to run either using the task scheduler or by enqueuing a job queue entry. If you want users to be able to change the scheduling, use the job queue.\n Sometimes in AL code, you want to change company and run code there. Maybe instead you can schedule a task to run the code in the other company?\n If something isn't urgent/time critical (for example, can run at a lower priority), consider running it with a task.\n## Create and manage scheduled tasks in AL\nA scheduled task is basically a codeunit that runs logic in a background session at a specific time. Optionally, you can create a second codeunit that contains the logic to handle the task if an error occurs for any reason. This codeunit is referred to as a failure codeunit.\nIn AL code, you create and manage the tasks by using the AL methods that are available for the methods-auto/taskscheduler/taskscheduler-data-type data type.\nMethod|Description|Learn more in ...\nCreateTask|Adds a task to run a codeunit at a specified date and time.|methods-auto/taskscheduler/taskscheduler-createtask-integer-integer-boolean-string-datetime-recordid-method<br><br>methods-auto/taskscheduler/taskscheduler-createtask-integer-integer-boolean-string-datetime-recordid-duration-method\nSetTaskReady|Sets a task to the Ready state. A task can't run until it's Ready.|TaskScheduler.SetTaskReady(Guid [, DateTime]) Method<methods-auto/taskscheduler/taskscheduler-settaskready-method>\nTaskExists|Checks whether a specific task exists.|TaskScheduler.TaskExists(Guid) Method<methods-auto/taskscheduler/taskscheduler-taskexists-method>\nCancelTask|Cancels a scheduled task.|TaskScheduler.CancelTask(Guid) Method<methods-auto/taskscheduler/taskscheduler-canceltask-method>\nTo set up a task, create codeunits that contain the logic that you want to run at a scheduled time. Once you have the codeunits, add code to the application that calls the CreateTask method to schedule a task. The CreateTask method can also specify the earliest date to run the task.\n## How task scheduler works\nThis section describes the flow that a scheduled task goes through.\n### General flow\nWhen a scheduled task is run, there are two possible execution paths that it can follow: the main path and the exception path. The main path is used to run the main codeunit and failure codeunits, if any. The exception path is used to handle errors and control the retry flow when errors occur in the main path. What happens in the exception path depends on whether the exception is #retriable.\nHere's a general overview of the process:\n1. When a task is created, the task is recorded in table 2000000175 Scheduled Task of the database.\n2. When task achieves the ready state and its scheduled time occurs, a new background session is started.\n3. The main path starts:\n 1. The company is opened and the scheduled task in the table 2000000175 Scheduled Task is validated.\n  If any error occurs during this phase, the task fails unless there's a failure codeunit. In which case, the failure code runs.\n 2. The task's main codeunit is run:\n   If main codeunit runs successfully, it's removed from table 2000000175 Scheduled Task.\n   If an error occurs, the error is passed on to the exception path.\n4. The exception path starts:\n 1. The transaction is rolled back.\n 2. The exception handling logic is run:\n   If the exception is retriable, the main codeunit is rerun following the main path.\n    This retry flow continues in the same session until the task succeeds or until the maximum number of retries is exceeded, then it fails. The session is then deleted. To understand when the task is retried, see Retry Intervals<#retrycycle>.\n   If the exception isn't retriable and there's no failure codeunit, the task fails.\n   If the exception isn't retriable and there's a failure codeunit, the current session is terminated. A new session is started, and the failure codeunit runs in this session, following the main path.\n    If the failure codeunit doesn't handle the error or fails itself, then the exception path is run to retry the failure codeunit. This retry flow continues in the same session until the task succeeds or until the maximum number of retries is exceeded. The session is then terminated.\n### Detailed flow\nThe following diagram illustrates the flow in detail.\n![Shows the detailed flow of a scheduled task.]<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/task-scheduler-flow.png>\n### Retry intervals\nWhen a task's main codeunit or failure codeunit enters the retry flow, it reruns at approximately the following intervals as long as the error persists. The number of retires and the intervals are different for Business Central online and on-premises.\nOnline\nA codeunit is retried up to 99 times, according to the following intervals:\nRetry attempt|Wait time (minutes) after previous attempt\n1 and 2|0.5\n3 and 4|1\n5 and 6|2\n7 and 8|3\n9 to 99|5\nOn-premises\nA codeunit is retried up to nine times, according to the following intervals:\nRetry attempt|Wait time (minutes) after previous attempt\n1 and 2|2\n3|4\n4 to 9|15\n## Error conditions and retriable exceptions\nA task can fail under the various conditions, like:\n The company can't be opened.\n A SQL connection or transient error occurred with the database.\n The Dynamics 365 Business Central service instance restarted while the task was being run.\n An upgrade is in progress.\nThe task scheduler is designed to automatically rerun main and failure codeunits when certain exceptions occur, instead of just failing on the first attempt. Exceptions that cause the system to rerun a codeunit are referred to as retriable exceptions. Whether an exception is retriable depends on whether the exception occurs in the main or failure codeunit and if you're using Business Central online or on-premises.\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.\n### Retriable exceptions in the main codeunit\nIf you're running Business Central online, the service controls which exceptions are retriable. With Business Central on-premises, you can specify retriable exceptions by configuring the Execution Retry Exceptions (TaskSchedulerExecutionRetryExceptions) setting on the Business Central Server instance. The Execution Retry Exceptions setting is semicolon-separated list of exceptions in a format: `Exception1;Exception2;Exception3`. If you want to specify error code of the exception, use the following format instead: `Exception1:ErrorCode1;Exception2:ErrorCode2.`\n### Retriable exceptions in the failure codeunit\nBecause failure codeunits are designed for error situations, expect for a selected few, almost all exceptions while running failure codeunits are retriable. It doesn't matter if you're using Business Central online or on-premises. Even with on-premises, you can't specify retriable exceptions, like you can for main codeunits.\n### AL methods that throw nonretriable exceptions in background sessions\nWhen running codeunits as scheduled tasks, 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 task sessions and permissions\nThe task runs in a background session, which means that there's no user interface. The behavior is similar to that of the StartSession method, where any dialog boxes that would normally appear are suppressed. Learn more about specific dialog boxes in methods-auto/session/session-startsession-integer-integer-string-table-duration-method method.\nThe session runs by using the same user/credentials that are used when calling AL code. The user must have appropriate permissions to the codeunit and any other objects that are associated with the operation of the codeunit.\n> NOTE\n> The delegated admins can't schedule tasks. They can test the job queues by making a copy of the job and running it once in the foreground, but not as a recurrent or scheduled task. Learn more about limitations for delegated admins in ../administration/delegated-admin#limitations-for-delegated-administrators.\n## Task scheduler 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## Operational limits for the task scheduler\nThe Business Central service has limits on how long time a background session can run and how many tasks you can run in parallel with the task scheduler. The background sessions that are started to process scheduled tasks don't have the same concurrency limit as those started by other methods.\nSee Asynchronous task limits<../administration/operational-limits-online#Task>.\n## Monitor and troubleshoot\nBusiness Central offers two ways to monitor the flow of scheduled tasks: telemetry in Azure Application Insights and the Session Event table. These tools let you follow execution of a task, and investigate errors in failure codeunits.\n### Task scheduler 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 is sent to the resource as scheduled task moves through the flow. Learn more in:\nEnable sending telemetry to Application Insights<../administration/telemetry-enable-application-insights>\nAnalyzing 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## Configure task scheduler for Business Central on-premises\nBusiness Central Server includes several settings related to task scheduler. These settings allow you to enable or disable task scheduler and manage tasks. See Configure Business Central Server - Task Scheduler<../administration/server-instance-settings#schedule-server-tasks>.\n> NOTE\n> Task scheduler telemetry in Azure Application Insights also works for Business Central on-premises.\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\nTask Scheduler Data Type<methods-auto/taskscheduler/taskscheduler-data-type>\nAnalyzing Task Scheduler Telemetry<../administration/telemetry-task-scheduler-trace>\ndevenv-job-queue\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>"}