August 6th, 2005
Using Version Numbers to Manage Database Designs
Notes templates are marvelously powerful.
But that power comes at a cost - templates and database designs must be
managed effectively. For any given inhouse developed database, how you
do know which version of the design is in production? While this is a problem
on servers, it can be a much bigger problem with remote users who replicate
databases down to their laptops. When they call the helpdesk, how does
the support person know which version of the database is being used? Multiply
this by the thousands of databases used at a typical corporate site, mix
in a few replication problems and you have a nightmare.
One solution is to use a configuration document to track the database version.
This document is updated with the new database version number whenever
a new design is pushed into production. With a one-to-one relationship
between development and production databases, it is difficult to keep everything
in sync. Whith multiple databases from one template it becomes almost impossible.
Some people try to track database versions by looking at the date and time
on design elements. This is really clumsy and only works on the server;
it fails on a remote laptop if the user doesn't have the designer
client available.
How much better it would be to have the design stamped automatically with
the template version. To do this you need a design element (as opposed
to a document like the configuration document above). The last design step
before pushing a new version of the code is to update the version number
of the design element. While a page or form could be used, typically a
shared field is used because it is more flexible. Since a shared field
is a design element, it flows into the production database during a design
refresh, like any other design element. This unambiguously identifies the
design version being used in production and very neatly solves the problem.
Implementation
In R5 you would use a computed shared field, and set the value of the field the release version, e.g. DocMaster R4.0.40. Release 6.5 moved this idea into core Notes functionality, and you can see an example of it in the mail file. Look at the mail file's Database properties... Design properties (middle tab) and you will see a version number something like 6.5.4 (03/09/2005). This information comes from a shared field called $TemplateBuild. The example below is from a database called DocMaster. Notice how this production database is based on the master template DocMaster R4 PRD, which is in turn based on the development template DocMaster R4 DEV
If you look at the properties of $TemplateBuild shared field in designer (see below), you will see 3 items on the design element document. (Note: Just like normal documents have items, so design elements have items.) You can access the template version number with a new @function, @TemplateVersion. (Unfortunately there is a bug: @TemplateVersion doesn't work in computed text. You must use a computed for display field).
You can use the new R6 NotesNoteCollection classes to manipulate these item values. I have written a small database Set Template Version (see download link below) that allows you to update these 3 items. Launch the database and follow the instructions in the diagram below. If the $TemplateBuild shared field is not present, it is added to your database. (Note: if you use Teamstudio CIAO you may get prompted to check out the design element. Select yes, and then use CIAO to check it back in again. This should be the last step before making the new version of the database.) Be aware that the master template does not show the version information on the design tab of the database properties (because it is not inheriting a design). However, any database that inherits from that template will show the version information on the design tab.
If you launch Set Template Version from the designer client, you can see templates as well as databases when you click the Click to start button. To launch form designer, create a new button on the toolbar, and give the button the formula
@Command([FileOpenDatabase]; "Dev\\Projects\\TemplateVersion\\TemplateVersion.nsf")
Replace the path above with the path to the database on your system. Thanks to Chad Schelfhout for this suggestion, and for pointing out an error which has since been fixed.
Click link to download file
TemplateVersion.zip