D365 Business Central : Upgrade Tags

Last time we talked about AppVersion and DataVersion, and how we can utilize them in our installation and upgrade procedure. Now, let’s talk about Upgrade Tags. Whenever you install your extension, the install or upgrade will be triggered (depending on whether it is an installation or upgrade). When you write an install or upgrade code unit, most of the time, you would want to run it only once, and that is how we can use Upgrade Tags. By using Upgrade Tags, you ensure that your upgrade procedure only runs once.

The idea is straightforward. Before running your upgrade procedure, check whether the Upgrade Tag exists. If the tag exists, you don’t execute it. If the tag doesn’t exist, you run the upgrade procedure and set the tag.

To implement the Upgrade Tag, we will use the Upgrade Tag codeunit. The two main methods we need to focus on are HasUpgradeTag and SetUpgradeTag.

Below is an example that demonstrates how to implement Upgrade Tags. It’s pretty straightforward.

codeunit 60091 "Upgrade Tags_TNG"
{
    Subtype = Upgrade;

    trigger OnUpgradePerCompany()
    begin
        MyUpgradeProcedure();
    end;

    local procedure MyUpgradeProcedure()
    var
        UpgradeTag: Codeunit "Upgrade Tag";
        MyUpgradeProcedureTagLbl: Label 'TNG-0001-DoSomething-20230624';
    begin
        if UpgradeTag.HasUpgradeTag(MyUpgradeProcedureTagLbl) then exit;

        //Do something

        UpgradeTag.SetUpgradeTag(MyUpgradeProcedureTagLbl);
    end;
}

In addition to this, subscribe to the OnGetPerCompanyUpgradeTags event and add your Upgrade Tag there. This step is crucial as it ensures you do not run the upgrade procedure for new company.

codeunit 60091 "Upgrade Tags_TNG"
{
    Subtype = Upgrade;

    trigger OnUpgradePerCompany()
    begin
        MyUpgradeProcedure();
    end;

    local procedure MyUpgradeProcedure()
    var
        UpgradeTag: Codeunit "Upgrade Tag";
    begin
        if UpgradeTag.HasUpgradeTag(MyUpgradeProcedureTagLbl) then exit;

        //Do something

        UpgradeTag.SetUpgradeTag(MyUpgradeProcedureTagLbl);
    end;


    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Upgrade Tag", 'OnGetPerCompanyUpgradeTags', '', false, false)]
    local procedure OnGetPerCompanyUpgradeTags(var PerCompanyUpgradeTags: List of [Code[250]]);
    begin
        PerCompanyUpgradeTags.Add(MyUpgradeProcedureTagLbl);
    end;


    var

        MyUpgradeProcedureTagLbl: Label 'TNG-0001-DoSomething-20230624';
}

That’s the only thing that we need to do to implement it. Very simple.

To define the format for your Upgrade Tag, you can choose any format you prefer. However, Microsoft recommends using the following format: [CompanyPrefix]-[TFSID]-[Description]-[YYYYMMDD]. Example: MS-29901-UpdateGLEntriesIntegrationRecordIDs-20161206.

Upgrade Tags are stored on a per-company basis in Table 9999 Upgrade Tags. Although there is no dedicated page for it, you can access it directly by adding “?table=9999” to your Business Central URL.

Another tip is to use Waldo’s CRS snippet to easily use Upgrade Tag.

That’s it. Now you know how to utilize Upgrade Tags.