If you’ve developed extensions for any length of time, you’ve probably learned the hard way that “upgrade code” is not where you want surprises.

You’re running in a system session, on customer data, in an environment update window, and whatever you do needs to be repeatable, safe, and fast.

Today, we’ll look at two common ways to control upgrade logic in Business Central:

• Checking versions (What version am I upgrading from?)
• Using upgrade tags (Has this upgrade step already run?)

Both approaches work, and you may often use a mix.

What Is an Upgrade Codeunit?

An upgrade codeunit is a codeunit with SubType = Upgrade; that Business Central executes as part of an extension upgrade.

There are two important scopes:

• Per-company upgrade: Runs once per company.
• Per-database upgrade: Runs once for the whole tenant/database.

A typical upgrade codeunit is structured around the upgrade triggers (preconditions → upgrade → validation). You’ll see these in Microsoft’s “Upgrading extensions” documentation.

Learn more about upgrading extensions and Upgrade codeunit here.

Controlling Upgrade Logic with Version Checks

The “classic” approach is to gate each upgrade step by checking the version you’re upgrading from.

In upgrade code, you can read version information using NavApp.GetCurrentModuleInfo and then compare against ModuleInfo.DataVersion() (commonly interpreted as the data version you’re upgrading from).

Example (simplified):

codeunit 50160 "DVLPR Upgrade"
{
    SubType = Upgrade;

    trigger OnUpgradePerCompany()
    var
        CurrentModuleInfo: ModuleInfo;
    begin
        NavApp.GetCurrentModuleInfo(CurrentModuleInfo);

        // Only run this step when upgrading from versions older than 2.0.0.0
        if CurrentModuleInfo.DataVersion() < Version.Create(2, 0, 0, 0) then
            UpgradeStep_200();
    end;

    local procedure UpgradeStep_200()
    begin
        // data transformation, backfill, etc.
    end;
}

This pattern is straightforward and works well when:

• You have a small number of versions to support.
• Each upgrade step cleanly maps to a specific “from version” range.

Where it gets messy is when you’ve shipped many versions, had hotfixes, or need to make upgrade code resilient against partial runs.

The Problem with Pure Version Checks

Version checks alone don’t tell you whether the step has already executed successfully.

For example:

• A tenant may have attempted an update, failed halfway through, and then retried.
• You may ship a fix that needs to run even if the version comparison still matches.
• You may be backporting an upgrade step into a servicing build.

In those cases, “Did we already run this exact step?” is a better question than, “What version are we upgrading from?”

Upgrade Tags: A Reliable Way to Make Upgrade Steps Idempotent

Upgrade tags are essentially a durable marker that says: “This specific upgrade step has been completed.”

Business Central provides the System.Upgrade codeunit “Upgrade Tag” (ID 9999) for this.

If you ever need to see what tags currently exist in an environment, you can open page 9985 Upgrade Tags to view the stored upgrade tags.

Microsoft Learn reference: Codeunit “Upgrade Tag”

The two methods you’ll use most often are:

• HasUpgradeTag(Tag: Code[250]): Boolean
• SetUpgradeTag(NewTag: Code[250])

(There are also database-scoped methods like HasDatabaseUpgradeTag and SetDatabaseUpgradeTag when you need a tag that applies at the database level.)

Example: Using HasUpgradeTag / SetUpgradeTag in an Upgrade Codeunit

Here’s the basic pattern:

1. Check if the tag exists.
2. If it does, exit (step already completed).
3. Run the upgrade logic.
4. Set the tag.

codeunit 50161 "DVLPR Upgrade With Tags"
{
    SubType = Upgrade;

    trigger OnUpgradePerCompany()
    var
        UpgradeTag: Codeunit "Upgrade Tag";
        Tag: Code[250];
    begin
        Tag := 'DVLPR-50161-PerformUpgradeSomething-20260105';
        if UpgradeTag.HasUpgradeTag(Tag) then
            exit;

        PerformUpgradeSomething();

        UpgradeTag.SetUpgradeTag(Tag);
    end;

    local procedure PerformUpgradeSomething()
    begin
        // data transformation, backfill, etc.
    end;
}

