ShowTable of Contents
Introduction
The most time-consuming part of an upgrade of your Notes environment to a more recent version, is not the actual upgrade, which is fairly simple, but the testing of your Notes and Domino applications to make sure they still function correctly in the new version.
The developers at Lotus make every effort to assure that version changes don't "break" existing applications. However, some issues do creep in by mistake, or are unavoidable if we are to continue to add features to our programming languages.
Server Upgrade
The install kit for 8.5.
x should not have a problem upgrading a Domino server of any version, without affecting your existing configuration.
Client Upgrade
The install kit for 8.5.
x should not have a problem upgrading a Lotus Notes client of any version, without affecting your existing configuration.
Known Application Issues
This section lists known issues that may "break" your application if you upgrade to version 8.5.1 or later from earlier versions. Each section discusses how to scan for applications that may have this problem, and how to fix or work around the failure.
If you know of issues that are not listed here, please edit this document.
NotesSQL Version
If you use NotesSQL you'll need to
upgrade to NotesSQL 8.
Since this would only be used by applications that access Notes from outside, we have no recommendations on how to scan your Notes applications for this, but if NotesSQL is installed, consider upgrading.
Postopen Display Issue (Notes client)
If your form's Postopen event uses UI functions that open modal windows, such as Messagebox or Dialogbox in LotusScript, the user will see these dialogs before the form is visible beneath the dialogs. In some earlier Notes versions, the form would display first.
In reality, the form is open, it just hasn't been "painted" yet. All the same UI functions, @Commands, etc, should still work; the only difference is in what the user sees behind a dialog.
Use the Database Synopsis function to generate descriptions of all forms and subforms (or use Tools > DXL Utilities > Viewer), and search for the words Messagebox, Msgbox, Prompt, Dialogbox, alert, inputbox... (Am I missing any?).
If the call occurs in a script library that's called from the form or subform, it will be harder to find, but you might search for the string Use " (doublequote) to find which script libraries are used in the forms.
Or, you could wait and see whether anyone has a problem.
A workaround if you require the form to display first, is to remove the code from Postopen, and instead put it into the action you use to compose the form. So after the call to NotesUIWorkspace.Compose, for instance, you would put your Dialogbox call or whatever. Alternatively, if the dialog is used only when the form is in edit mode, you could insert code into the Onfocus event of the first field (be sure to set a static flag to remember that you've already displayed the dialog, so that you don't redisplay it whenever the user returns to the field).
Embedded View Focus Change
Suppose you have a form with an embedded view which is linked to an embedded editor. In version 6.5 and 7.x the first document gets focus on open (and shows in the embedded editor), while in 8.0 it doesn't, and you have to click on the document in the embedded view.
Whether this is a problem depends on your users' expectations.
Finding all forms with embedded editors would be possible with DXL; there's no direct DXL representation of this element, but you could search for relevant elements. However, there's nothing you can do about it; that's just how the control works now. So searching may be more trouble than it's worth.
navigator.appName in common Javascript
navigator.appName running in the client doesn't return "Lotus Notes" as it used to be prior to v 7.x but "IBM Lotus Notes". If you use Common Javascript and you rely on appName to execute something in the client different than in the browser, you have to consider this.
Application Upgrade Procedure
We advise testing your applications in the new version of Notes. If the application is already working, we do not advise recompiling LotusScript code, as this in theory can cause problems that did not previously exist.
As an example, in version 6.0 a new built-in function, Replace, was added. Since Replace is now a reserved name, you can no longer define a variable or function named Replace. However, code that was compiled in versions earlier than 6.0, can still use this name. If you attempt to recompile the code, the recompile will fail, but the old object code will keep working.
There haven't been changes since 6.0 that are likely to cause this sort of conflict. A few built-in classes were added, but their names are not such as to likely cause conflicts.
Best practices to prevent future problems
- In LotusScript, always, always use Option Declare. This causes some errors (which might not have been errors in previous versions) to be noticed at compile time rather than resulting in non-working code. We strongly recommend you enable the option in the Programming Pane properties, to always insert this statement automatically.
- In LotusScript, use NotesDocument.GetItemValue and ReplaceItemValue to work with item values, rather than the "dot notation" doc.fieldname. This prevents problems in case a method or property with the same name as your field, is later added to the NotesDocument class.
An example of how failing to follow these guidelines can cause a problem, is the addition of the Lock method in version 6.0. Previous to this, you could refer to a field named Lock by writing:
This is no longer valid syntax. But suppose you already have code that contains this statement; will it continue to work? That depends. If doc is declared as type NotesDocument, then the Notes 5.0 LotusScript compiler could tell that this is intended to be a field reference, and compile it as such. So even in later versions, the code would continue to work, even though if you try to recompile you will get an error.
But if doc was not declared, the compiler doesn't know it was intended to be a NotesDocument, so it has to defer the binding until runtime. But Notes 5.0 and Notes 6.0 would resolve this call differently, since 6.0 has the Lock method. So the line would work in 5.0, but generate an error in 6.0 (since this is not a legal call to the Lock method -- and even if it were, that's not the developer's intention). The code fails because the variable was not declared. Use of Option Declare would have prevented this problem by reminding the developer to declare the variable.
Resources
The guidelines for a successful Domino upgrade change slightly from release to release based on features, but the basics remain the same.
This Redbook provides a good overview of the process, but the specifics are from the 7.0 version. http://www.redbooks.ibm.com/abstracts/REDP4120.html?Open