One of the most popular ways of scheduling background processes in Microsoft Dynamics 365 Business Central is by using the Job Queue. In this guide, you will understand how it works and how you can use it. Also, you will learn about error handling along with some general tips.
- What Is The Job Queue In Business Central?
- Job Queue Entry Walkthrough
- The General Tab
- The Recurrence Tab
- Available Actions
- Error Handling
- General Tips
- Error Handling Example
- Telemetry
What Is The Job Queue In Business Central?
The Job Queue is the tool that allows to schedule recurring processes in Business Central. It also logs the result of the job queue, whether it failed or succeeded.
As noted in the previous article it runs on top of the TaskScheduler. See more about it here:
Job Queue Entry Walkthrough
When looking for ‘Job Queue Entries’ in Business Central you will find the list of entries.
We will have a look at a simple example during the walkthrough.
The General Tab
When the Job Queue Entry opens you will find a General Tab and a Recurrence Tab:
In the general tab, you can choose the object to run. It can be either Codeunit or Report. After that, we can select the object number and the earliest start date and time for the process.
You can also set a Timeout. It specifies the maximum time that the job queue entry is allowed to run.
When you click on ‘Show more’, additional fields will populate.
Parameter String. You can set a string for utilizing in a codeunit. Check the following blog post on how it works in detail.
Job Queue Category Code. You can set a Category to organize entry processes. The list of categories can be also accessed by searching ‘Job Queue Categories’.
Maximum No. of Attempts To Run. Specifies how many times a job queue task should be rerun after a job queue fails to run. This is useful for situations in which a task might be unresponsive. For example, a task might be unresponsive because it depends on an external resource that is not always available.
Rerun Delay (sec.). Specifies how many seconds to wait before re-running this job queue task in the event of a failure.
Expiration Date/Time. It will set an end date for the entry. After this date, it won´t be run again and the job queue entry will be deleted automatically.
The Recurrence Tab
When we expand the Recurrence tab we will see the following fields:
In the Recurrence tab, we can set the periodicity of the process. There is a checkbox for every day of the week.
Next Run Date Formula. Specifies the date formula that is used to calculate the next time the recurring job queue entry will run. If you use a date formula, all other recurrence settings are cleared.
Starting Time. Specifies the earliest time of the day that the recurring job queue entry is to be run.
When you set this parameter the field ‘Earliest Start Date/Time’ will change when setting the status to ready.
Ending Time. Specifies the latest time of the day that the recurring job queue entry is to be run.
No. of Minutes between Runs. Specifies the minimum number of minutes that are to elapse between runs of a job queue entry. The value cannot be less than one minute. This field only has meaning if the job queue entry is set to be a recurring job. If you use a no. of minutes between runs, the date formula setting is cleared.
Available Actions
These are the actions available:
Set Status to Ready. Set On Hold. For editing a Job Queue you need the Job Queue entry to be on hold. Once is ready you can set it to ready with ‘Set Status to Ready’.
Show Error. It will show the error message if an error occurred during the process. The Job Queue entry will also change its status to ‘Error’ and won´t run again until set to ready manually.
Restart. It will stop and restart the entry.
Run once(foreground). It will run the process in the foreground. The following blog post covers this option in detail and how to use it via code.
Log Entries. It will take you to the result page of running the process in the background. It can show Error and its message or Success.
Learn more about the job queue and its capabilities in the Microsoft documentation:
Job Queue – Business Central | Microsoft Docs
Error Handling
General Tips
Sometimes, Job Queues can be unstable or act unexpectedly for various reasons. Waldo points out some recommendations in his blog, make sure to check it out.
As stated above, a job queue entry needs to be manually restarted when it fails. On Twitter, Henrik shares a great tip for this scenario. And that is to create ‘single-run’ job queues with a recurring job. In other words, job queues that run only once. And these queues are, at the same time, created with a recurring job queue. With this approach, you make sure that if the process fails there will be a fresh job queue created next time. Leaving the failed queue entry behind.
Now, you only need to make sure that the recurring job that creates the rest is running. This one doesn´t have a heavy process and is less likely to fail. Keeping the heavy logic to the ‘sing-run’ job queues.
See the full thread here:
Error Handling Example
Since October 2021, there are some improvements in the job queue. See the full information here:
As seen in the ‘Task Scheduler’ post, we can use a failure codeunit when a job queue entry fails and subscribe to it. The codeunit is called ‘Job Queue Error Handler’ and has 4 different events available.
Let´s try the ‘OnAfterLogError’ event. In this example, it will insert the error to a custom table called ‘MyErrorTable’. You can also add functionality to send emails notifying about the problem. Basically, anything you wish to handle when a job queue fails.
As you can see, in ‘MyErrorTable’ there is a logged error.
Which comes from the following failed job queue. For this example, I´ve populated the field ‘Error Message’ so you can see it´s the same as the one that comes from the event.
Telemetry
We can also set telemetry for Job Queues with Azure Application Insights.
Find more information here:
And an example of setting up alerts here:
https://github.com/microsoft/BCTech/tree/master/samples/AppInsights/Alerts
That´s all. Hope you find it useful.