TaskScheduler.CreateTask(Integer, Integer [, Boolean] [, Text] [, DateTime] [, RecordId]) Method

Article
03/20/2024

Version: Available or changed with runtime version 1.0.

Adds a task to be run by the task scheduler. The task is ensured to not run before the specified time.

Syntax

[Task := ]  TaskScheduler.CreateTask(CodeunitId: Integer, FailureCodeunitId: Integer [, IsReady: Boolean] [, Company: Text] [, NotBefore: DateTime] [, RecordID: RecordId])

Parameters

CodeunitId
Type: Integer
Specifies the ID of the codeunit to run.

FailureCodeunitId
Type: Integer
Specifies the ID of the codeunit to run if the task fails. If you do not want to provide a failure codeunit, then use 0.

[Optional] IsReady
Type: Boolean
Sets the task to the ready state. A task cannot run unless it is ready.

[Optional] Company
Type: Text
Specifies the company to run the task for. If you do not specify a company, the task will run in the user’s current company.

[Optional] NotBefore
Type: DateTime
Specifies the date and time that you want to run the task. When the task actually runs will depend on whether other tasks are running at the same time. The task will run the first opportunity on or after the date and time that you specify.

[Optional] RecordID
Type: RecordId
Specifies the recordID of the record that you want to run the task on.

Return Value

[Optional] Task
Type: Guid

Remarks

Scheduled tasks are shown in the Scheduled Tasks page in the client. The TaskScheduler.CreateTask method creates a task and if the operation is successful, the task appears on the page (the implementation is different for the on-premises version compared to the online version of Business Central).

If one or both of the codeunits provided to TaskScheduler.CreateTask don't exist, then the method will throw an error at runtime.

Note

The first two parameters in TaskScheduler.CreateTask are integers, which represent the object IDs of codeunits. To code robustly, never supply the object ID directly in your code as numbers. Instead, use the :: operator as illustrated in the example above. With this technique, if any of the codeunits don't exist, you'll get a compile time error instead of a runtime error.

The TaskScheduler.CreateTask method also has a version that allows you to set a timeout parameter. For more information, see CreateTask(Integer, Integer, Boolean, Text, DateTime, RecordId, Duration)

For more information about the task scheduler, see Using the Task Scheduler.

Example (create a task to run now)

The following example schedules a task to run the MyCodeunit codeunit right now (when resources are available) in the current company and use the codeunit MyErrorhandlerCodeunit as the failure codeunit.

begin
    TaskScheduler.CreateTask(CodeUnit::MyCodeunit, CodeUnit::MyErrorhandlerCodeunit);  
end;

Example (create a task to run after a specified point in time)

The following example schedules a task to run the MyCodeunit codeunit after a specified point in time (60 seconds + a random part of up to three seconds) and when resources are available. It runs in the current company and use the codeunit MyErrorhandlerCodeunit as the failure codeunit.

begin
    TaskScheduler.CreateTask(
        CodeUnit::MyCodeunit, 
        CodeUnit::MyErrorhandlerCodeunit, 
        true, 
        CompanyName, 
        CurrentDateTime + 60*1000 + Random(3000)
    );  
end;