Database comparison functionality: what every Domino pro should know about the Designer client part 3

December 20, 2018

announcing-complimentary-addon-eliminate

This is post number 3 in a series of 4 posts exploring some of my favorite features in the Domino Designer, and the tactics that I’ve used to make the most out of the Designer client in my own workflow. I hope to draw attention to some features that are on my list of essentials (but perhaps less known to some), as well as discuss their pros and cons.

I don’t know about you, but I make extensive use of templates in my work. I have templates within templates, databases referencing a template that in turn references another template. So, with all this inheritance going on, sometimes when I want to update designs I need a quick way to get my bearings in the linkage of databases and templates. I need a way to see that my views, libraries, and other design code are all up to date throughout the line of inheritance. I need to be able to see where any differences start and stop, or to see if database replicas on different servers are in sync with each other. This is where the comparison function in the Designer client comes in to my workflow. That’s what I’m going to talk about today.

Why compare databases?

In my experience, there are two main reasons why you’d want to compare databases:

The user wants to compare two pieces of code (a piece of LotusScript or a form or view, for example) to see if it’s been implemented consistently.
A far more important reason is because (as I already mentioned about my own situation) in Notes there is a lot of work that gets done using templates, and the user will eventually want to know if databases are using the latest version of a template. They’ll need to find out if a design is up to date in a given database. Templates involve refreshing or replacing of designs, so there’s always the need to know whether the refresh has been done at the proper time.
I do almost all Ytria’s Notes development work myself, but I can imagine the types of confusion that can be introduced when multiple team members are contributing to projects. When you start modifying templates that have a lot of databases inheriting from them, things can get blurry quite fast. So, eventually you’ll want to see where (if any) designs differ. And for that, the Domino Designer offers a pretty powerful solution with its Eclipse-based comparison feature.

Better with the Eclipse Navigator

There’s something to keep in mind before comparing anything. The “normal” Designer selection in the Applications pane is limited to a scope of one database at a time. That means the comparison options are also limited, in this case limited to comparing two different designs within the same database to “each other.” And that’s not very helpful—when you compare two different, unrelated designs, it’s almost certain that you’ll find a lot of differences.

The comparison feature really shines when used in tandem with the Eclipse-based Navigator. If you don’t have this enabled, you can find it by selecting in the top menu ‘Window > Show Eclipse Views > Navigator’ (see fig. 1). In the Navigator, there are no limits in selection scope, although there are some practical limits to the effectiveness of a database comparison beyond 2 or 3 at once.

Fig. 1 The comparison feature really shines when used with the Eclipse-based Navigator.

How to compare designs across databases

Let’s jump right in with a practical example that I’ve set up to show some of the types of things a comparison will reveal, and how the results look. It’s a situation involving three resources: template and two databases that inherit from it (see fig. 2).

Fig. 2 Here’s a common simple situation that will illustrate the database comparison feature: a template and two databases that both use it

I already know what the differences are between the template and the two databases. Here is what I have set up:

In the template zTemplate.ntf, I added an agent named Just Run, and then, AFTER refreshing the design of the other 2 databases I added a view named New Review Status.
In the database zPrinicpal.nsf I did the following
Changed the form named Document (added a field)
Ran the agent named Just Run
Changed the LotusScript library named DiscussionRoutines (added a Sub)
In the database zOtherApp.nsf I did the following
Added the view Another Author
Ran the agent named Just Run
Enabled the scheduled agent Process Late Reviews

So let’s run through the comparisons and see if all these changes are picked up, so you’ll know what you’d be looking at if you see something similar in your own comparisons.

Comparison #1

I’ll start by comparing the database zPrincipal.nsf to the template zTemplate.ntf (compare by selecting the two resources in the Navigator, and then right-click and select ‘Compare with > Each Other’).

Only the differences will be shown in the Structure Compare pane. This is good, but here we can already see see one of the limitations of the comparison. As I mentioned in the previous blogpost in this series, certain (legacy) design elements are converted to DXL in order to be handled by the Designer. And because of this, common note information such as NoteID, access dates, etc. are stored in the document header. This type of information is by nature different in every element. So even though only the differences are shown, you’ll see a lot of “false positives” due to this type of information being present in all legacy design elements (see fig. 3).

Fig. 3 Only differences will be shown when you compare. But there is some information that is necessarily different in all design elements. This gives you a lot of false positives in your results.

One thing that can help you sort out which designs are showing up due to things like differences in NoteID or ReplicaID from those that truly have coding differences is the small “map” to the right of the comparison results (fig. 4). Note also that all differences are highlighted in content display, and broken down by blocks of code, not by line number.

Fig. 4 A small “map” of the differences found is shown to the right of the comparison results.

You can use this map to your advantage because all this “obviously different” information will be located in the header area, at the top of the map. So as you flip through the results, you can easily see whether the differences are in the header, or further down in the code where the actual differences are.

So, let’s dive into the real differences found in this specific template/database comparison, going in the order that the results are shown in the tree.

The database properties is the first with notable differences. The differences in the properties are shown here, and that’s not surprising because, among lots of other things, the ACL is different between the two resources (fig. 5).

Fig. 5 ACL differences are clearly shown in the database properties.

Moving on through the code into agents, we can see that the agent Just Run.lsa shows a run date in the database zPrincipal.nsf while zTemplate.ntf has no date. Also note the side map indicating differences outside of header content (see fig. 6).

Fig. 6 As expected, the agent Just Run.lsa shows a run date on one side, and not on the other. Note the side map’s indication of differences outside the header content.

