There are several tools that will help us in the upgrading process. Some of them must be used at some point of the upgrade process (like the text format upgrade tool). Some others can be used to help us in the upgrade process, but are not mandatory (like MergeTool). In this section we will explain them all.
Upgrade Toolkit is included in the Microsoft Dynamics NAV 2013 installation media.
For the W1 version of Microsoft Dynamics NAV 2013, Upgrade Toolkit only includes two folders: Data Conversion Tools
and Object Change Tools
. For country versions, it also includes an extra folder: Local Objects
.
In both the Data Conversion Tools
and Local Objects
folders, there are two .fob
files that have to be used in the data upgrade process. If you are upgrading an old W1 version database, the objects found on Data Conversion Tools
should be used. If you are upgrading any old localized version database, use the objects under the Local Objects
folder instead.
In upgrading the data section from the different versions of Microsoft Dynamics NAV, we have explained at what point those objects have to be imported and used.
In the Object Change Tools
folder, there is a .exe
file that will help us transform our new customized objects that have a Dynamics NAV 2009 object definition, into objects with a Dynamics NAV 2013 object definition.
As part of Upgrade Toolkit, there is a folder called Object Change Tools
, which contains a tool called
TextFormatUpgrade2013.
This tool has to be used during the application code upgrade process.
There are several object properties, parts, triggers, text in code, and so on, that are no longer available in Microsoft Dynamics NAV 2013. Some of them have been replaced by other properties, parts, or triggers. Some of them have just been removed.
As part of a code upgrade to Dynamics NAV 2013 we have to get rid of all the old stuff and get a clean object for the new application version.
The text format upgrade tool does the following:
LookupFormID
table and page property with LookupPageID
DrillDownFormID
table property with DrillDownPageID
LookupFormID
and DrillDownFormID
FORM.RUN(FORM::
and FORM.RUNMODAL(FORM::
with PAGE.RUN(PAGE::
and PAGE.RUNMODAL(PAGE::
UseRequestForm
XMLport property with UseRequestPage
MenuSuite
property, RunObjectType
RunFormLink
page property with RunPageLink
CardFormID
page property with CardPageID
RunFormView
page property with RunPageView
SubFormLink
page property with SubPageLink
RunFormMode
page property with RunPageMode
We may have skipped some individual replacements, but we are pretty sure you got the idea. Actually, summarizing, what the tool does is the following:
So now, how do we use that tool? Well, it is a command-line tool that can just take one parameter, so it's pretty easy to use! Just follow these steps:
.txt
format.TextFormatUpgrade2013.exe <PathToTheTxtFileOrFolder>
Which can, for instance, be:
TextFormatUpgrade2013.exe C:ImplementingDynamicsNAV2013OldCustom.txt
Or just:
TextFormatUpgrade2013.exe C:ImplementingDynamicsNAV2013
In this second case, we have just specified the folder containing different .txt
Dynamics NAV files (OldBase.txt
and OldCustom.txt
), and the tool will convert all the text files inside the folder during the same execution.
Converted
inside the directory where the original file was.You can now use those new text files for merging purposes by following the instructions explained in previous sections. If you use the old text files instead, any comparison to the new standard application code of Microsoft Dynamics NAV 2013 will result in hundreds or thousands of modifications purely because of object property changes, even if the object has not changed between two versions. Using those new files instead, will let us just compare real object modifications.
For those who upgrade to Microsoft Dynamics NAV 2013 from Microsoft Dynamics NAV 5.0 or previous versions, or from Microsoft Dynamics NAV 2009 in a classic environment, you have to know that your form objects have to be transformed to pages. Customizations done in standard form objects have to be carried out to the corresponding standard page object and new custom form objects have to be fully transformed to new custom page objects.
This process is not new for Microsoft Dynamics NAV 2013. It was already a requisite if you wanted to upgrade to Microsoft Dynamics NAV 2009 in an RTC environment.
There was a form-transformation tool available with Microsoft Dynamics NAV 2009. You will find the tool in the Microsoft Dynamics NAV 2009 installation media, on a folder called TransformationTool
.
There is no form-transformation tool shipped with Microsoft Dynamics NAV 2013. So, if you have to transform forms into pages, you will have to use the tool shipped with the 2009 version.
We will not explain how to use this tool in this book. If you have never used the tool and want to learn how to use it, you can consult the online help available at http://msdn.microsoft.com/en-us/library/dd338789.aspx.
With Microsoft Dynamics NAV 2009, a new way of reporting was introduced: Reporting Definition Language Client-side (RDLC). The old way of reporting, the classic way, was kept for compatibility reasons to use it with the classic client. That is, in Microsoft Dynamics NAV 5.0 and previous versions, only classic reporting was available; in Microsoft Dynamics NAV 2009, hybrid reporting was available (reporting in classic and RDLC at the same time); and now, in Microsoft Dynamics NAV 2013, only RDLC reporting is available.
For RDLC in Microsoft Dynamics NAV 2009, classic sections were the base to construct the layout of the report, and Report Viewer 2008 was used. In Microsoft Dynamics NAV 2013, the base of the RDLC layout is not the Classic report structure anymore (because it has disappeared). The new report structure is the report dataset. Along with that, RDLC 2005 (the RDLC version used in Microsoft Dynamics NAV 2009) has been upgraded to RDLC 2008, and the report viewer used is the 2010 version.
All of this means that old reports done in previous versions of Microsoft Dynamics NAV 2013 will not run anymore in the new version. They have to be converted to the new report format and structure.
The method of upgrading reports to Microsoft Dynamics NAV 2013 differs for Hybrid reports (those that have both a native Dynamics NAV and a RDLC definition) and Classic reports (those that only have a native Dynamics NAV definition).
The steps required to upgrade a Hybrid report to Microsoft Dynamics NAV 2013 are the following:
.txt
format from a Microsoft Dynamics NAV 2009 database.When the Upgrade Report tool is run, the report data is upgraded to a valid Microsoft Dynamics NAV 2013 dataset definition and the layout is upgraded to RLDC 2008.
The steps required to upgrade a Classic report to Microsoft Dynamics NAV 2013 are the following:
.txt
format from a Microsoft Dynamics NAV 2009 database.To upgrade your application code to a new version of Microsoft Dynamics NAV, you have to compare your customized application code with the old original standard application code to determine which customizations have been made and where they have been made.
A second comparison has to be done, between the old original standard application code and the new original standard application code to determine what differences exist between those two versions, so that we can decide whether the old customized objects can still be used (if the original object hasn't changed) or if the customization has to be manually carried out to the new version of Dynamics NAV.
There are several generic compare text tools that you could use for this purpose. A web search will present you with several tools that you can use. We will not explain any of these tools here. We just want to point out that you can use any of them for application code upgrade purposes.
MergeTool is a third-party application that can be used for free by Microsoft Partners. This application is developed inside Microsoft Dynamics NAV. Using this application to help you out in your application code upgrade will probably save you a lot of time in analyzing text, as it will let you concentrate only on real customizations.
When using any generic text compare tool, you have to deal not only with customizations but also with object structure changes that may exist between a Microsoft Dynamics NAV version and its preceding versions. Dealing with object structure changes is useless.
MergeTool can be downloaded from www.mergetool.com. In the download section of the web page, you will find a ZIP or RAR file containing all the objects of the application. Download it onto your hard disk and unzip the file.
The version of MergeTool at the time of writing was MGT1.30.37. This version contains four .fob
files that can be imported into Microsoft Dynamics NAV 2013, two help files, one Microsoft Visio file, and one readme file.
The steps to install MergeTool are as follows:
MGT1.30.37 NAV7 B33451.fob
file.The steps to install the help files for MergeTool are as follows:
addin_e.hh
to the folder C:Program FilesMicrosoft Dynamics NAV70ServiceENU
in the server where Microsoft Dynamics NAV 2013 services are installed.addin_e.chm
to the folder C:Program FilesMicrosoft Dynamics NAV70RoleTailored Clienten-US
in all PCs where the Microsoft Dynamics NAV 2013 client is installed.MergeTool will allow us to compare our customized application code with the old standard application code and merge the customizations to the new standard application code, creating a new customized application code.
Follow the steps explained in the Upgrade steps in detail section.
OldBase.txt
, OldCustom.txt
, and NewBase.txt
.In this menu you will find everything that can be done with MergeTool.
We will start by importing the old base version of our current Microsoft Dynamics NAV database. That is, the OldBase.txt
file.
To import the old base version, follow these steps:
OldBase.txt
file, give this version a name in field Version, and put a checkmark on Navision Version.In the example we are using, the old version is a Microsoft Dynamics NAV 2009 R2 database. This version has 4232 different objects (excluding forms and dataports), which gets reflected in the version list of MergeTool once the file has been completely imported.
We will now import our old customized database, that is, the OldCustom.txt
file:
OldCustom.txt
file, give this version a name in the Version field, select OLDBASE in the Based on Navision Version Code field and also in the Compare Old Version field, and select Delete Equal Objects.When importing the old custom version, we have selected a version in the Based on Navision Version Code and Compare Old Version fields and have also selected Delete Equal Objects because this will allow us to concentrate only on customizations done on the base code.
By selecting Based on Navision Version Code, the import process will skip those objects in our custom version that do not exist in the base version. Objects that exist in a custom version but do not exist in its base version are objects that have been created for the customization. You don't need to compare them to anything, you will just import those on the new custom database. That's why we skip them.
By selecting Compare Old Version and Delete Equal Objects, the import process will first compare the custom objects against those on the base version and, if they have not changed at all, will skip them. As we have seen on the first import process, a Microsoft Dynamics NAV database has thousands of objects. In a customization, probably not all of them have been customized. Probably only a few dozens or even some hundreds of objects have been modified, but all 7,000 objects are not customized. We want to skip objects that have not been modified because we want to concentrate only on those that have actually been modified.
Once the old custom version has been imported, compared against the old base version, and equal objects have been deleted, our old custom version has only 927 objects. Only 927! We don't need to go through all 4,232 objects for the application code upgrade. We really only need to concentrate on those 927 that have actually been modified. That's great! That will save us a lot of time!
But we can further reduce those 927 objects by a little. How is that? Well, sometimes it happens that you open an object in the design mode through the Object Designer page because you want to check something. You finally leave the object without modifying anything at all, but the editor asks you whether you want to save the changes made to the object or not. If you say yes, object properties such as Date
and Time
will be modified. Since there is something that has changed, even if it's just those object properties, MergeTool has determined that you will have to compare and merge those objects. Wouldn't it be great to be able to delete those objects from comparison so that only real modifications have to be compared and merged?
That is possible with MergeTool. That's cool, right?
Let's see how to delete objects that has only object property changes (date, time, and version list):
If we go back to the Versions list, only 914 objects are on the OLDCUSTOM version now. That means that 13 objects had only object properties changes and have been removed. Great! As we go on, we will be saving more and more time. Now we will only have to concentrate on 914 objects!
Now it is time to import the new base version, that is, the NewBase.txt
file.
NewBase.txt
file, give this version a name in the Version field, place a checkmark on Navision Version, and select OLDCUSTOM in the Must Exist in Version field.When importing the new base version, we have selected a version in the Must Exist in Version field because this will allow us to concentrate only on customizations done on the base code. In previous steps we have seen that only 914 objects were really modified or new in the custom application code used in that example. For the new version, we only want to import those 914 objects. Microsoft Dynamics NAV 2013 has 4,053 objects. But we only want to focus on the 914 that were modified or new in our custom version. For the rest of the objects, we will use the standard objects of Microsoft Dynamics NAV 2013. By selecting the OLDCUSTOM version in the Must Exist in Version field, we are telling MergeTool that we only want to import the new object of the new version if it was an object modified in our custom version.
The result is shown in the previous screenshot. Only 182 objects are shown in the new base version. That means 732 objects that were modified on the old custom version do not exist anymore in Microsoft Dynamics NAV 2013 or they were new customized objects.
The main thing is that now we have just a few objects to concentrate on. Our customizations on those objects will have to be carried out to the new application code version.
To do so, the first thing we need to know is if the standard code for those 182 objects has been modified at all. If there are no modifications in the standard code, carrying our customizations will be easy. If there are modifications in the standard code, we will have to take a closer look to see how to carry out our customizations to the new objects.
Let's first compare the old base and new base versions:
Take a new look at the Versions list. Contrast fields have been updated. A contrast is a group of code lines that have some differences (change in code, added code, or deleted code) respective to the two versions. MergeTool does not treat modifications on a line-by-line basis. It actually treats modifications as groups of line codes.
Imagine the modification in an object consists of creating a new function with hundreds of code lines and a call to that function from within the same object. There aren't hundreds of modifications for the hundreds of code lines added. There are only two modifications: added code for the definition of a function and added code for the call to that function. It's easier to deal with two modifications than with hundreds of modifications. And that's what MergeTool does.
MergeTool groups contrasts in Contrast Headers. There is one contrast header per object in the new base version. Each contrast header may have several contrasts inside.
The screenshot taken after NEWBASE was compared against OLDBASE and it tells us that there are 182 contrasts:
We can navigate to the contrast to analyze the differences. To do so, click on the type of contrast you want to analyze (for all: by clicking on the Contrast Headers field; for equal contrasts: by clicking on the Equal Contrast Headers fields; for changed contrasts: by clicking on the Changed Contrast Headers field; for new contrasts: by clicking on the field New Contrast Headers) and the list of contrasts will be shown. Select then the specific contrast you want to analyze and click on Lines (log), which can be found on the ribbon bar.
In the previous screenshot we can see what a contrast looks like. The code lines in green remain the same in both versions (Line Status is Equal). The code lines in red tell us what the code was on the old version (Line Status is Before). The code lines in orange tell us what the code is in the new version (Line Status is After).
In the example, a line of code has been replaced by three lines of code. Three lines of code are involved in the change but there is only one change—a local variable has been defined for an action in Page 143 Posted Sales Invoices.
In the Contrast Headers list, we can see how many groups of changes exist between the two versions. In the example, we have 182 contrast headers (objects) with a total of 4,018 groups of changes: 330 changes in properties groups, 2,368 changed groups, 893 inserted groups, and 427 deleted groups.
We definitely do not want to deal with all 4018 groups of changes by manually looking at all the differences in code. We want MergeTool to deal with them automatically and just let us decide on those that cannot be merged automatically by the application. That's what we are going to do on the last part of this section.
We will go back to the version list page of MergeTool and we will follow these steps:
If we go back to the MergeTool version list, we will see that a new version, NEWCUSTOM, has been created, with a few objects—the ones that were completely merged automatically.
We will now do a second run of the merge process, unselecting the Skip if Manual Merge field. Once the merge process starts again, when a manual merge is required, the process will prompt a page with all the versions (the old base code, the old custom code, the new base code, and the new merged custom code). MergeTool has merged the changes to the new merged custom code, but we have to decide if we accept the merge or if we want to do any extra modification. Let's see an example of that.
The first subpage corresponds to the old base code. Before, we had the assignation of a value to a field, then a record was inserted into the database, and finally the call to a function to store document dimensions.
The second subpage corresponds to the new base code. On the new application code, there is an extra code line between the assignation of a value to a field and the insertion into the database, and the call to a function to store document dimensions has disappeared.
The third subpage corresponds to the old custom base code. To see the whole customization, we will have to scroll through the subpage. The customization consists of a group of 11 code lines added between the assignation of a value to a field and the insertion of the record into the database.
The fourth subpage corresponds to the new custom code. There is a conflict. The custom code inserts code lines in a specific place and the new code inserts different code lines in the same place. MergeTool cannot automatically merge this because the tool cannot decide if only the custom-added code lines have to be inserted, if only the new code lines have to be inserted, or if both the added code lines have to be inserted in the new custom version; and, in this case, in which order.
Let's take a better look at the fourth subpage, at the proposal made by MergeTool in the following screenshot:
As we can see, the merge proposal consists of using only the customized code. Even the old call to the StoreDocDim()
function has been used in the custom-merged code. MergeTool has made this proposal because of the option Default Manual Merge Lines used on the merge options, which we have left to its default value, Custom. That is, we have actually told MergeTool to use the custom version for the first proposal when merging lines manually.
In this particular example, we actually want both groups of added lines (the ones coming from the old customization version and the ones coming from the new base version) to be added to the new customized version, and we want the call to the function to be deleted from the new customized version, as this function is no longer available in Microsoft Dynamics NAV 2013 because of the dimension functionality redesign.
The way to move code lines from any version to the new customized version in MergeTool is through the New Line Number field that can be found in any of the subpages. If there is a number in the New Line Number field in any line code of the three first subpages, which correspond to the three code versions used for the merge process, that line will show up on the fourth subpage, on the new customized code. The number used in this field will determine the order in which the code lines will be shown in the fourth subpage.
In this particular example, we want to do the following:
StoreDocDim()
function to be on our new customized version.15
to the New Line Number field on the second subpage (new version), to the second line:SalesHeaderArchive.COPYLINKS(SalesHeader);
To do so, we will use the functions found on the Actions tab of the ribbon bar.
In the New Lines action, there are several functions to assign a value to the New Line Number field to code lines in the second subpage, the one corresponding to the new base version.
In the Custom Lines action, we will find the same functions but they apply to code lines in the third subpage, the one corresponding to the old custom version.
The final result is the one that can be seen in the following screenshot:
In the new custom version, we have our customized code and we have the code line added in the new version, and the call to the StoreDocDim()
function is not there anymore.
Once we are done, we will click OK and MergeTool will move on to the next merge conflict.
Once we are done with the whole merge process and we have a good new custom version, we can go back to the MergeTool versions list and export this version as a .txt
file. To do so, there is an action in the Actions tab of the ribbon bar, called Export Object Text File. Select NEWCUSTOM as the version to export and select a destination folder and file name.
The last part of the merge process is to get a new database, with all the new objects, and import into that database the .txt
file we have just exported with the customizations merged into the new code version. After importing the .txt
file, we will have to compile all objects and solve any additional issues that may exist.
And that's it. We have a brand new full application code with standard objects for all those objects that we have not modified in the old version and with the customizations carried out to this new version.
We would still have to import into that new database the new objects created in our customization. To do so, we will first have to do the following: