Task Scheduler
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.
Create and manage scheduled tasks in AL
A 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.
In AL code, you create and manage the tasks by using the AL methods that are available for the TASKSCHEDULER data type.
| Method | Description | For more information, see... |
|---|---|---|
| CreateTask | Adds a task to run a codeunit at a specified date and time. | TaskScheduler.CreateTask(Integer, Integer [, Boolean] [, String] [, DateTime] [, RecordId]) Method TaskScheduler.CreateTask(Integer, Integer, Boolean, String, DateTime, RecordId, Duration) Method |
| SetTaskReady | Sets a task to the Ready state. A task can't run until it's Ready. | TaskScheduler.SetTaskReady(Guid [, DateTime]) Method |
| TaskExists | Checks whether a specific task exists. | TaskScheduler.TaskExists(Guid) Method |
| CancelTask | Cancels a scheduled task. | TaskScheduler.CancelTask(Guid) Method |
To 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.
How task scheduler works
This section describes the flow that a scheduled task goes through.
General flow
When 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.
Here's a general overview of the process:
When a task is created, the task is recorded in table 2000000175 Scheduled Task of the database.
When task achieves the ready state and it's scheduled time occurs, a new background session is started.
The main path starts:
The company is opened and the scheduled task in the table 2000000175 Scheduled Task is validated.
If any error occurs during this phase, the task fails unless there's a failure codeunit. In which case, the failure code will run.
The task's main codeunit is run:
- If main codeunit runs successfully, it's removed from table 2000000175 Scheduled Task.
- If an error occurs, the error is passed on to the exception path.
The exception path starts:
The transaction is rolled back.
The exception handling logic is run:
If the exception is retriable, the main codeunit is rerun following the main path.
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 will be retried, see Retry Intervals.
If the exception isn't retriable and there's no failure codeunit, the task fails.
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.
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.
Detailed flow
The following diagram illustrates the flow in detail.
Retry intervals
When a task's main codeunit or failure codeunit enters the retry flow, it will be rerun 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.
Online
A codeunit will be retried up to 99 times, according to the following intervals:
| Retry attempt | Wait time (minutes) after previous attempt |
|---|---|
| 1 and 2 | .5 |
| 3 and 4 | 1 |
| 5 and 6 | 2 |
| 7 and 8 | 3 |
| 9 to 99 | 5 |
On-premises
A codeunit will be retried up to nine times, according to the following intervals:
| Retry attempt | Wait time (minutes) after previous attempt |
|---|---|
| 1 and 2 | 2 |
| 3 | 4 |
| 4 to 9 | 15 |
Error conditions and retriable exceptions
A task can fail under the various conditions, like:
- The company can't be opened.
- A SQL connection or transient error occurred with the database.
- The Dynamics 365 Business Central service instance restarted while the task was being run.
- An upgrade is in progress.
The 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.
Retriable exceptions in the main codeunit
If 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.
Retriable exceptions in the main codeunit
Because 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.
About task sessions and permissions
The 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. For more information about specific dialog boxes, see StartSession method.
The 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.
Note
The device users and delegated admins can't schedule the tasks. To know the restrictions for device users, see Device licenses.
Delegated admins 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. To know more about limitations for delegated admins, see Restricted access to Business Central as delegated administrators.
Monitor and troubleshoot
Business Central offers two ways to monitor the flow of scheduled tasks: Azure Application Insights and the Session Event table. These tools let you follow execution of a task, and investigate errors in failure codeunits.
Application Insights
You can set up Business Central to send telemetry traces to an Application Insights resource in Azure. Once set up, telemetry data will be sent to the resource as scheduled task moves through the flow. For more information, see:
Enable Sending Telemetry to Application Insights
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.
Configure task scheduler for Business Central on-premises
Business Central Server includes several settings related to task scheduler. These settings allow you to enable or disable task scheduler and manage tasks. For more information, see Configure Business Central Server - Task Scheduler.
See Also
Task Scheduler Data Type
Developing Extensions
Get Started with AL
Feedback
Submit and view feedback for