Eliminate false-positives in your database comparisons: What every Domino pro should know about the Designer client part 4

November 2, 2019
|By Eric Houvenaghel
Tags: databases Domino Designer DXL IBM Domino IBM Notes IBM Notes and Domino Ultra Compare
lotus-notes-articles-database-comparison

This is post number 4, the final post in a 4-part series where I explore some of my favorite features of Domino Designer, and the tactics I use to make the most out of the Designer client in my own workflow. In this post, we’ll tackle “false positives“ like DXL headers and I’ll walk you through a database application we created for you to do just that.

In post 3, I discussed the way Domino Designer handles legacy-type design elements using DXL. When comparing them using the Designer’s compare feature, information unique to documents is stored in the header and fills your comparison with a ton of false positive results. The header will always be there, and it will always be different, but having to rifle through a bunch of clutter like that is time-consuming and aggravating. I wanted to figure out how to get around this problem.

I explored different options for making an XSLT plugin able to process the DXL and filter out these header parts, leaving only the true differences.

At first, I was unable to find a proper in-point to intercept the compare process in the Designer, but fast forward and I’ve found a solution! Instead of using the Designer, I used a database that exports the designs as DXL and that was specifically built to get rid of false-positives.

And as a bonus, I’m offering this database to you – for free!

Break it down, fix it up, or use as is. It was created to be modified.

Download it here

A fine-tuned database/design comparison

So, what does this database do? It lets you perform a much more detailed and accurate database/design comparison than is possible in the Domino Designer client.

Note: To carry out the comparison, you will need to have a third-party file comparison tool. There are plenty of free ones available. I use UltraCompare, but any solution could work. Ideally, your solution should have the ability to be launched from a command line with some parameters. That way it’s launched right away at the end of the export process.

This database also eliminates the need to check through comparison differences caused by the infamous DXL header information, filtering out these “false-positives” so you can concentrate on the differences that really matter.

Here’s how it works:

It takes the databases you select and uses LotusScript to export the DXL for the designs in the database. However, the DXL is transformed and “cleaned” of all the false-positive information talked about in the previous blogpost about the database comparison in the designer client. That way, when you compare the DXL files, all you’ll see is the information that matters.

The DXL files will be created in 2 different folders, one for each database, and the name of the folder is set using the name of the database. These 2 folders will be created in the Target Directory. These DXL files will be organized depending on the options you choose.

You will need to select which part of the database designs you want to export. So, either export all design elements or a specific selection of design types or families. It could be forms, views, agents, etc. These are, in a way, the same families you have in the Domino Designer.

When you open the database, it will show a simple no-frills UI. It doesn’t look like much, but the functionality will make database code comparisons clear. (fig. 1)

domino-compare

Fig. 1 This database has a no-frills UI but has plenty of fine-tuning ability to make DXL exports of your designs.

All options and fields are relatively self-explanatory. But here’s a run-through so you won’t have to guess about anything.

From the top down, here is the meaning of each option:

  • Launch Export – Once you’ve set everything up, this puts it all in motion.
  • Target Directory – This is the file path where the transformed DXL exports will go.
  • First Database – Like it says, this is the first database in your selection. The first field is for the server name and the second one is for the file path. You can enter it manually. The button next to the text will show the Notes client dialog to select a server and a database. One drawback: database templates won’t be listed here, so you will have to enter them manually.
  • Check Database – This will let you check if the database path you’ve defined here is correct, so you don’t waste time trying to compare a database using a path that doesn’t work.
  • Second Database – This is the second database of the comparison.
  • Output – This section is where you select how the export clusters the data
  • One DXL file per family – This is the faster, but less specific option. It will create one DXL file per type of design element.
  • One DXL file per design element – This will let you make a far more detailed comparison by creating one DXL per design element.
  • All Designs – Select this to export all designs as one unique family. So if you selected previously “One DXL file per family”, it will then export everything as one file. If you selected “One DXL file per design element”, it will put all the DXL files in one folder.
  • Specific Design Family (DXL name) – Here you can choose which types of designs to export.
  • Save DXL Log? – Choose this to save the DXL export log. When the process generates the DXL file, we get logs from the process. These logs can be stored as documents in the current database and viewed in the embedded view (shown at the end the current UI). This is crucial in the case of errors that need to be analyzed further, but most of the time it’s not needed.
  • Compare Exe – Enter the executable of your chosen file comparison tool here. Compare Param – This depends on the solution chosen. By default, these are set to the parameter structure of the UltraCompare command line.
  • Compare Run Path – If the compare exe file is not in the global path of your system it will require a specific running path. In my case, I don’t need it because the UltraCompare I’m using is set in the Windows PATH and can be launched from anywhere.

Note that, at first “One DXL file per family” was the only option available in the database. But after using it, we encountered one major issue with this system. Since DXL files contain more than one design element in this case, there was no easy way to have them sorted – so they are shown in the same order. At times this was making the comparison a bit tricky on big databases. We tried several XLST tricks to solve this, but none ever worked. Also, finding the context of a given difference (the effective design element) may not always be easy, requiring a search for the appropriate DXL tags to find a name of the concerned design element.

Fortunately, the option “One DXL file per design element” fixed this beautifully. It just takes a bit more time to generate all the DXL files.

Let’s see what this database can do

As a quick example, I am going to use two of the exact same databases that I compared in the last Tech lab post on the Designer’s compare feature: zPrincipal.nsf and zOtherApp.nsf.

For the export, I’ll make a DXL file per design element and include all design types.

And here are the results seen in the trial version of UltraCompare (see fig. 2).

domino-compare

Fig. 2 Using a third-party file compare tool, you can now compare your export folders and all the files inside to see a true picture of all the differences. Ultra Compare is seen here.

Like most file comparison tools, UltraCompare provides options to include or exclude files and folders that are equal. So, because the idea of this tool is to cut through the clutter and only see those files that were truly different without all the false positive noise of the DXL headers, I’ve hidden all the equal files. This results in files that are either different between the two databases, or missing from either one—a true comparison of differences.

Just to check and see if everything was exported to begin with, I’ll show the equal files and folders as well (see fig. 3).

domino-compare

Fig. 3 Here we see all files within the export folders to ensure that all files were indeed exported and that nothing is missing.

As you can see, it’s all there.

So, are you ready to use this database to make your own comparisons?

Feel free to make changes to any part of the database. It is yours to do with as you please.

Let me know in the comments if you tried it out and what you used it for.

5 Comments

Submit a comment

  • This field is for validation purposes and should be left unchanged.

Privacy Preference Center

Privacy Preferences