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.

Mick Moignard has been working and traveling with Lotus Notes since Release 2.0 in 1991. Mick is a DominoPower Senior Technical Editor and a Principal CLP with Unipart Expert Practices, a Lotus Advanced Partner in the UK. If you want to discuss anything to do with this article, or indeed anything else to do with Notes and Domino, contact Mick at Mick_Moignard@unipart.co.uk. Unipart Expert Practices will also happily discuss any opportunities you may have with any Notes and Domino application development or infrastructure projects you need help with. Unipart Expert Practices can be found at http://www.unipartep.com.