A few notes:

• The tag format is up to you, but make it unique and traceable. A common pattern is CompanyPrefix-WorkItem-Description-YYYYMMDD.
• The critical part is when you set the tag—set it only after the step is complete.

Version Checks + Upgrade Tags Together

In many real upgrades, the best solution is a hybrid:

• Use version checks to decide whether a step is relevant.
• Use an upgrade tag to ensure the step runs once, at most.

Example:

trigger OnUpgradePerCompany()
var
    CurrentModuleInfo: ModuleInfo;
    UpgradeTag: Codeunit "Upgrade Tag";
    Tag: Code[250];
begin
    NavApp.GetCurrentModuleInfo(CurrentModuleInfo);

    if CurrentModuleInfo.DataVersion() >= Version.Create(2, 0, 0, 0) then
        exit;

    Tag := 'DVLPR-200-UpgradeStep-20260105';
    if UpgradeTag.HasUpgradeTag(Tag) then
        exit;

    UpgradeStep_200();
    UpgradeTag.SetUpgradeTag(Tag);
end;

A Practical Reminder: Order Isn’t Guaranteed Across Upgrade Codeunits

One important design point from the platform: If you have multiple upgrade codeunits, the execution order between different upgrade codeunits is not something you should rely on.

Keep upgrade steps independent, or consolidate logically dependent work into a single upgrade codeunit.

Wrapping Up

You can control upgrade code in Business Central by checking versions, but upgrade tags add a second layer of safety: They let you make individual upgrade steps idempotent and resilient across retries and long-lived version histories.

If you’re building an extension that you expect to ship and maintain for years, upgrade tags are one of the best tools you can adopt early on.

Learn more:

• Upgrade tags (HasUpgradeTag, SetUpgradeTag, and more)
• Upgrading extensions (upgrade triggers, version checks, best practices)
• SubType = Upgrade property reference

Note: The code and information discussed in this article are for informational and demonstration purposes only. Always test upgrade code in a sandbox and make sure it behaves correctly on a copy of production data. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online.

If you build extensions long enough, you eventually get burned by a dependency you didn’t mean to create: another app starts calling into your “helper” codeunit, or relies on a table/field you never intended as public API. Later, you refactor—and everything breaks.

That’s the real value of the Access property: it lets you define (at compile time) what’s part of your supported surface area versus what’s strictly internal implementation.

What Is the Access Property?

The Access property sets the compile-time visibility of an AL object (and, for tables, of individual fields). In practice, it controls whether other AL code can take a direct reference to that symbol.

Think of it as the AL equivalent of “public vs internal” in other languages, but scoped to apps (modules) and extension objects.

What the Access Property Applies To

Access applies to:

• Codeunit
• Query
• Table
• Table field
• Enum
• Interface
• PermissionSet

Object-Level Access: Public vs Internal

For most objects (tables, codeunits, queries, interfaces, enums), you’ll typically use:

• Access = Public; (default): Other apps that reference your app can use the object.
• Access = Internal;: Only code inside your app can reference the object.

Example: keep a table internal so nobody else compiles against it:

table 50111 "DVLPR Internal Staging"
{
    DataClassification = CustomerContent;
    Access = Internal;

    fields
    {
        field(1; "Entry No."; Integer) { }
        field(2; Payload; Blob) { }
    }
}

Table Field Access: Local, Protected, Internal, Public

Table fields add two extra options that are incredibly useful for designing clean extensibility:

• Local: Only code in the same table or the same table extension object where the field is defined can reference the field.
• Protected: Code in the base table and table extensions of that table can reference the field.
• Internal: Anything inside the same app can reference the field.
• Public (default): Any referencing app can reference the field.

Example: Table with different field access levels:

