Monday, November 1, 2004

The further case of Last Modified dates

PROGRAMMING POWER

By Mick Moignard

Back in the March issue of DominoPower Magazine I wrote about document lastmodified dates -- see http://www.dominopower.com/issues/issue200403/00001250001.html. Maybe someone at Lotus reads DominoPower, because in the latest ND7 beta, beta2 at the time of this writing, lo and behold, NotesDatabase.getModifiedDocuments has been included.

NotesDatabase.getModifiedDocuments

What NotesDatabase.getModifiedDocuments does is return a collection of documents that have been modified since a given date and time. While it defaults to returning a collection of data documents, you can set flags to also return non-data documents, meaning you can also use it to track changes to design elements if you need to.

The returned collection is stamped with an "Until" time -- NotesDocumentCollection.UntilTime. This enables you to design an agent that steps forward on successive runs, only dealing with documents it has previously seen.

Just like NotesDatabase.Search, NotesDatabase.getModifiedDocuments also seems to filter on the values stored as NotesDocument.LastModified time, which as we saw back in March, is just one of the many document modification times that Notes keeps. This actually solves the problem that I described in March rather well, better than the solution we devised then with Notes 6.5.

To recap, what we wanted to do was design an agent that worked on documents that had changed since it last ran. How we solved it then was to use the cut-off time in a Db.Search. We then recorded the time that the agent started, which basically was the time we actually did the search.

On the next run, we retrieved that stored date, and used that as the cut-off time on the next search. It worked, but was a bit cumbersome. It also relied on the captured agent start date/time and the search actually happening at the same instant, which they might not.

This whole process will be simplified when we move forward to ND7. Instead of making the collection with a search, we use the new NotesDatabase.getModifiedDocuments, which will give us the same collection as we had before. So no change there.

But we can also capture the UntilTime from the collection (NotesDocumentCollection.UntilTime) and store that, rather than capturing the agent start time. So on the next run, the next time we make a getModifiedDocuments collection, we replay back into the call the stored UntilTime, and know that we will have a seamless move forward to the next set of modified documents, if any. Indeed, if you do a getModifiedDocuments and the collection is empty, it still gives a new UntilTime.

Cool. Thanks, Lotus.