Navigation Comparer

Unofficial Content

The navigation list of a GeneXus object shows the object behavior and it must be analyzed when the GeneXus version is changed (or when the object logic is changed). It is an HTML file created from an XML applying an XSL (Extensible Stylesheet Language). 

The XML file format is not so easy to understand and besides it may vary from one GeneXus version to the other; therefore, comparing navigations of different versions may be difficult. Besides, the tools currently existing in the market to compare two files do not allow comparing the html (they do allow comparing the code, but not the way it is visualized).  To solve this, new xsl's have been created to generate a text file instead of an HTML file for the navigations of the different GeneXus versions. This text file has a unified format as regards GeneXus versions. 

There is also a tool that massively generates the text files for a directory, applying the xsl. This results in having the navigations in text format, thus being able to apply any comparison on them.

Navegacion Comparer Diagram



This tool for navigations comparison may be applied to knowledge bases built with GeneXus 7.5 or higher.  

For knowledge bases from previous versions, we suggest performing an intermediate conversion to GeneXus version 7.5 to be able to use the tool. 

This conversion implies just opening the knowledge base with GeneXus 7.5 and forcedly specifying all the objects (without detailed navigation) with no need of generating.  


Steps to follow in order to compare the files:

1. Do a Build All in both GeneXus versions to specify all the model objects without selecting the "Detailed Navigation" option. When comparing with GeneXus 9.0 we suggest the value NO in the model property Optimize Find Navigation from the Specification group.

2. Make a copy of the NVG directory of version 1 model (located in the directory: GXSPCnnn/GENmm) with the name NVGBASE. This will be the directory with the expected navigations. 

3. Create NVGBASE_TXT and NVGV2_TXT directories where the corresponding text files will be generated.

4. Download the tool from Download Center and unzip the files in a directory. 

5. Execute the tool: "Transform XML Files" (TransformXML.exe) and fill this information:

  • Select Input File or Folder: <path>\NVGBASE
  • Select Output File or Folder: <path>\NVGBASE_TXT
  • Template for Input: <?xml version="1.0" encoding="iso-8859-1" ?>$xmlData$
  • Select Transformation File:
    • spec75To80.xsl (to compare GeneXus 7.5 with 8.0)
    • spec75To90.xsl (to compare GeneXus 7.5 with 9.0)
    • spec80To75.xsl (to compare GeneXus 8.0 with 7.5)
    • spec80To90.xsl (to compare GeneXus 8.0 with 9.0) 
    • spec90ToX.xsl (to compare GeneXus 9.0 with X and X Evolution 1)
    • specXEv1.xsl (to compare GeneXus X Evolution 1 and Evolution 2 with previous versions from GX 9.0)
    • specXEv3_v15.xsl (to compare GeneXus X Evolution 3 with GeneXus 15)


6. Execute the tool "Transform XML Files" to generate version 2 navigations in text format, with the following options:

  • Input Folder: <path>\NVG  
  • Output Folder: <path>\NVGV2_TXT
  • Template for input: <?xml version="1.0" encoding="iso-8859-1" ?>$xmlData$
  • Select Transformation File:
    • spec80To75.xsl (to compare GeneXus 8.0 with 7.5)
    • spec90To75.xsl (to compare GeneXus 9.0 with 7.5)
    • spec90To80.xsl (to compare GeneXus 9.0 with 8.0)
    • specXTo90.xsl (to compare GeneXus X with 9.0)
    • specXEv1.xsl (to compare GeneXus X Evolution 1 and Evolution 2 with previous versions from GX 9.0)
    • specXEv3_v15.xsl (to compare GeneXus X Evolution 3 with GeneXus 15)


7. Compare NVGBASE_TXT and NVGV2_TXT directories with a files comparison tool.  

To minimize unexpected differences, the tool must report the comparison rules definition.

In the case of Beyond*, a file with the rules to be imported before doing the comparison is included (it can be found in the directory where you extracted the files in step 4): 

  • IgnoreRules7580.xml to compare GeneXus 8.0 with 7.5
  • IgnoreRules7590.xml to compare GeneXus 9.0 with 7.5 
  • IgnoreRules8090.xml to compare GeneXus 9.0 with 8.0 
  • IgnoreRules90X.xml to compare GeneXus 9.0 with X or X Evolution 1
  • IgnoreRules_Xev3_V15.xml to compare GeneXus X Evolution with GeneXus 15

In order to import the rules, go to Tools => Import Settings... and select the relevant IgnoreRulesNNN file.

Once the rules were imported, right click on the left page and select "Compare Contents... option. and then select "Rules-based comparison" as shown in the image below.


8. Analyze the differences of these files.

  • The possible differences converting to GeneXus 9.0 are described here
  • The possible differences converting to GeneXus X or higher are described here


We suggest incorporating the navigations comparison as one more stage in the project, which must be performed after changing GeneXus version or the application logic.   

For this, we recommend maintaining NVGBASE directory updated with those navigations expected in XML format. That is to say, if version 2 navigation is correct, copy the navigation xml file to the NVGBASE directory. In this way, by applying points 3 to 6, you can always have the differences that have not been processed yet or detect easily the differences that appear/disappear after applying a change in the knowledge base.

There is not an easy mechanism to maintain this synchronization between text files and xml files directories yet. When you are analyzing the entire knowledge base, doing the synchronization of each file makes the analysis slower; therefore, you can do it afterwards, once you have finished

For this, we suggest identifying the list of text files corresponding to version 1 and version 2 and copy the corresponding xml files generating a .bat.    

Text files directories can be generated each time you need to see the differences. 

Besides, the directory with the xml files of the current navigation is generated each time you want to make the comparison. 

 *Beyond stands for Beyond Compare and can be downloaded from the following link (please download version 2.5.3):