Job Queue

Erik's ToolBox integrates with the standard Business Central Job Queue to allow you to schedule saved programs for automatic, unattended execution. Instead of manually opening the Run Programs page and clicking Run, you can configure a program to execute on a recurring schedule -- nightly, hourly, weekly, or at any interval that Business Central's Job Queue supports.

This chapter covers how the Job Queue integration works, how to set up scheduled programs, how to monitor their execution, and the important differences between interactive and unattended program execution.

What Job Queue Integration Does

The Job Queue integration connects two systems:

Erik's ToolBox Run Programs -- where your saved AL scripts live.
Business Central Job Queue -- the built-in scheduling engine that runs tasks automatically at configured times.

When you schedule a ToolBox program through the Job Queue, Business Central automatically executes the program at the times you specify. The program runs in the background without any user interaction. The Job Queue Executor codeunit handles the execution, reading the program's CodeBlob from the Program table, passing it through the ToolBox execution pipeline, and capturing the results.

This means you can take any program that you have written and tested interactively, and turn it into an automated task with just a few clicks. The same code runs in both scenarios -- the only difference is whether a user triggers the execution manually or the Job Queue triggers it on a schedule.

The Job Queue Executor Codeunit

The Job Queue Executor codeunit is the bridge between Business Central's Job Queue engine and the ToolBox execution pipeline. When a Job Queue Entry fires for a ToolBox program, Business Central calls this codeunit, which then:

Reads the program record from the Program table.
Extracts the AL source code from the CodeBlob field.
Passes the source code through the Lexer, Parser, and Interpreter.
Captures the console output and execution results.
Stores the results so they can be reviewed later.

You do not interact with this codeunit directly. It operates behind the scenes whenever a scheduled ToolBox program runs. Understanding that it exists helps you troubleshoot issues and understand the execution flow when reviewing Job Queue Entry logs.

Setting Up a Scheduled Program

Scheduling a program for automatic execution is a straightforward process. Follow these steps:

Step 1: Save Your Program in ToolBox

Before you can schedule a program, it must be saved in the Program table. If you have not already created and saved your program, follow the instructions in Creating Programs to write, test, and save your script.

Ensure that your program is fully tested and works correctly when run interactively. Debugging a program that only runs in the Job Queue is significantly more difficult than testing it in the interactive editor.

Step 2: Open Run Programs

Navigate to the Run Programs page in Business Central. You can find it by searching for "Run Programs" in the Business Central search bar or by navigating through the ToolBox area.

Step 3: Select the Program

In the Run Programs list, find and select the program that you want to schedule. Make sure you select the correct program -- verify the name and, if needed, run it once interactively to confirm it behaves as expected.

Step 4: Use the Add to Job Queue Action

With the program selected, click the Add to Job Queue action. This creates a new Job Queue Entry in Business Central that is linked to your ToolBox program and configured to use the Job Queue Executor codeunit for execution.

Step 5: Configure the Schedule

After clicking Add to Job Queue, Business Central opens the Job Queue Entry card for the newly created entry. Here you configure the execution schedule:

Earliest Start Date/Time: Set when the program should first run. If you want it to start immediately, leave this as the current date and time.
Recurrence: Configure how often the program should repeat. You can set it to run:
- Daily at a specific time.
- On specific days of the week (for example, every Monday, Wednesday, and Friday).
- At a fixed interval (for example, every 60 minutes during business hours).
- Once for a single scheduled execution.
Expiration Date/Time: Optionally set a date after which the Job Queue Entry should stop running.
No. of Minutes between Runs: For recurring tasks, specify the interval in minutes between executions.

Once you have configured the schedule, set the Job Queue Entry status to Ready to activate it. Business Central will begin executing the program according to your schedule.

The Business Central Job Queue Entry Page

The standard Business Central Job Queue Entries page is where you manage all scheduled tasks, including those created for ToolBox programs. You can access it by searching for "Job Queue Entries" in Business Central.

From this page, you can:

View all scheduled ToolBox programs alongside other Job Queue tasks in your system.
Edit the schedule of an existing entry by changing the recurrence, start time, or other settings.
Pause execution by setting the status to On Hold.
Resume execution by setting the status back to Ready.
Delete entries for programs that no longer need to run on a schedule.
View the Job Queue Log to see the history of past executions, including successes and failures.

Each Job Queue Entry for a ToolBox program is linked to the Job Queue Executor codeunit and references the specific program that should be executed. You can identify ToolBox entries by looking at the Object ID to Run field, which references the Job Queue Executor codeunit.

Monitoring Execution

When programs run through the Job Queue, you are not present to watch the console output in real time. Monitoring the execution and reviewing results requires a different approach than interactive execution.

Checking Job Queue Entry Status

The Job Queue Entries page shows the current status of each entry:

Status	Meaning
Ready	The entry is active and will run at its next scheduled time.
In Process	The program is currently executing.
Finished	The entry ran successfully and has completed (for one-time entries).
On Hold	The entry is paused and will not run until set back to Ready.
Error	The last execution failed. Review the error message for details.

Viewing the Job Queue Log

The Job Queue Log Entries page provides a history of all executions for each Job Queue Entry. For each execution, you can see:

The date and time when the execution started and ended.
Whether the execution succeeded or failed.
The error message if the execution failed.
The duration of the execution.

You can access the log from the Job Queue Entry card by clicking the Log Entries action.

Downloading Results

After a scheduled program has run, you can review its output by opening the Run Programs page, selecting the program, and using the Download Result action. This retrieves the results from the most recent execution, whether it was triggered manually or by the Job Queue.

For programs that write data to Excel, the Download Result action allows you to retrieve the generated Excel file with the program's output.

Console Output Logging

When a program runs through the Job Queue, its message() output is still captured by the ToolBox engine. While the output is not displayed on screen in real time (since there is no interactive session), it is stored and can be retrieved after execution. This makes it possible to review what the program did, what data it processed, and what results it produced, even though no one was watching during execution.

Error Handling in Scheduled Execution

Error handling is particularly important for programs that run unattended through the Job Queue. When a program encounters an error during interactive execution, you see the error immediately and can take corrective action. When the same error occurs during a scheduled run, it may go unnoticed until someone checks the Job Queue status.

How Errors Are Reported

When a scheduled program fails, the Job Queue Entry status changes to Error, and the error message is recorded in the Job Queue Log. The entry will not run again until you review the error and either fix the issue or manually reset the entry status.

Writing Error-Resilient Programs

To minimize the impact of errors in scheduled execution, follow these practices:

Use error handling in your code. Wrap operations that might fail in appropriate error handling logic. Instead of letting the entire program crash when a single record fails to process, log the error and continue with the remaining records:

var
    Cust : Record Customer;
    ErrorCount : Integer;
begin
    if Cust.FindSet() then
        repeat
            // Process each customer...
            // If individual processing fails, increment ErrorCount
            // and continue to next record
        until Cust.Next() = 0;

    if ErrorCount > 0 then
        message('Completed with %1 errors. Review output for details.', ErrorCount);
end;

Include summary output. Even though no one watches the execution in real time, include message() calls that summarize what the program did. This information is captured in the console log and can be reviewed after the fact:

message('Job started: %1', CurrentDateTime());
// ... processing logic ...
message('Job completed: %1', CurrentDateTime());
message('Records processed: %1', ProcessedCount);
message('Records skipped: %1', SkippedCount);
message('Errors: %1', ErrorCount);

Use commit() appropriately. In long-running programs, use commit() at appropriate intervals to save progress. This prevents a late-stage error from rolling back all the work the program has already done. However, use commit() judiciously -- committing too frequently can affect performance, and committing at the wrong point can leave data in an inconsistent state.

Differences Between Interactive and Job Queue Execution

While the same code runs in both interactive and Job Queue modes, there are important behavioral differences to be aware of:

No User Interaction

The most significant difference is that Job Queue execution has no user interface. This means:

confirm() does not work. Any confirm() call in your code will fail because there is no user present to respond to the dialog. If your program uses confirm() for safety checks before destructive operations, you must handle the unattended case differently.
strmenu() does not work. Menu selections require a user to choose an option, which is not possible in Job Queue mode.
page.RunModal() does not work. Opening pages for user interaction is not supported in background execution.

If your program needs to support both interactive and scheduled execution, include logic to detect the execution context and skip interactive elements when running in the Job Queue.

No Real-Time Output

In interactive mode, console output appears immediately as each message() call executes. In Job Queue mode, the output is captured but not displayed until someone retrieves it after execution. Design your output with this in mind -- include timestamps, record counts, and summaries that make sense when reviewed after the fact.

Session Context

Job Queue entries run under the user account specified in the Job Queue Entry. This means:

The program runs with the permissions of the Job Queue user, not the user who created the program.
Any user-specific settings or filters apply to the Job Queue user's session.
Ensure the Job Queue user has sufficient permissions to access all tables and perform all operations that the program requires.

Transaction Handling

In interactive mode, each Run execution is typically a single transaction. In Job Queue mode, the same applies, but the consequences of transaction errors are different because there is no user present to respond to an error dialog. This makes proper use of commit() and error handling more critical in scheduled programs.

