Simple LotusScript NotesDocumentCollection Iteration

02/16/2010 12:21 PM by Chris Toohey

Sometimes a StampAll just doesn't give you enough flexibility or control when dealing with a NotesDocumentCollection. Sometimes you need to some logic behind each NotesDocument update. For those situations, we tend to use a technique called iteration... which sounds really awesome and consultant-like, but basically boils down to creating a looping function within your LotusScript.

There are several methods complete with built-in functions in LotusScript that allow you to iterate through NotesDocumentCollections, NotesViewEntryCollections, and such... so I'll start off by defining a simple use case, and then showing you how not to iterate through a given NotesDocumentCollection, and then ultimately showing you a solid approach to NotesDocumentCollection iteration!

Use Case

A scheduled Agent for a simple Project Management application will evaluate each new NotesDocument since last run and -- since we're going for simple here -- update the manager NotesItem with the value stored in the submitter's Person Document in the Domino Directory. Since this is an ideal world, every Person Document manager is both defined and contains the common name matching the manager's own Person Document.

Author's Note: Yeah, this would never happen, but this is a use case for iteration, not chasing down the manager NotesItem values... so go with me on this one.

How not to...

The below LotusScript uses the getNthDocument function to loop through a supplied NotesDocumentCollection and perform whatever NotesDocument application logic is needed (in this case, a Domino Directory lookup and NotesDocument update & save).

Function setManager(col As NotesDocumentCollection)
	
	Dim s As 
New NotesSession
	Dim counter As Integer
	Dim doc As NotesDocument
	Dim nab As New NotesDatabase(s.CurrentDatabase.Server, "names.nsf")
	Dim nabview As NotesView
	Dim nabcol As NotesDocumentCollection
	Dim nabdoc As NotesDocument
	
	Set nabview = nab.GetView("people")
	counter = 0
	
	Set doc = col.GetFirstDocument
	Do Until(counter > col.Count)
	 
	 Set doc = col.GetNthDocument(counter)
	 Set nabcol = nabview.GetAllDocumentsByKey(Join(doc.GetItemValue("submitter"), ""),True)
	 Set nabdoc = nabcol.GetFirstDocument
	 Call doc.ReplaceItemValue("manager", nabdoc.GetItemValue("manager"))
	 Call doc.Save(True, False, True)
	 
	 counter = counter + 1
 
	Loop
	
End Function

If you have 5 NotesDocuments, this isn't that bad of an approach. I still wouldn't use it though and the reason is pretty simple: it scales horribly, and we're coding for the species here people!

The reason it scales so poorly is simply that the use results in the code losing it's place through the iteration. As a result, it starts from the first NotesDocument in the NotesDocumentCollection and steps through... the whole time asking it it's the Nth NotesDocument in the NotesDocumentCollection.

How To

Function setManager(col As NotesDocumentCollection)
	
	Dim s As 
New NotesSession
	Dim doc As NotesDocument
	Dim nab As New NotesDatabase(s.CurrentDatabase.Server, "names.nsf")
	Dim nabview As NotesView
	Dim nabcol As NotesDocumentCollection
	Dim nabdoc As NotesDocument
	
	Set nabview = nab.GetView("people")
	
	Set doc = col.GetFirstDocument
	Do Until(doc Is Nothing)
	 
	 Set nabcol = nabview.GetAllDocumentsByKey(Join(doc.GetItemValue("submitter"), ""),True)
	 Set nabdoc = nabcol.GetFirstDocument
	 Call doc.ReplaceItemValue("manager", nabdoc.GetItemValue("manager"))
	 Call doc.Save(True, False, True)
	 
	 Set doc = col.GetNextDocument(doc)
	 
	Loop
	
End Function

Not a big change here, but using the getNextDocument steps through the NotesDocumentCollection and scales much better than the dreaded getNthDocument.

Conclusion

So what have we learned?

1. There's no environment in the world where the above scenario would actually exist.
2. I suck at creating Use Cases...
3. getNthDocument is evil. If you come across it in your production code, you might as well just unplug the Domino server.
4. getNextDocument-based iterations scale!

And, most importantly, NotesDocumentCollection iteration is an extremely powerful technique that can allow you to process large numbers of NotesDocuments with applied logic at the individual NotesDocument-level.