In standard NAV by default the documentation trigger of every object was virginal empty and provided room to partners to document their changes. Until the emergence of the CaptionClass feature in 3.xx (Navision Solutions/Attain) when the documentation trigger of codeunit 1 (ApplicationManagement) got stuffed with an expose of the data definitions and logic behind it.
And then in the course of what later was released as NAV 5.0 extra data appeared in the same documentation trigger. Ever had a closer look at it?
An Example
Let’s abstract it from NAV 2009 SP1 for Spain (ES):
<changelog>
<add id=”es0001″ dev=”VGARCA” date=”2004-08-27″ area=”DATEEXPR” request=”es-start-40″
releaseversion=”ES4.00″>Localization of Date Expressions</add>
<add id=”es0002″ dev=”VGARCA” date=”2004-08-27″ area=”VERSION” request=”es-start-40″
releaseversion=”ES4.00″>Localization of Version Number</add>
<add id=”es0003″ dev=”VGARCA” date=”2004-08-27″ area=”CARTERA” request=”es-start-40″
releaseversion=”ES4.00″>Cartera Add-On (Spanish)</add>
<change id=”es0004″ dev=”VGARCA” date=”2004-06-20″ area=”VERSION” request=”ES-START-40A”
releaseversion=”ES4.00.A” baseversion=”ES4.00″>Localization of Version Number</change>
<add id=”es0005″ dev=”VGARCA” date=”2005-10-21″ area=”MISCELL” feature=”PS-SE-12120″
releaseversion=”ES4.00.02″>Development Standards</add>
<add id=”es0006″ dev=”jhoek” date=”2006-09-04″ area=”UID” feature=”NAVCORS3374″
releaseversion=”ES5.00″>Added GetUIDOffset function</add>
<change id=”es0007″ dev=”VGARCA” date=”2006-11-01″ area=”VERSION” feature=”ES-START-5.00″
releaseversion=”ES5.00″ baseversion=”ES5.00″>Localization of Version Number</change>
<add id=”CA0001″ dev=”SRYSER” feature=”PSCORS417″ date=”2006-01-30″ area=”COSTACCTNG”
releaseversion=”CACEM5.00″>
COD1</add>
<add id=”CF0001″ dev=”TMARTI” feature=”PSCORS339″ date=”2006-04-25″ area=”LIQUIDITY”
releaseversion=”LIQEM5.00″>
Liquidity</add>
<remove id=”es0008″ dev=”TMARTI” date=”2008-07-24″ area=”MISCELL”
baseversion=”ES4.00.02″ releaseversion=”ES6.00″ feature=”NAVCORS26647″>
MISCELL – 129 out of 190+ objects should not be part of this area
</remove>
<change id=”es0009″ dev=”all-e” date=”2009-03-03″ area=”CARTERA” feature=”NAVCORS35301″
releaseversion=”ES6.00.01″ baseversion=”ES4.00″>
Not possible to post invoice with customer license that contain granule 7300</change>
</changelog>
Or in ‘xml coloring’:
<changelog>
<add id=”es0001“ dev=”VGARCA“ date=”2004-08-27“ area=”DATEEXPR“ request=”es-start-40“ releaseversion=”ES4.00“>Localization of Date Expressions</add>
<add id=”es0002“ dev=”VGARCA“ date=”2004-08-27“ area=”VERSION“ request=”es-start-40“ releaseversion=”ES4.00“>Localization of Version Number</add>
<add id=”es0003“ dev=”VGARCA“ date=”2004-08-27“ area=”CARTERA“ request=”es-start-40“ releaseversion=”ES4.00“>Cartera Add-On (Spanish)</add>
<change id=”es0004“ dev=”VGARCA“ date=”2004-06-20“ area=”VERSION“ request=”ES-START-40A“ releaseversion=”ES4.00.A“ baseversion=”ES4.00“>Localization of Version Number</change>
<add id=”es0005“ dev=”VGARCA“ date=”2005-10-21“ area=”MISCELL“ feature=”PS-SE-12120“ releaseversion=”ES4.00.02“>Development Standards</add>
<add id=”es0006“ dev=”jhoek“ date=”2006-09-04“ area=”UID“ feature=”NAVCORS3374“ releaseversion=”ES5.00“>Added GetUIDOffset function</add>
<change id=”es0007“ dev=”VGARCA“ date=”2006-11-01“ area=”VERSION“ feature=”ES-START-5.00“ releaseversion=”ES5.00“ baseversion=”ES5.00“>Localization of Version Number</change>
<add id=”CA0001“ dev=”SRYSER“ feature=”PSCORS417“ date=”2006-01-30“ area=”COSTACCTNG“ releaseversion=”CACEM5.00“>COD1</add>
<add id=”CF0001“ dev=”TMARTI“ feature=”PSCORS339“ date=”2006-04-25“ area=”LIQUIDITY“ releaseversion=”LIQEM5.00“>Liquidity</add>
<remove id=”es0008“ dev=”TMARTI“ date=”2008-07-24“ area=”MISCELL“ baseversion=”ES4.00.02“ releaseversion=”ES6.00“ feature=”NAVCORS26647“>MISCELL – 129 out of 190+ objects should not be part of this area</remove>
<change id=”es0009“ dev=”all-e“ date=”2009-03-03“ area=”CARTERA“ feature=”NAVCORS35301“ releaseversion=”ES6.00.01“ baseversion=”ES4.00“>Not possible to post invoice with customer license that contain granule 7300</change>
</changelog>
Changelog
As you might have guessed this whole thing, called a changelog, is internal change documentation; introduced and used by the former Dynamics GDL (Global Localization Development) team. Actually every local and localized object does contain this kind of information in MS internal source control system Source Depot. However, when building a database, as it eventually might be released, the documentation trigger of each object is fully cleared. Simple as that, with no intelligence whatsoever.
Applied on codeunit 1 this would mean that all the CaptionClass information would also be removed. Ouch. So let’s not do that and exempt codeunit 1 from that, some build engineers have thought. And even though we testers reported it various times this changelog info was never cleared ever since. Ouch.
In the WEMEA team of GDL we used the XML changelog as the input to our local features tracking system called C/Track (guess where this tool was built in). Although it altogether required some discipline to keep the changelog in each object up to date it provided us a terrific tool for:
-
having an overview on the various local features and which objects are included in each feature
-
creating a change log for every major and minor release (you might recall the Changes in Microsoft Dynamics NAV ….htm file on the product CD which disappeared since NAV 2009)
-
easily identify code in C/SIDE objects that belong to a specific feature
-
discriminating between standard (w1) code and local code
-
etc.
So what does a changelog tell me?
First off all a changelog contains a description of every change imposed on the object. Nothing special, that’s what a change log is about, right? But we not only wanted to be able to track changes to an object as such, but also wanted to:
-
track changes to local features, e.g. area=”CARTERA“
-
relate changes to the version it is be released for, e.g. releaseversion=” ES6.00.01“
and of course we also wanted to register:
-
who had implemented the change, e.g. dev=”all-e“
-
when it was implemented, e.g. date=”2009-03-03“
-
due to what change request or bug report, e.g. request=”es-start-40“ or feature=”NAVCORS35301“, typically this linked the change to the change and bug tracking system used by the NAV development organization
-
a short description of the change, e.g. Not possible to post invoice with customer license that contain granule 7300
A changelog can contain three different elements: add, change, and remove. Let’s illustrate their usage on the basis of the Spanish changelog for codeunit 1 (see above).
Add
Typically each first time change to an object for a specific feature (area) should result in an add changelog entry, i.e. by doing this the object is added to the feature (area=CARTERA) and the change is registered
Change
After the first time change to an object for a specific feature (area) any next change should result in a change changelog entry.
Remove
In case an object should no longer part of a feature, i.e. should be removed from this area, the remove changelog entry is used.
So what does the changelog tell me more?
Equipped with all this information I am able to read our example changelog. I can see it’s telling me that codeunit 1:
-
was changed 11 times (you might argue that it was 10 times, as a remove actually does not impose a real change to the object as such)
-
belongs to 7 different local features (though not only Spanish, but more about that later) or actually belonged to 7 areas as it eventually was removed from one (area=”MISCELL“)
-
5 different developers implemented the changes
-
the changes were implemented on 6 different releases
Change ID
Next to all the information as explained so far each changelog entry is uniquely identified by means of a change ID (id). This ID is used in the code to mark the changes (code markers). The standard format of a change id is:
LLDDDD
where LL is either the ISO 2-letter country code or the 2-letter global feature code and DDDD is (unique) serial number starting at 0001.
Apparently the code markers for the last change in our example (id=”es0009“) have not been removed from codeunit 1. Have a look in function trigger AccessToCartera:
// es0009.begin
IF LicensePermission.GET(LicensePermission.”Object Type”::Table, DATABASE::”Cartera Setup”) THEN
IF LicensePermission.”Execute Permission” <> LicensePermission.”Execute Permission”::” ” THEN
EXIT(CarteraSetup.READPERMISSION);
// es0009.end
In our example we these 2-letter prefixes:
- es, used for any Spanish feature
- CA, used for global feature Cost Accounting
- CF, used for the global feature Liquidity (Cash Flow)
Notes
-
You might wonder what will happen if the object itself is removed, i.e. deleted. Well … we will not be able to insert a remove changelog entry.
-
Where clearing the documentation trigger and code markers is always done for major and minor (SP) releases, this does not always apply for regulatory release (RegFs) and hot-fixes. Those who have been involved with installing these might indeed have noticed that changelogs (including code markers) often still reside in these objects.
-
I haven’t touched one attribute: baseversion. When implementing any next change (after a add) the baseversion tells me on what versions the previous change was implemented.
-
The global features are 3 features introduced with NAV 5.0 that are generic, but not released in all countries (rumours say they will be a standard part of NAV 7):
-
Cost Accounting
-
Liquidity
-
Kitting
-