Common Use Cases for Scheduled Programs

Nightly Data Processing

Schedule programs that perform end-of-day operations such as recalculating summary fields, updating status flags, or archiving records that are no longer active. Set these to run after business hours to avoid impacting system performance during the workday.

Scheduled Reports

Programs that generate data summaries or export data to Excel can be scheduled to run at the start of each business day. Users can then download the latest report results when they begin work.

Automated Data Cleanup

Programs that clean up temporary records, purge old log entries, or remove orphaned data can run on a weekly or monthly schedule to keep your database clean without manual intervention.

Periodic Reconciliation

Schedule programs that cross-check data between tables, verify totals, or validate business rules on a regular basis. These programs can flag inconsistencies in their console output for review.

Recurring Data Imports

If your organization regularly receives data files that need to be imported into Business Central, a scheduled program can process these imports automatically at defined intervals.

Tips for Successful Job Queue Programs

Test Interactively First

Always test your program in the ToolBox editor before scheduling it. Verify that it produces the expected results and handles edge cases correctly. It is much easier to debug a program in the interactive environment than to troubleshoot a failed Job Queue execution.

Handle Errors in Code

Do not rely on the Job Queue to handle errors for you. Write your program so that it catches and logs foreseeable errors, continues processing when possible, and provides a clear summary of any issues. A program that reports "3 of 500 records failed to process" is far more useful than one that simply crashes on the third record.

Use commit() Appropriately

For long-running programs that process many records, include commit() calls at logical checkpoints to save progress. This ensures that if the program fails partway through, the work it has already completed is preserved. Place commit() calls after completing a logical unit of work, such as finishing a batch of records or completing a processing phase.

Avoid User Interaction Functions

Remove or conditionally skip confirm(), strmenu(), and any other functions that require user input. These functions will cause your program to fail when running in the Job Queue because there is no user present to respond.

Include Comprehensive Logging

Since you cannot watch the program run in real time, include detailed message() output that records what the program did, how many records it processed, and any issues it encountered. This log is your primary diagnostic tool for understanding what happened during a scheduled run.

Monitor Regularly

Make it a habit to check the Job Queue Entries page periodically to verify that your scheduled programs are running successfully. Set up a routine to review the Job Queue Log for any failures or unexpected behavior. Catching problems early prevents them from compounding over time.

Set Appropriate Schedules

Choose execution schedules that match the business need and system capacity. Running a data-intensive program during peak business hours may affect system performance for other users. When possible, schedule heavy processing tasks for off-peak hours.

Limitations

The Job Queue integration has several limitations that you should be aware of:

No user interaction. As discussed above, confirm(), strmenu(), and modal page operations are not available in Job Queue mode. Programs must run without any user input.
Session constraints. Job Queue entries run under a specific user session with its associated permissions and settings. The program cannot access resources that the Job Queue user does not have permission to use.
Error recovery. When a Job Queue entry fails, it stops executing until someone manually reviews the error and resets the entry. There is no automatic retry mechanism beyond what the standard Business Central Job Queue provides.
Execution time. Very long-running programs may be affected by session timeouts or Job Queue timeout settings. If your program needs to process a large volume of data, consider breaking it into smaller batches that run at separate intervals.
No real-time monitoring. You cannot watch the program's console output as it executes. All monitoring must be done after the fact by reviewing logs and downloaded results.

Troubleshooting

The Job Queue Entry Shows "Error" Status

Open the Job Queue Entry and review the error message. Common causes include:

Permission errors. The Job Queue user does not have permission to access a table or perform an operation that the program requires. Verify that the user has the necessary permissions.
confirm() calls in code. The program contains confirm() or other interactive functions that cannot run in the Job Queue. Edit the program to remove or conditionally skip these calls.
Data-dependent errors. The program encountered unexpected data (for example, a record it expected to exist was missing). Review the program logic and add error handling for these cases.
Timeout. The program took too long to execute and was terminated by the Job Queue. Optimize the program or break it into smaller tasks.

The Program Runs but Produces No Output

Verify that the program includes message() calls to produce output. If the program processes data silently without any message() output, there will be nothing to review after execution. Add logging statements to your program.

The Program Works Interactively but Fails in Job Queue

This is usually caused by one of the behavioral differences described above -- most commonly a confirm() call that works in interactive mode but fails in Job Queue mode. Review your program for any functions that require user interaction and modify them for unattended execution.

Results Are Not Available After Execution

Ensure you are looking at the correct program in the Run Programs page. Use the Download Result action to retrieve the output. If no results are available, check whether the Job Queue Entry actually ran by reviewing the Job Queue Log Entries.