ShowTable of Contents
Previous |
Next Upgrading applications
When it comes time to upgrade your application, there are things you, as a developer, can do to make the upgrade process easier. Here are some best practices for upgrading your Domino applications.
Using templates
An NSF file generally contains both the data of the application and the design used to manage that data. However, to avoid problems in managing the maintenance of your application, it's better if you manage the data and the design in separate files, so that you can edit the design, and fully test the changes, without affecting the application that's in actual use. In addition, it is often the case that a design may be duplicated into multiple NSF files which contain different data. One obvious example is the user mail file, where each user has a copy of the mail file design, but it has their own data in it.
Templates provide a way to edit the design centrally and away from the application data. Once you are satisfied your changes are correct, you can apply the updated design to application databases, either directly or by placing an updated copy of the template on your servers, where the nightly DESIGN task will update applications.
Domino templates generally have a NTF file extension, but the true thing that makes a Domino application a template is the “Is A Template” setting found on the design tab of the application properties:
Any application that has the same value in the “Inherit from Template” setting in application properties inherits design elements from this template whenever the server's Design task runs. By default, the Design task runs at 1:00 AM daily, however, this can be changed (or even disabled) by a Domino Administrator.
Individual design element inheritance
Individual design elements can be marked to inherit their design from a specific template, or be set to not inherit from any template. These are done on the properties of the individual design element.
You can set this option on design elements an an application. As a general rule, this is only a good idea when the design contains elements that are supposed to be customized to the occurrence of the application -- they're supposed to be different from the template. With the exception of personal views and folders (such as in mail files), or customized graphics or stylesheets that are different in each instantiation of the design, this is rare. In nearly all cases, it's best to manage the design of the application by editing the template, and making the application design identical to the template design. In cases where you have two designs that share some design elements, the template for one application can inherit its design from another template, with certain design elements exempted by checking their "Prohibit design refresh..." checkbox. Or if two templates have just a few elements in common, one can inherit only specific elements by adding the source template name in the "Inherit from..." field.
The danger of working in this way is that if part of your design changes without your awareness, because someone edited the template from which you inherit, it can break your application. Design elements are often interrelated; for instance, a form might contain a field formula that uses @DbLookup to find a key in a view, and read a value from a certain column. If someone changes the view, you may now be reading from the wrong column. You would definitely, at least, want to not accept updates automatically, but first test the changes to make sure there's no problem introduced. You may find it better to simply copy the design you want to customize to a new template with a different name, with no inheritance, and use other means to track reusable design elements.
Use special caution in allowing automatic inheritance of code-based design elements. For any code, there's a danger that someone will change the design in a way that will make it fail when called by existing code -- for instance, by inserting an argument in the middle of a function list, so that existing calls to that function are no longer correct. LotusScript code has the additional limitation that it is compiled in the context of existing code that it calls in the same application. If a script library is modified without recompiling the other LotusScript code that calls the library, the library can fail to load even if the profiles of the functions it makes calls to have not changed. There's no search that will identify all the places where a particular library is used across all applications. Therefore, it's generally better to allow the maintainers of different applications to determine when and if they will incorporate a new version of a common library into their designs. Allowing these to inherit automatically across the organization will almost certainly cause applications to fail in the field.
Generally speaking, it's a bad idea to control inheritance of individual design elements in an NSF file, since that's means you're assembling the final design for the first time in your production environment, without ever having tested it. If anything is to inherit individual design elements, it should be a template. Use the template to create test NSFs to try out upcoming changes before you release them to users.
Putting changes into production
When you are changing the production design of your application, there are general rules to follow to make sure the deployment works smoothly.
Back up existing design
First, you should make a back up copy of the current production template. You can revert back to that design in the case of a failure or unforeseen issue.
Document data migration procedures
If data needs to be migrated because of the new design (adding a new field that your new design requires, for example), then you should include data migration agents to update the data, and document the steps required to run the agents. You should also work with your Domino Administrator to make sure that the data migration happens soon after the design is upgraded in order to decrease the potential for end user errors from using the new design with the old data.
If possible, design your new version to work acceptably with the old style data as well as the new, so that no migration process is needed. If you cannot find a way to do this, you definitely don't want to allow the Design task to update that design automatically.
Document data reversion procedures
For every data migration agent you have, you should also have a data reversion agent that will “undo” the migration in the case of a failure. If you have to revert back to the original design, you need a way to revert back to the original data. The agents that need to be run in the case of a reversion have to be documented.
Verification of success
After upgrading the application and migrating the data, you should have one or more users verify the new functionality of the application in production. Users should have already validated that the functionality does what they asked in a development environment, however, this is making sure the design elements were properly refreshed and the data properly migrated in production.
Deployment steps
You should check with your Domino Administrator for the exact steps your company uses to deploy changes to Domino applications. If the Design task has been disabled on the server, the design of the production application must be manually refreshed after deploying an updated template. If templates are not allowed to be stored on the production servers, someone with the proper authority and access have to manually refresh the design of the production application from a local template. Every company may have slightly different procedures for upgrading applications, but those procedures should be documented by the Domino Administration team.
Parent topic:
2.0 Application development lifecycle