table 50140 "DVLPR Access Property"
{
    Access = Public;
    Caption = 'DVLPR';
    DataClassification = CustomerContent;

    fields
    {
        field(1; "Code"; Code[10])
        {
            Caption = 'Code';
            ToolTip = 'Specifies the value of the Code field.';
        }
        field(2; "Local Code"; Code[10])
        {
            Access = Local;
            Caption = 'Local Code';
            ToolTip = 'Specifies the value of the Local Code field.';
        }
        field(3; "Protected Code"; Code[10])
        {
            Access = Protected;
            Caption = 'Protected Code';
            ToolTip = 'Specifies the value of the Protected Code field.';
        }
        field(4; "Public Code"; Code[10])
        {
            Access = Public;
            Caption = 'Public Code';
            ToolTip = 'Specifies the value of the Public Code field.';
        }
        field(5; "Internal Code"; Code[10])
        {
            Access = Internal;
            Caption = 'Internal Code';
            ToolTip = 'Specifies the value of the Internal Code field.';
        }
    }
    keys
    {
        key(PK; "Code")
        {
            Clustered = true;
        }
    }
}

The Access levels for table fields are especially useful when you want to allow controlled extensibility without opening up everything.

If, for example, you have a field with Access = Local, you won’t be able to reference it by name from a page, report, or codeunit—even inside the same app.

One more practical detail from the platform: table and field accessibility affects the in-client Designer. Only Public table fields can be added to pages using Designer.

Sharing Internals Between Your Own Apps: internalsVisibleTo

Sometimes you do want internals shared—but only with your own “companion” apps. That’s where internalsVisibleTo in app.json comes in.

It allows specific friend modules to compile against your Access = Internal objects.

Example app.json snippet:

{
  "internalsVisibleTo": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "DVLPR Companion App",
      "publisher": "DVLPRLIFE"
    }
  ]
}

Important: Access Is Compile-Time Only (Not Security)

This is the part that’s easy to misunderstand.

Access is enforced at compile time. It is not a runtime security boundary.

One way to think about it: Access controls who can compile against your symbols, not who can ultimately interact with data at runtime. Business Central still has reflection-style mechanisms (such as RecordRef, FieldRef, and TransferFields) that can work with tables/fields without a direct symbol reference.

For example, even though the Local Code field is marked as Access = Local, you can still technically read and write it using RecordRef and FieldRef (because those APIs work by field number rather than a compile-time field reference):

    procedure GetLocalCode(): Code[10]
    var
        RecordRef: RecordRef;
        FieldRef: FieldRef;
        LocalCode: Code[10];
    begin
        RecordRef.GetTable(Rec);
        FieldRef := RecordRef.Field(2);
        LocalCode := FieldRef.Value;
        RecordRef.Close();

        exit(LocalCode);
    end;

    procedure SetLocalCode(NewLocalCode: Code[10])
    var
        RecordRef: RecordRef;
        FieldRef: FieldRef;
    begin
        RecordRef.GetTable(Rec);
        FieldRef := RecordRef.Field(2);
        FieldRef.Value := NewLocalCode;
        RecordRef.Modify();
        RecordRef.Close();
    end;

When I Reach for Each Level

My personal defaults:

• Public: Objects/fields I’m willing to support as a stable contract.
• Internal: Implementation objects I expect to refactor freely.
• Protected (fields): When I want controlled extensibility through table extensions.
• Local (fields): Fields that are strictly internal to the table logic.

Wrapping Up

The Access property is one of the most practical tools you have for keeping an extension maintainable over time. It helps you draw a clear line between API and implementation, reduces accidental coupling between apps, and makes your intent obvious to anyone reading your symbols.

Learn more about access modifiers here.

Learn more about the Access property here.

Learn more about internalsVisibleTo in the app.json schema here.

Note: The code and information discussed in this article are for informational and demonstration purposes only. The Access property is available from runtime version 4.0.

What Is a Control Add-in in Business Central?

A control add-in is an AL object you use to embed a custom web-based UI component inside the Business Central client. Think of it as a bridge between the Business Central page framework and HTML/JavaScript/CSS running in the browser client. The client hosts the add-in on a page (typically rendered in an iframe) and loads the JavaScript and CSS packaged with your extension.

The key concept is that Business Central renders the add-in in the client, and you communicate between AL and JavaScript using events (JS → AL) and procedures (AL → JS).

