XPages Page Versions 

Each XPage has a version number that is compared to the server version when attempting to run the XPage. An XPage that was created in Domino Designer version 8.5.1 and that uses features or options that were added or redefined in 8.5.1 will not run on an 8.5 server.

The error message that appears on the Domino 8.5 server is like so:


If you were to use an 8.5.2 feature on a Domino 8.5.1 server, the error message would be like:


The error message on the 8.5 server is slightly odd. It only prints the first 2 parts of the version numbers (8.5 instead of 8.5.1). Also the 8.5 server has XPage compatibility version 3.0; it was not named 8.5.0.

The server version numbers will be changed in every release. The server versions so far have been 3.0 (Domino 8.5) and 8.5.1 (Domino 8.5.1). The term "server version" is slightly misnamed - it is actual the version of the XPages runtime. So if you have an application designed to run as XPages in the Client, and it uses an 8.5.2 feature, when you try to use it in an 8.5.1 install of the Notes Client it will complain that the "server version" is 8.5.1, when it means that the Notes Client install is 8.5.1.

The page version will depend on both the version of Domino Designer where the application was last opened, and on the contents of the XPage. The Designer install knows which controls and properties were added or redefined in this Domino Designer version, and in each of the previous versions. If your XPage only uses controls and properties that were available in 8.5, and they did not have any incompatible changes in 8.5.1, then the page version will be 3.0, even though the Domino Designer installed is 8.5.1. Such an XPage would continue to run successfully on an 8.5 server. If an XPage uses new features that were introduced in 8.5.1, then it definitely will not run on an 8.5 server, failing with the error message above. It is possible that some later release of Designer might mark all XPages with a recent page version, even where the XPage did not use new features. If that were to occur then that version of Designer would only work with servers that were of the same version or more recent than the Designer install. (If it ever seems necessary to make such a change, customer inconvenience would be a strong consideration in the decision-making.) For now, in Designer 8.5.1, there is a short list of XPage contents that will change the page version to 8.5.1, and hence prevent running such XPages on an 8.5 server.

While Domino has always and still supports backwards compatibility, forward compatibility (newer designs running on older servers) has never been guaranteed. The recommended upgrade path prescribes upgrading servers first, then clients, then the Designer client. Following this pattern will guarantee the best application results. Running newer designs on older servers is not supported or predictable.

If you encounter one of the version error messages, then the easiest solution is to revert to using an older Domino Designer install, with a version matching or lower than all of your server and client installs.

If you are an advanced user who did not intend to use any new features, and who doesn't have an old Domino Designer install to hand, there are some steps to track down which new or redefined tag or property has increased the page version.

To determine the tag or property responsible for the page version

Select the application in Designer, in the menus Search, Search, File Search, "Containing text" (with the double-quotes): "8.5.1"
The search results will be some .java files that correspond to XPages or Custom Controls.
The comment on the selected line will tell you which XPage tag or property is new, like so:

The first example refers to the xp:view tag. If you select that tag in the source tab of the XPages editor, you will see that it is the XPage root control. In the All Properties tab, when you hover over the readonly property, you will see that the property was newly added in 8.5.1.

Similarly, the xp:platformEvent tag refers to the new Platform Event Control, added in 8.5.1 to publish Composite Application events in the Notes Client.
Use of any such new property or tag will change the page version.
(The issue MKEE7X3N8Z has been logged, asking for an easier way to determine the page version.)


Unusual version 8.5.1 tags and properties
Some of the tags or properties that are marked as 8.5.1 are not just regular new features.



xp:eventHandler script
That property is new to 8.5.1, and it enables configuring client simple actions that run in the browser.
However it's worth noting that Designer will sometimes automatically change to using that property.
If you have Client JavaScript associated with an event in 8.5, the XPage source is like this:

If you open that in 8.5.1 Designer, and edit the script, it will change to:

Those are functionally identical, but the second one will not run on an 8.5 server.
If you wish to continue using that application on 8.5 servers, you will have to manually change
it back to the old format, and ensure you do not edit the script in the Events view.
That Designer change was related to the issue MKEE7STDLN.



xp:navigationRule
The Navigation Rule tag was present in 8.5, but it has changed substantially in 8.5.1,
so that an 8.5.1 Navigation Rule will not run on an 8.5 server. The implementation was changed
so that the target XPage can be computed, related to the issue PHAN7U5K8C.
The page version will change to 8.5.1 when any Navigation Rule is recompiled in 8.5.1,
even though you have not changed the XPage.
There is an advanced user workaround, but it is recommended to instead revert back to using an 8.5 Designer install.

Advanced user workaround for PHAN7U5K8C
You can initialize the navigation rule in JavaScript code instead of in the compiled Java code,
so that it will work on both an 8.5 and an 8.5.1 server.
If you open the .java file corresponding to the XPage, you'll see the code that creates
and initializes the navigation rule. e.g. for this .xsp source:

In 8.5.1 you'll see something like:

In 8.5 you'll see something like:

(that is, it doesn't call setComponent).
Copy that code into the XPage Events view, the afterPageLoad event,
convert the first line to JavaScript, conditionally call the setComponent method,
and use "view" instead of "result", like so:

Then remove the navigation rules from the XPage source, by deleting these lines:

The XPage will no longer be restricted to 8.5.1.



If you wish to provide feedback, or if you encounter any problems, please discuss them in the IBM Lotus Notes/Domino 8.5 Forum,
or report them through the IBM Lotus Domino Support system. Comments on this article are not monitored.