Using upgrade tags to facilitate continuous upgrade

What do you do when you need to kill some time in a hotel before the NAV TechDays break loose? That’s right, write a blog post!
This one has been on my list for quite some time now but there were always more interesting things to blog about, but now it’s time to finally take care of the Upgrade Tags.

Somewhere in the development of Business Central the table Upgrade Tag and codeunit Upgrade Tag Mgt. appeared, but what are they meant for?
Let’s find out!

With NAV2015 we got upgrade codeunits, codeunits that will trigger whenever the Invoke-NAVDataUpgrade cmdlet is called or when the data upgrade is started from the C/SIDE development environment.
Whenever the data upgrade is started, all upgrade codeunits will be triggered and this is exactly what the problem is.
If you deliver your software cumulatively you need to make sure that you either write upgrade codeunits in such a defensive way that executing them again won’t hurt or you should think of some kind of mechanism that knows if a certain upgrade codeunit has been executed already.

This is where Upgrade Tags come into play, the API is really simple, it only contains two straight-forward functions:

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

The API is also accessible from AL but in AL the same can be achieved by using the ModuleInfo data type, however, for logging purposes, it might still make sense to use the upgrade tags.

This is basically all you need to know, in the object itself Microsoft wrote some documentation about how the upgrade tag should be formatted:

In my opinion, the upgrade tag format is something you should decide with your team but I would definitely create a codeunit to format the upgrade tag itself, this way you’re sure that everyone’s using the same format.


So let’s look at an example upgrade codeunit that implements the Upgrade Tag API:

The code is self-explanatory so let’s go straight to the more strict API that implements the custom tag formatting of choice.
I’ve decided to create a new codeunit that implements the exact same API as the Upgrade Tag Mgt codeunit, but then with strict parameters:

We can now implement it like this in our example upgrade codeunit:

This way you’re sure that every developer applies the same formatting and of course, you’re fully flexible to format the tag so that it contains the information that you find important!


Luc van Vugt · November 28, 2018 at 5:00 pm

Thanx for sharing.

And oops, how come MS to call the table Upgrade Tags. IMHO against guidelines where a table name is singular as a table definition describes an entity.

Nikola Kukrika · January 9, 2019 at 3:40 pm

One important thing to add – be sure to insert the tags for the new companies/new installations so they are not triggered for the new company/new users.
In the scenario where the new user would install the latest version we have to make sure we will not trigger the upgrade code on the first upgrade since the tag is missing.

    richardr · January 9, 2019 at 8:36 pm

    You’re totally right, thanks for the addition 🙂

Michał Wardach · March 20, 2019 at 2:12 pm

What were Upgrade Tags created for? What is the idea? What are they for? Is there any documentation for this? Okay, I understand that it’s a codeunit and a table, but what is it created for? I would like to explore the topic, every hint is priceless.

    richardr · March 26, 2019 at 10:32 am

    The Upgrade Tags is a framework for upgrade codeunits, upgrade codeunits are always executed when you start the data upgrade.
    With upgrade tags you can more or less log the upgrade codeunits/functions that have been executed already , so that they won’t be executed again.

Using upgrade tags to facilitate continuous upgrade - Robberse - Dynamics 365 Business Central/NAV User Group - Dynamics User Group · November 21, 2018 at 5:15 pm

[…] Richard Robberse 2018-11-21 5:50 PM 0 comments 0 views Mirror post […]

Leave a Reply

Your email address will not be published. Required fields are marked *