I’ve been having a lot of fun building control add-ins and vibe-coded something fun for the holiday.

You can find the full code for the example on GitHub.

How Control Add-ins Work

When a page that contains a usercontrol is opened, the Business Central web client loads the add-in resources packaged in your extension (JavaScript, CSS, images). The add-in renders into a host container in the page.

From there, the integration is two-way:

• JavaScript raises events back to AL using Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('EventName', [args]).
• AL calls JavaScript functions by invoking procedures declared on the controladdin object (which must exist in your JS runtime).

You can think of it as:

• Events: “JavaScript is telling AL something happened.”
• Procedures: “AL is telling JavaScript to update the UI.”

Creating a Control Add-in Object

To get started, you’ll typically:

1. Create a controladdin object in AL.
2. Add your JS/CSS files to the extension (often under an addin/ or controladdin/ folder).
3. Reference those files from Scripts, StartupScript, and StyleSheets.
4. Define events (JS → AL) and procedures (AL → JS).
5. Place it on a page using a usercontrol.

Here’s the control add-in definition for my holiday example:

controladdin DVLPRControlAddIn
{
    HorizontalShrink = true;
    HorizontalStretch = true;
    MaximumHeight = 300;
    MaximumWidth = 700;
    MinimumHeight = 300;
    MinimumWidth = 700;
    RequestedHeight = 300;
    RequestedWidth = 700;
    Scripts = 'controladdin/scripts.js';
    StartupScript = 'controladdin/start.js';
    StyleSheets = 'controladdin/style.css';
    VerticalShrink = true;
    VerticalStretch = true;

    procedure Animate()
    procedure Render(html: Text);
    event OnControlAddInReady();
    event ShowError(ErrorTxt: Text);
}

A few notes on those properties:

• StartupScript is typically used to bootstrap the control and indicate the initial trigger to invoke on the page that contains the add-in.
• Scripts is where you put the bulk of your implementation (functions that AL procedures call, helpers, etc.).
• StyleSheets is optional, but recommended for maintainability.
• Sizing properties (RequestedHeight, MinimumHeight, VerticalStretch, etc.) help your add-in behave predictably in pages.

Using the Control Add-in on a Page

Once the controladdin exists, you host it on a page via usercontrol. Below is a simple Card page example that:

• Receives a JavaScript event when the control is loaded and ready (JS → AL event).
• Calls JavaScript procedures to render HTML and start an animation (AL → JS procedures).