The next differences that we’ll find are in LotusScript. Only the LotusScript that has been changed will be shown—there is more LotusScript in the database, but since it hasn’t changed, it will not be shown. LotusScript is never converted to DXL, so there is no different header info to flag. This also means that any differences flagged are worth looking into. We can see that there is an addition in the database zPrincipal,nsf, and there are also some additions in zTemplate.ntf (see fig. 7).

Fig. 7 The comparison shows some differences (additions) in both zPrincipal.nsf and zTemplate.ntf.

Moving on through the forms, we can see that the form Document.form shows up in the list of differences. And by looking closer, we see that the addition of a field can really wreak havoc when it comes to differences in the code. Adding in a field caused the rest of paragraph IDs from that point on to shift, resulting in a long list of changes when, in reality, only one change was made—as shown in the comparison (see fig. 8). This is NOT always the case, all the more reason to be vigilant.

Fig. 8 Adding a field to a form caused the paragraph IDs to shift, registering a long list of changes.

Coming to the end of the list of changes, we can also see that the view I added in the template (no design refresh) is also shown as missing in the database zPrincipal.nsf (see fig. 9).

Fig. 9 A view is completely missing from the database zPrinicpal.nsf in this example.

So that basically does it for all the known differences between the template zTemplate.ntf and the database zPrinicpal.nsf. Nothing else was signaled, which is very reassuring.

Comparison #2

Now let’s take a quick look at a comparison between the two databases zPrincipal.nsf and zOtherApp.nsf.

Once again, database property differences are expected and shown.

The agent Just Run.lsa is once again here in the differences. The agent was run here, too, so we can see differences in the run data (see fig. 10).

Fig. 10 Agent run data shows as different between two databases.

We can also see that the enabling of the scheduled agent Process Late Reviews also registered a change in the agent between the two databases (see fig. 11).

Fig. 11 Comparing an enabled agent in one database to the same agent but disabled in another database will show a difference.

In the LotusScript, we can see that the changes made in the database zPrincipal.nsf and not in zOtherApp.nsf are shown here (see fig. 12).

Fig. 12 As expected, differences in the LotusScript are indicated as well, because changes were made in zPrincipal.nsf and not zOtherApp.nsf.

Fig. 13 When making a three-way comparison, you’ll be able to choose the common ancestor.

Running the comparison of all three at once yields the following results.

The database properties are shown as being different between the three. Which is completely understandable (see fig. 14).

Fig. 14 The database properties are different among the three compared elements.

Continuing to the agents, we come to the agent Just Run.lsa. And in the comparison it’s shown as different among all three. The comparison also attempts to differentiate how the content is different between all three, whether the code blocks are missing from some, or if the blocks are there but different (fig. 15).

Fig. 15 In a three-way comparison, the results attempt to indicate what is different because the information is simply missing, or what is different because the information is there but different.

Into the LotusScript, which we already know is different from the comparison between zTemplate.ntf and zPrincipal.nsf. We can see that the three-way comparison results don’t show differences between all three. It instead indicates that differences were found between zPrincipal.nsf and zOtherApp.nsf (see fig. 16). And upon further examination we can see that the LotusScript in zOtherApp.nsf and zTemplate.ntf is the same.

Fig. 16 This LotusScript is not indicated as being different in all three parts of the comparison. We can see that indeed, differences are shown between zPrinicpal.nsf and zOtherApp.nsf. The LotusScript in zTemplate.ntf is the same as that in zOtherApp.nsf.

The form where the extra field was added into zPrincipal.nsf shows the same ID changes throughout the form. These changes are not present in either zOtherApp.nsf and zTemplate.ntf. But the expected differences in the header information result in all three being flagged as having differences (see fig. 17).

Fig. 17 The three-way comparison still shows the changed field IDs due to the field addition. But also shows the expected differences in properties such as the replica ID.

In the views, we can see that zOtherApp.nsf contains the view Another Author.view. This is missing from the other two (see fig. 18).

Fig. 18 The view Another Author.view is shown as being present in zOtherApp.nsf, but not present in the other two.

And finally, the last of the known differences. The added view New Review Status.view. This is present in the common ancestor zTemplate.ntf, but not at all in either zPrincipal.nsf or zOtherApp.nsf. The content comparison for this case doesn’t display anything. Perhaps this is something to be straightened out in future versions of the Domino Designer.

An efficient tool to spot differences

Overall, the comparison feature can bring to light differences in designs between replicas, as well as databases inheriting from templates. This can be a great starting point when your databases have more complex inheritance, or when you have multiple hands on the databases and templates in question. You’ll be able to find out which databases are using the most up-to-date code, and which are lacking and in need of a design refresh. It’s a powerful tool that is free and readily available in the Designer client. And if you haven’t ever used it before you’ll be able to start making sense of the differences and working towards a more consistent environment.

To copy or not to copy?

One secondary feature that is available while doing a comparison is the ability to copy/paste code from one side where additional code is found to the side that lacks it. Situated just above the content comparison pane are buttons that give you the option to copy all non-conflicting changes from one side to the other, or a more granular approach that lets you select specific changes to copy (see fig. 19).

Fig. 19 The comparison also offers copy/paste options for changes.

As mentioned in a previous blog post about the Domino Designer’s search functionality, I have never been one to make use of the search and replace feature. And I have the same reservations about these options here. Although there is a minimum of intelligence behind the mechanics of finding differences, I just haven’t ever wanted to place a wholesale trust in this type of operation. Do you use these copy options? If so, how have they worked out for you? Feel free to discuss in the comments below.

Last article of the serie – Eliminate false-positives in your database comparisons: What every Domino pro should know about the Designer client