This script shows you how to flag a parent document, as well as each of its associated child or response documents, for deletion. The child documents do not necessarily have to be related by a unique ID (UNID) or parent ID, but they must be related by another ID that all the documents might share, such as a project name or project category. However, you can modify and adopt this script easily if you need to get a parent and all its children by UNID and perform some type of operation on each.
Getting started, this agent is called from a webquerysave event based on a field flag that is invoked by a delete button on a Web parent document. It collects the parent and looks for any other children or response documents that match the parent. Continuing on, the agent puts the collected documents in a document collection, changes the form name to DeleteThisDoc, and saves the document. Another agent, DeleteDocsMarkedForDeletion , later runs on schedule to remove all the flagged documents for deletion. Sometimes it is good practice to use a safety net for when users actually delete something they did not intend to delete. As a result of this script, an administrator can easily go to the AllDeletionDocs view and change the form name back to what it was; the document then is restored to its original state. This could be done via an Admin agent launched from a button in the AllDeletionDocs view as well. The DeleteDocsMarkedForDeletion agent also uses a document collection routine to step through each document in the view and delete it permanently from the database.
See Listing 15.1 for a complete explanation of the option declarations shown in Listing 15.13, how they are used, and what they mean.
Listing 15.13 Option Preferences
1. Option Public 2. Option Explicit
Listing 15.14 shows the globally declared variables that is used in this script. See Listing 15.2 for a further account of how global declarations are defined and used in LotusScript.
Listing 15.14 Global Declarations
1. Dim db As NotesDatabase 2. Dim view As NotesView 3. Dim dc As NotesDocumentCollection 4. Dim parentDoc As NotesDocument 5. Dim dcDoc As NotesDocument 6. Dim NextDoc As NotesDocument 7. Dim FormName As String 8. Dim errormsg As String 9. Dim refreshView As NotesView
The routine in Listing 15.15 starts by setting the Web context document as the parent doc, shown in line 5, that will be used to gather the documents for the collection. A view object is also set that contains all the documents categorized by the deletion criteria. In this example, ProjectName is used as the criteria that the agent will used to select documents for the collection. Next , while the parentDoc object remains set, the agent creates a document collection ( dc , as shown in line 7.ii), and parses the view looking for documents whose project name matches that of the parent. If the document's projectname field contents match the contents of the parent's, the agent then places the document in the collection. When the collection is processed, the agent flags each document in it for deletion (see Line 7.iii.2.a), saves the document, and gets the next document in the collection until all the documents have been processed in the collection.
Listing 15.15 The Initialize Subroutine
1. Sub Initialize 2. Dim session As New NotesSession z 3. On Error Goto ERRORHANDLER 4. Set db = session.CurrentDatabase 5. Set parentDoc=session.documentcontext 'current web document that is being processed 6. Set view = db.GetView("DeleteParentAndChildren") 7. If Not(parentDoc Is Nothing) Then i. 'Go get all the child docs for the parent and parent and put it in a collection so they can be marked for deletion. ii. Set dc = view.GetAllDocumentsByKey( parentDoc.ProjectName(0),True ) iii. If dc.Count <> 0 Then 1. Set dcDoc = dc.GetFirstDocument 2. While Not (dcDoc Is Nothing) a. dcDoc.Form = "DeleteThisDoc" b. dcDoc.Save False,False c. Set NextDoc = dc.GetNextDocument(dcDoc) d. Set dcDoc = NextDoc e. Set NextDoc = Nothing 3. Wend iv. End If v. 'Now refresh the view to show the updates! vi. Set refreshView = db.GetView("ProjectsActiveUnit") vii. view.refresh 8. End If 9. Exit Sub 10. ERRORHANDLER: 11. errormsg = " * * Agent Error: " & Err & " - " & Error() & _ 12. " in " & "DeleteParentAndChildren at " & Erl() 13. Msgbox errormsg 14. Resume Next 15. End Sub
When all the documents have been processed in the collection, the agent gets the refreshView view, as shown in lines 7.vi and 7.vii and refreshes it, and then completes its run by exiting the subroutine. If an error occurs during the script, the ERRORHANDLER is called to log the error to the log.nsf database on the server. You might want to go a step further and use the NotesLog class in your agent code to record various runtime details in the Agent Log database. Either approach is flexible enough to let you know when an agent succeeds or fails.
The complete code listing for the DeleteDocsMarkedForDeletion agent is shown in Listing 15.16.
Listing 15.16 The DeleteDocsMarkedForDeletion Agent Complete Script Listing
'DeleteDocsMarkedForDeletion: Option Public Option Explicit Dim db As NotesDatabase Dim view As NotesView Dim dc As NotesDocumentCollection Dim dcDoc As NotesDocument Dim NextDoc As NotesDocument Dim errormsg As String Sub Initialize Dim session As New NotesSession Set db = session.CurrentDatabase Set view = db.GetView("AllDeletionDocs") 'Go get all the child docs for the parent and parent and put it in a collection so they can be marked for deletion. Set dc = view.GetAllDocumentsByKey( "DeleteThisDoc" ,True ) If dc.Count <> 0 Then Set dcDoc = dc.GetFirstDocument While Not (dcDoc Is Nothing) dcDoc.Form = "DeleteThisDoc" Set NextDoc = dc.GetNextDocument(dcDoc) dcDoc.Remove True Set dcDoc = NextDoc Set NextDoc = Nothing Wend End If Exit Sub LOGERROR: errormsg = " * * Error: " & Err & " - " & Error() & _ " in " & "DeleteDocsMarkedForDeletion at " & Erl() Msgbox errormsg Resume Next End Sub
The complete code listing for the DeleteParentAndChild agent is shown in Listing 15.17.
Listing 15.17 The DeleteParentAndChild Agent Complete Script Listing
'DeleteParentAndChildren: Option Public Option Explicit Dim db As NotesDatabase Dim view As NotesView Dim dc As NotesDocumentCollection Dim parentDoc As NotesDocument Dim dcDoc As NotesDocument Dim NextDoc As NotesDocument Dim FormName As String Dim errormsg As String Dim refreshView As NotesView Sub Initialize Dim session As New NotesSession On Error Goto ERRORHANDLER Set db = session.CurrentDatabase Set parentDoc=session.documentcontext 'current web document that is being processed Set view = db.GetView("DeleteParentAndChildren") If Not(parentDoc Is Nothing) Then 'Go get the parent and all its child docs, and put in a collection so they can be marked for deletion. Set dc = view.GetAllDocumentsByKey( parentDoc.ProjectName(0),True ) If dc.Count <> 0 Then Set dcDoc = dc.GetFirstDocument While Not (dcDoc Is Nothing) dcDoc.Form = "DeleteThisDoc" dcDoc.Save False,False Set NextDoc = dc.GetNextDocument(dcDoc) Set dcDoc = NextDoc Set NextDoc = Nothing Wend End If 'Now refresh the default view to reflect the updates! Set refreshView = db.GetView("ProjectsActiveUnit") view.refresh End If Exit Sub ERRORHANDLER: errormsg = " * * Agent Error: " & Err & " - " & Error() & _ " in " & "DeleteParentAndChildren at " & Erl() Msgbox errormsg Resume Next End Sub
Part I. Introduction to Release 6
Whats New in Release 6?
The Release 6 Object Store
The Integrated Development Environment
Part II. Foundations of Application Design
Forms Design
Advanced Form Design
Designing Views
Using Shared Resources in Domino Applications
Using the Page Designer
Creating Outlines
Adding Framesets to Domino Applications
Automating Your Application with Agents
Part III. Programming Domino Applications
Using the Formula Language
Real-World Examples Using the Formula Language
Writing LotusScript for Domino Applications
Real-World LotusScript Examples
Writing JavaScript for Domino Applications
Real-World JavaScript Examples
Writing Java for Domino Applications
Real-World Java Examples
Enhancing Domino Applications for the Web
Part IV. Advanced Design Topics
Accessing Data with XML
Accessing Data with DECS and DCRs
Security and Domino Applications
Creating Workflow Applications
Analyzing Domino Applications
Part V. Appendices
Appendix A. HTML Reference
Appendix B. Domino URL Reference