#16 Considerations when renaming properties

[Jade Support]

Summary
This bulletin was motivated by a number of Parsys contacts that have been received by Support over the years reporting the following unexpected effects after renaming a class property:
- Lost property values
- Collections losing their member objects
- Dictionary members not being stored at their correct key values

The purpose of this bulletin is to:
- Outline the circumstances under which these effects occur, so that the developer may adopt a procedure for avoiding these effects.
- Outline corrective measures if the effect is observed.

Background
When a property name is changed in the IDE, and a schema extract is then deployed, JADE has no way of knowing upon schema load that the apparently new (renamed) property is the same property as an existing property. By default, the schema load will consequently treat the renamed property as a delete of an existing property (since it is not present in the schema extract) and an addition of a new property. A deployment performed in this way will result in lost information.

One way of maintaining the renamed property value is to retain the existing property and introduce a new property. The value of the new property can then be copied from the existing property by running a post deploy script. Finally the original property is removed in a subsequent schema deploy.

A second way of deploying a rename of a property is to use the Rename Property command in a command file. It is important to realise however, that this mechanism in itself is not sufficient to guarantee that under all circumstances the property value will be maintained (hence the existence of contacts motivating this bulletin). This will be discussed in detail in the following section.

Renaming a Property by command file may have unexpected results
When a mutating reorg is performed, property values are retained by matching the current and latest versioned properties of each class by name and copying data from current to latest versions for matches identified.

When a property is renamed and the owning class (or one of its superclasses or subclasses) is marked for reorg, reorg is unable to retain the property value because a name match is not made between the current and latest versions of the property. When the reorg is performed all instances will lose the value of this renamed property, or in the case of a renamed collection reference, that collection will lose its members.

The class may be in a versioned-for-reorg state when the Rename Property command is executed because another command in the command file has been executed that marked the class for reorg (for example a command that removes another property on that class). Alternatively, the class may be in a versioned-for-reorg state when the rename is executed because a prior schema load was performed that versioned the class for reorg but the reorg was not performed (suppressReorg was set).

Avoiding the issue
The issue can be avoided by ensuring that when a rename command is executed, no schemas are versioned.

Running the command file prior to loading schemas will go part way to ensuring that no schemas are versioned. Alternatively you could ensure that any outstanding reorg is performed prior to running the command file to complete changes made in any schemas loaded prior.

It is also recommended that a separate rename command file be used to avoid the possibility of another command versioning the class owning the property to be renamed.

Alternatively, specify loadStyle=currentSchemaVersion to ensure that the property rename will not cause versioning.

Test deploys performed before the final deploy to production should be identical in procedure to the production deploy. This ensures the opportunity to perform appropriate testing.

Detecting and repairing the issue
It is important to detect the issue during development by testing the deploy process thoroughly because once the deploy to production has been made and data is lost in production, determining lost property values can be difficult and in some cases not possible.

The issue may be detected using various forms of testing (manually checking property values for example, or by unexpected application exceptions being raised during application testing).

In the case of a renamed collection reference resulting in lost membership, if the collection has an inverse, then a Logical Certifier analysis will report the missing members.

Lost property values may be retrieved by restoring a backup and rolling forward to a point in time prior to the property name change. This means of course that subsequent transactions will be lost- another reason for discovering the issue during testing and before production deploy.

In some cases it may be necessary to reset lost property values by script after extracting old values from a restored backup, or by deriving those values from another source.

If a Logical Certifier analysis detects members absent from an inversed collection, running the Logical Certifier repair will add the absent members into the collection.

Special cases involving a property rename in the IDE
The same general issue of actioning a rename of a property in combination with another change necessitating a reorg of that class applies in development also.

When a property is renamed, and then in the same update another property attribute that necessitates a reorg is made (E.g. changing the size of the property), the property value for all instances will be lost when the reorg is performed.

When a property that has an RPS mapping is renamed in the IDE, the property value for all instances is lost.