page 50100 "DVLPR Christmas Tree Page"
{
    ApplicationArea = All;
    Caption = 'Christmas Tree';
    UsageCategory = Lists;

    layout
    {
        area(Content)
        {
            group(controls)
            {
                Caption = 'Merry Christmas!';
                usercontrol(PageControlAddIn; DVLPRControlAddIn)
                {
                    trigger OnControlAddInReady()
                    begin
                        CurrPage.PageControlAddIn.Render(@'
                        <div id="scrolltext">Merry Christmas!</div>
                        <div class="tree">
                            <div class="lights">
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="stump"></div>
                            </div>
                        </div>');
                        CurrPage.PageControlAddIn.Animate();
                    end;

                    trigger ShowError(ErrorTxt: Text)
                    begin
                        Error(ErrorTxt);
                    end;
                }
            }
        }
    }
}

OnControlAddInReady() is your “safe moment” to start calling procedures into JavaScript, because the client has loaded the resources and the JavaScript runtime is initialized.

Note: In Business Central 2025 Wave 1 and later, you can also use the new UserControlHost page type to host control add-ins in a full-page experience.

Learn more about that here.

JavaScript: Rendering UI and Calling Back into AL

Now for the JavaScript side. The easiest pattern is:

• In start.js: signal that the add-in is ready.
• When something happens: call Microsoft.Dynamics.NAV.InvokeExtensibilityMethod(...) with the event name defined in AL. The Business Central client will route that to your AL event handler.

controladdin/start.js

Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('OnControlAddInReady', []);

That InvokeExtensibilityMethod call maps directly to the AL event:

trigger OnControlAddInReady()
begin
end;

So the Business Central client will invoke the trigger OnControlAddInReady() block inside your usercontrol.

JavaScript: Implementing AL Procedures (AL → JS)

If you declare a procedure in the controladdin object, you must implement a matching function in JavaScript so AL can call it.

From the AL object:

    procedure Render(html: Text);

Implement it in a JS file you included under Scripts (for example scripts.js):

controladdin/scripts.js

function Render(html) {
    try {
        document.getElementById('controlAddIn').innerHTML = html;
    }
    catch (e) {
        Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('ShowError', [e.toString()]);
    }
}

Now this AL call will work (it passes HTML to render):

CurrPage.PageControlAddIn.Render(@'
                        <div id="scrolltext">Merry Christmas!</div>
                        <div class="tree">
                            <div class="lights">
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="light"></div>
                                <div class="stump"></div>
                            </div>
                        </div>');

CSS: Keep It Simple and Contained

A small stylesheet helps keep the markup readable:

controladdin/style.css

body {
    display: flex;
    justify-content: center;
    align-items: center;
    height: 100vh;
    background-color: #000;
    color: #fff;
    font-family: Arial, sans-serif;
}

#scrolltext {
    position: absolute;
    top: 50px;
    left: 50px;
    font-size: 24px;
    overflow-x: hidden;
    white-space: nowrap;
}

.tree {
    position: absolute;
    top: 180px;
    left: 320px;
    width: 40;
    height: 0;
    border-left: 50px solid transparent;
    border-right: 50px solid transparent;
    border-bottom: 100px solid green;
    margin-bottom: -30px;
}

.tree:before {
    content: '';
    position: absolute;
    top: -50px;
    left: -25px;
    width: 0;
    height: 0;
    border-left: 25px solid transparent;
    border-right: 25px solid transparent;
    border-bottom: 50px solid green;
}

.tree:after {
    content: '';
    position: absolute;
    top: -80px;
    left: -15px;
    width: 0;
    height: 0;
    border-left: 15px solid transparent;
    border-right: 15px solid transparent;
    border-bottom: 30px solid green;
}

.stump {
    position: absolute;
    top: 190px;
    left: 5px;
    width: 20px;
    height: 20px;
    background-color: brown;
}

.lights {
    position: absolute;
    top: -90px;
    left: -15px;
    width: 30px;
    height: 170px;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
    align-items: center;
}

.light {
    width: 10px;
    height: 10px;
    border-radius: 50%;
    background-color: red;
    animation: blink 1s infinite;
}

.light:nth-child(2) {
    background-color: yellow;
    animation-delay: 0.2s;
}

.light:nth-child(3) {
    background-color: blue;
    animation-delay: 0.4s;
}

.light:nth-child(4) {
    background-color: white;
    animation-delay: 0.6s;
}

.light:nth-child(5) {
    background-color: orange;
    animation-delay: 0.8s;
}

@keyframes blink {

    0%,
    100% {
        opacity: 1;
    }

    50% {
        opacity: 0.5;
    }
}

(Keep your CSS scoped to your own classes so you don’t accidentally affect the surrounding Business Central page.)

Common Pitfalls (That Everyone Hits Once)

• Calling procedures before the control is ready: use OnControlAddInReady() for initialization calls.
• Event name mismatches: the string you pass to InvokeExtensibilityMethod('OnControlAddInReady', ...) (or ShowError) must match the AL event name exactly.
• Trying to do server work in the add-in: treat it as UI; keep business logic in AL/codeunits.

Wrapping Up

Control add-ins are helpful when you need a richer client experience than standard AL page controls can provide. Once you learn the basic rhythm—declare events/procedures in AL, implement the UI in JavaScript, and connect them with InvokeExtensibilityMethod—you can build surprisingly powerful UI integrations (I’ve even created a few games within Business Central—more on that later) while keeping business logic in AL.

Learn more about the control add-in object here.

You can find the full code for the example on GitHub.

Note: The code and information discussed in this article are for informational and demonstration purposes only. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online.