Domino offers a lot out-of-the-box. It’s immediately apparent when looking at the Document Properties that the last modified time and last modifier are stored. What’s less obvious is that the last modified time of an individual field is also stored. That can be extremely useful when trying to work out who or how that field was modified.

For each Notes Item, a number of pieces of information is stored – field name, data type, data length, duplicate item ID and field flags (e.g. SUMMARY, NAMES etc). But the most useful for troubleshooting the state of a document at a particular moment in time is Seq Num.

Seq Num

Each time a document is saved (back-end or front-end), the Seq Num field is incremented. You can see it on $UpdatedBy and $Revisions. (Note: $Revisions field does not exist until a document has been saved twice – because it’s not been revised!)

So the Seq Num value for a specific Notes Item corresponds to the nth time the document was saved. So in the screenshot above, Country was last updated on the second save of the document.  By cross-referencing that with the $Revisions value, the corresponding date and time can be identified. (Bear in mind that the field usually gets capped, so work backwards, not forgetting to remember that the most recent save is not included in $Revisions field.)

What I didn’t realise until Nathan T. Freeman pointed out to me recently was there is also a LotusScript / Java method of NotesItem / Item class to give that information – lastModified / getLastModified(). (One of the benefits of working on an API extending Domino is that when you suggest adding something that’s already there, someone tells you!)

This tells you the when, but identifying the who is a little more complex. The $UpdatedBy field is not updated for every save. If the person saving the document is the same as the last editor, the field is not updated. But if Person A saves the document, then Person B, then Person A again, the $UpdatedBy will have three entries “Person A”, “Person B”, “Person A”.

This points to one big caveat when creating code that updates or synchronises documents – only update fields if there’s a change. Front-end saves from Notes Client or via DominoDocument datasources only update modified fields. So does the OpenNTF Domino API SyncHelper has strategies to do this. But the LotusScript / Java stampAll() method does not. And if you’re creating a wrapper, you might not. Indeed I have seen backend code that updates all fields regardless of changes and, the very basic introduction to Java in the “Introduction to XPages” training course I run deliberately does that – so my “Java for XPages” course can show what you should do! However, by so doing, such code removes a big weapon in the armoury of a Domino developer, to help identify the state of a document at a point in time and what process / who made the change.

2 thoughts on “Notes Items, Seq Num, and Domino Update Troubleshooting”

  1. “…only update fields if there’s a change”

    The ODA Graph decorator handles this for you. It’s quite rigorous in only changing an item when the data is actually different.

    (And thanks for the hat tip.)

    1. The discoverability of all these things and documentation in general remain a utter mystery to me. Apart from the implementers/developers or those who do reverse engineering is there any available documentation that can make logical sense of all this?

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.