Diagnosing Field Changes
This blog post isn’t specific to XPages and may be something many developers are aware of. But it took me many years of Notes development to learn this little bit of information that can quickly help troubleshoot data issues with Notes documents. It’s still relevant in the world of XPages and well worth taking into consideration if you’re manipulating field values via managed beans. And it may be something XPages developers who have come from a non-Domino background may not be aware of. It’s something that can be very useful for database support, as I was reminded last week.
Notes documents comprise fields or Notes Items. In the traditional Notes Client development world, the Notes Items stored will comprise of all Editable, Computed or Computed When Composed fields on the Form design element used to edit the Notes Document. In addition, an agent can be used to modify, add or remove Notes Items from the Notes Document.
There are two special Notes Items added to the document to track edits: $Revisions captures each date and time the Notes Document is saved, and $UpdatedBy captures the editors. The number of entries in these two Notes Items can be limited in the Database Properties, on the Advanced tab, as below. A value of 0 means the Notes Items are only limited by the inherent size limit for Notes Items in Domino.
This can be useful for confirming a Notes Document has been updated, but what about confirming whether a field has been updated. For each Notes Item a number of pieces of data are captured, which can be seen by viewing the Document Properties. This is done in a traditional Notes Client view either by right-clicking a Notes Document and selecting “Document Properties” or highlighting the document and either pressing Alt + Enter or going to File -> Properties. A dialog box like this will be shown:
- Field Name: the name given to the Notes Item by the developer. This can help diagnose typos in your code and is a good reason for notes using field names like “View”, i.e. field names which will return lots of results if you do a search in the database design for them. You want something that, if you need to search for it, will quickly give you all references to that field across your database.
- Data Type: the relevant data type defined by the code. This can also help track coding issues where an agent has set the field to an incorrect data type or changed the data type. Domino allows different data types, but this will affect search results.
- Data Length: the size of the Notes Item.
- Seq Num: I’ll come back to this.
- Dup Item: If you have more than one Notes Item with the same name, this will be incremented. This is most commonly encountered when developers use appendItemValue(). Views, getFirstItem and other functionality will only retrieve the first field, so this is why replaceItemValue() is the preferred method to use, unless you specifically want to create duplicate Notes Items.
- Field Flags: this needs to include “SUMMARY” if the Notes Item should be included in a Notes View Column. If it’s not, even if the Notes Document shows in the view, the Notes Item value will not. This is also the element that will confirm / deny if a field is used for Reader or Author access and if it’s a Names field.
But the key element for tracking when / if a Notes Item was updated is Seq Num. When a Notes Document is first saved, the Seq Num for each Notes Item on it will be “1″. If the Notes Document is edited and saved again, $UpdatedBy and $Revisions will have the Seq Num value of “2″. Also, any field modified during the save process will also have Seq Num set to “2″. So by looking at the Document Properties and cross-referencing a Notes Item’s Seq Num against the $Revisions Seq Num, you can quickly see whether the Notes Item has been modified. By tracking back through $Revisions against the Seq Num count, you can identify when it was changed. If the Notes Document is edited twice consecutively by the same user, the $UpdatedBy is not captured, but it may help track down editors.
So why is this important? There is no out-of-the-box document locking on the web although it is possible to code something to achieve this. If not, there are a number of options for concurrency handling that Domino provides, either on the Form design element (relevant if you’re editing in the Notes Client or traditional web), in the dominoDocument datasource (the concurrencyMode property) or in the Notes Document save method:
- The developer can create a Replication/Save Conflict, creating a response document to allow someone to manually compare the Notes Items and fix up by amending the main document and subsequently deleting the conflict. Seq Num can be useful here to quickly identify which Notes Items were changed during the last save.
- The developer can choose to just fail the process or throw an exception.
- The developer can choose to force the subsequent save. This may cause Notes Item changes to revert back. This most commonly triggers support if a process amends the back-end Notes Document while someone has the same document open in edit mode. If they then save the document without closing and re-opening, Notes Item values may be reverted, but Seq Num will be incremented. If the back-end process updates Notes Item A that has Seq Num set to “5″ and Notes Item B has a Seq Num of “6″, B must have been updated after A. This kind of diagnostics can help confirm that the back-end process did run, but that some other process has updated the Notes Document subsequently.
Seq Num is very useful for support purposes, but highlights why it’s important to not update all Notes Items during every save.