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.
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).
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.
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).
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.
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).
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).
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).
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.
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).
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.
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).
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).
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).
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).
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).
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.
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).
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).
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).
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.