How to create a Job Queue Friendly Codeunit

You can use codeunits in the Job Queue, but how do you make the codeunit “Job Queue Friendly”, check out this video:

https://youtu.be/fjavHACTNUY

In this video, Erik demonstrates how to create a codeunit in AL that is “job queue friendly” — meaning it can detect whether it’s being run from a job queue or manually, and it can leverage job queue parameters to adjust its behavior at runtime. This is a simple but powerful technique that makes your scheduled jobs smarter and more configurable without hard-coding logic or maintaining separate setup tables.

Why Make a Codeunit Job Queue Aware?

In Business Central, you can schedule both reports and codeunits to run via the job queue. But out of the box, a basic codeunit has no idea whether it’s being executed manually or as part of a scheduled job. By making your codeunit aware of its job queue context, you can:

  • Detect whether the code is running inside or outside the job queue
  • Read the Parameter String field (a 250-character free-text field) to accept user-configurable input
  • Use the Job Queue Category Code to branch logic based on the type of job
  • Check schedule properties like Run on Saturdays to vary behavior by day of the week
  • Reuse the same codeunit across multiple job queue entries with different configurations

The Hidden Power of the Job Queue Entry Card

When you create a new job queue entry in Business Central, clicking “Show more” reveals additional fields that are often overlooked. Among them is the Parameter String field — a 250-character string that can contain anything you want. There’s also the Job Queue Category Code, and if you inspect the page further, you’ll find fields like Record ID to Process (used primarily by CRM integration).

These fields are the key to making your codeunits configurable without requiring custom setup tables.

How It Works: The TableNo Property

The secret to making a codeunit job queue aware is surprisingly simple. A codeunit, much like a page, can have a source table. By setting the TableNo property to "Job Queue Entry", Business Central will automatically pass the job queue entry record into the codeunit’s OnRun trigger when it’s executed from the job queue.

Here’s the complete source code:

codeunit 50133 "My JobQueue Job"
{
    TableNo = "Job Queue Entry";
    trigger OnRun()
    begin
        if Rec."Job Queue Category Code" = 'DOTHIS' then
            // Do something specific for this category

        if Rec."Object ID to Run" = 0 then
            // Running outside Jobqueue
        else
            // Running in Jobqueue
    end;
}

Key Points

  • TableNo = "Job Queue Entry"; — This is the critical line. It tells Business Central that this codeunit expects a Job Queue Entry record. The table number for Job Queue Entry is 472.
  • Rec — When the codeunit runs from the job queue, Rec is populated with the full job queue entry record. When run manually (e.g., via Codeunit.Run), the record will be blank.
  • Rec."Object ID to Run" — If this is zero, you know the codeunit was invoked directly rather than through the job queue. This gives you a simple way to branch your logic.

Detecting Job Queue vs. Manual Execution

When the codeunit is run directly (not from the job queue), the Rec variable will be empty — all fields will have their default values. You can use this to detect the execution context:

if Rec."Object ID to Run" = 0 then
    // Running outside the job queue — perhaps show a confirmation dialog
else
    // Running inside the job queue — proceed with automated logic

This is useful because you might want different behavior — for example, showing messages or confirmation dialogs when running interactively, but suppressing them entirely when running as a background job.

Using Parameters and Categories

Once you have access to the job queue entry record, you can leverage several fields to make your job configurable:

Parameter String

The "Parameter String" field is a 250-character text field where users can enter anything — date formulas, filter expressions, command flags, or comma-separated values. Your codeunit can parse this string and act accordingly.

Job Queue Category Code

You can define custom categories and use them to route logic within the same codeunit. For example, you could create categories like DOTHIS or DOTHAT and branch your processing logic based on which category is assigned to the job.

Schedule Properties

You also have access to schedule-related fields like "Run on Saturdays", allowing you to adjust behavior based on when the job is running.

Practical Example

Erik gives a real-world example: imagine a job queue entry that generates customer statements or payment reminders. Instead of hard-coding the lookback period (e.g., “two weeks overdue”), you put a date formula in the Parameter String. When accounting decides to change the threshold from two weeks to three weeks, they simply update the parameter on the job queue entry — no code changes, no redeployment.

Even better, if you need to run the same logic with different parameters — say, one job for domestic customers and another for international customers — you can create multiple job queue entries pointing to the same codeunit, each with its own parameter string.

The App Configuration

For reference, here’s the app.json used in the demo, targeting Business Central version 21 with runtime 10.0:

{
  "id": "bbf88a17-29d5-4592-b6de-76552573009a",
  "name": "JobQueueFriendlyCodeunit",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "platform": "1.0.0.0",
  "application": "21.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "runtime": "10.0",
  "features": [
    "NoImplicitWith"
  ]
}

Summary

Making a codeunit job queue friendly in Business Central is remarkably simple — just set the TableNo property to "Job Queue Entry" (table 472) and your OnRun trigger will receive the full job queue entry record. From there, you can detect whether you’re running in a job queue or manually, read the parameter string for user-configurable input, branch logic based on category codes, and check schedule properties. This approach eliminates the need for hard-coded values and separate setup tables, making your automated jobs smarter, more reusable, and easier for end users to configure.

Picture of hougaard

hougaard