ShowTable of Contents
Introduction
The IBM® Lotus® Notes® ID Vault feature helps users by automatically collecting user ID files, so as to have centralized ID management in Lotus Domino®. Using the ID Vault, we can reset passwords and recover IDs easily; moreover, the ID Vault has removed the need to visit desktops for ID management.
In some cases, however, there may instances when the user ID files might not be collected due to incorrect configurations or some flaws from the administration end. Administrators must then manually check the Vault database to determine whether it contains IDs for all the current users. This can be an easy task, if there a only a few users; however, it can be cumbersome to find missing IDs when there are many users.
To overcome this we propose a solution called the Vault Database Scanner, which can automatically scan the Vault database and the Names.nsf file and report IDs missing from the Vault database.
The tool has been developed as a plug-and-play type in that you don't need to configure the tool to make it operational; all you need to do is deploy the tool and run the desired agent.
Understanding the Vault Database Scanner
The database contains two LotusScript agents called "Vault Scanner" and “Create Configuration Document”. The Vault Scanner agent consists of four main functions called GetVaultDocuments, Comparison, RemoveLocalTempVaultDoc, and removeoldconfigdocuments.
Create Configuration Document agent
The Create Configuration Document agent consist of one main function function called “CreateConfigDocument, which scans the Notes Address Book to determine how many Vault databases there are for an organization directory. It then creates a Configuration document within the database, to store the path of the Vault databases.
The function is coded to remove any previous Configuration documents before creating new Configuration documents so that, when we run the tool, we probe with the current configuration so that we are not using any old configurations for scanning (see listing 1).
Listing 1. Code for CreateConfigDocument
Function createconfigdocument As Boolean
Dim S As New NotesSession
Dim CurDB As NotesDatabase
Dim CurView As NotesView
Dim NABDB As NotesDatabase
Dim NABVIEW As NotesView
Dim CurDoc As NotesDocument
Dim ConfigDoc As NotesDocument
Set curdb = s.currentdatabase
Set CurView = Curdb.getview("Configuration")
Set CurDoc = CurView.getfirstdocument()
If CurDoc Is Nothing Then
GoTo CreateConfigDoc
Else
MsgBox "We detect some previous configuration document exist, we would be clearing those documents"
GoTo RemoveOldConfigDoc
End If
RemoveOldConfigDoc:
Dim CurViewEntryCollection As NotesViewEntryCollection
Dim CurViewEntry As NotesViewEntry
Set CurViewEntryCollection = Curview.allentries
Set CurViewEntry = CurViewEntryCollection.getfirstentry
Do Until curviewentry Is Nothing
Dim delconfigdoc As NotesDocument
Set delconfigdoc = curviewentry.document
Call delconfigdoc.remove(True)
Set curviewentry = curviewentrycollection.getnextentry(curviewentry)
Loop
MsgBox "We have removed your previous configuration documents from this scanner database,and now creating new configuration documents"
GoTo CreateConfigDoc
CreateConfigDoc:
Dim NABVaultDoc As NotesDocument
Dim NABVaultView As NotesView
Dim server As String
server = curdb.server
Set NABDB = S.getdatabase(server, "names.nsf")
Set NABVaultView = NABDB.GetView("IDVaults")
Set NABVaultDoc = NABVaultView.getfirstdocument( )
While Not NABVaultDoc Is Nothing
Dim VaultServerList As String
Dim IDVaultPath As String
IDVaultPath$ = NABVaultDoc.VTPath(0)
VaultServerList$ = NABVaultDoc.VaultServerList(0)
'MsgBox VaultServerList
Set ConfigDoc = CurDB.CreateDocument
ConfigDoc.form = "frmconfig"
ConfigDoc.fldidvaultpath = IDvaultPath
Configdoc.FldIDVaultServer = VaultServerList
Call Configdoc.save ( True, True)
Set NABVaultDoc = NABVaultView.getnextdocument(NABVaultDoc)
Wend
MsgBox "Created Configuration Document Successfully, now click the button ScanNow to identify missing Vault Documents"
End Function
VaultScanner agent
The VaultScanner agent consists of four main functions called GetVaultDocuments, Comparison, RemoveLocalTempVaultDoc, and removeoldconfigdocuments.
The GetVaultDocuments function uses the Configuration document to open the individual Vault databases, read each document, and take the field value (IDOwner) to create a temporary Vault document within the scanner databases (see listing 2). The agent copies only the name of the user who is in the Vault database and nothing else.
Listing 2. Code for GetVaultDocuments
Function GetVaultDcouments As Boolean
Dim S1 As New NotesSession
Dim tardoc As NotesDocument
Dim curdb1 As NotesDatabase
Dim curview1 As NotesView
Set curdb1= s1.currentdatabase
Set curview1 = CurDB1.GetView("Configuration")
Set tardoc = Curview1.getfirstdocument()
While Not tardoc Is Nothing
Dim temp1 As String
Dim temp2 As String
temp1 = tardoc.fldidvaultpath(0)
temp2 = tardoc.fldidvaultserver(0)
Dim openvaultDB As NotesDatabase
Dim openvaultview As NotesView
Dim openvaultdoc As NotesDocument
Dim vaultviewentrycollection As NotesViewEntryCollection
Dim vaultviewEntry As NotesViewEntry
Set openvaultdb = S1.Getdatabase(Temp2$, Temp1$)
Set openvaultview = OpenVaultDB.getView("Vault Users")
Set vaultviewentrycollection = OpenVaultView.Allentries
Set vaultviewEntry = VaultViewEntryCollection.getfirstentry()
While Not vaultviewentry Is Nothing
Dim copyvaultidowner As String
Set openVaultDoc = vaultviewentry.Document
copyvaultidowner$ = openvaultdoc.idowner(0)
'MsgBox CopyVaultIDowner
'Create local tempID Vault Document for comparison
Dim localtempidvaultdoc As NotesDocument
Set localtempidvaultdoc = curdb1.createdocument()
localtempidvaultdoc.form = "FrmTempVaultFile"
localtempidvaultDoc.fldidowner = copyvaultidowner$
Call localtempidvaultdoc.save(True, True)
Set vaultviewentry = vaultviewentrycollection.getnextentry(vaultviewentry)
Wend
Set tardoc = CurView1.getnextdocument(tardoc)
Wend
End Function
The Comparison function compares the users in the Address book with the locally created Person entry, and reports any user who doesn't have a Person entry in the view (see listing 3).
Listing 3. Code for Comparison function
function comparison as boolean
dim s2 as new notessession
dim curdb2 as notesdatabase
dim curdb2view2 as notesview
dim curdb2view2doc2 as notesdocument
dim nab2 as notesdatabase
dim nab2view2 as notesview
dim nab2doc2 as notesdocument
dim curdb2view2entrycollection2 as notesviewentrycollection
dim curdb2view2entry2 as notesviewentry
dim server2 as string
dim flag as string
set curdb2 = s2.currentdatabase
dim resultdoc as notesdocument
set resultdoc = curdb2.createdocument()
resultdoc.form = "frmresult"
dim item as notesitem
set item = resultdoc.replaceitemvalue("fldmissingvault", null)
call resultdoc.save( true, true)
set curdb2view2 = curdb2.getview("localtempidvaultdocuments")
server2 = curdb2.server
set nab2 = s2.getdatabase(server2, "names.nsf")
set nab2view2 = nab2.getview("people")
set nab2doc2 = nab2view2.getfirstdocument()
while not nab2doc2 is nothing
set curdb2view2entrycollection2 = curdb2view2.allentries
set curdb2view2entry2 = curdb2view2entrycollection2.getfirstentry()
flag =0
while not curdb2view2entry2 is nothing
set curdb2view2doc2 = curdb2view2entry2.document
dim persondocname as string
dim vaultdocname as string
persondocname$ = nab2doc2.fullname(0)
vaultdocname$ = curdb2view2doc2.fldidowner(0)
if persondocname = vaultdocname then
'skiploop
flag=1
end if
set curdb2view2entry2 = curdb2view2entrycollection2.getnextentry(curdb2view2entry2)
wend
if flag=0 then
call item.appendtotextlist(persondocname)
call resultdoc.save(true, true)
end if
set nab2doc2 = nab2view2.getnextdocument(nab2doc2)
wend
end function
The RemoveLocalempIDVaultDocuments function removes all the locally created temporary Vault documents from the scanner database, after which the database is ready for the next run.
Listing 4. Code for RemoveLocalempIDVaultDocuments function
Function removelocaltempvaultdoc As Boolean
dim s3 as new notessession
dim curdb3 as notesdatabase
dim curdb3view3 as notesview
dim curdb3view3entrycollection as notesviewentrycollection
dim curdb3view3entry as notesviewentry
set curdb3=s3.currentdatabase
set curdb3view3 = curdb3.getview("localtempidvaultdocuments")
set curdb3view3entrycollection = curdb3view3.allentries
set curdb3view3entry = curdb3view3entrycollection.getfirstentry()
while not curdb3view3entry is nothing
dim curdb3view3doc3 as notesdocument
set curdb3view3doc3 = curdb3view3entry.document
call curdb3view3doc3.remove(true)
set curdb3view3entry = curdb3view3entrycollection.getnextentry(curdb3view3entry)
wend
End Function
The Removeoldconfigdocuments function runs last, removing all your previously created Configuration documents and ensuring that the database/tool is ready for the next run.
Listing 5. Code for Removeoldconfigdocuments function
Function removeoldconfigdocuments As Boolean
Dim S4 As New NotesSession
Dim curdb4 As NotesDatabase
Dim curdoc4 As NotesDocument
Dim curdb4view4 As NotesView
Dim curdb4view4entrycollection As Notesviewentrycollection
Dim curdb4view4entry4 As NotesViewEntry
Set curdb4 = s4.currentdatabase
Set curdb4view4 = curdb4.getview("Configuration")
Set curdb4view4entrycollection = curdb4view4.Allentries
Set curdb4view4entry4 = curdb4view4entrycollection.getfirstentry
Do Until curdb4view4entry4 Is Nothing
Set curdoc4 = curdb4view4entry4.Document
Call curdoc4.remove(True)
Set curdb4view4entry4 = curdb4view4entrycollection.getnextentry(curdb4view4entry4)
Loop
End Function
Do not run the tool from the local Notes client; you must deploy this database on your Domino server before you try running the tool.
Figure 1 shows all the Script Functions that are used in this agent.
Figure 1. Script functions
Running the VaultScanner agent
You can run the agent in any of the following three methods:
Method 1
1. Open the Vault Database Scanner on the Notes Client, expand IDVault Scanner, and select Configuration View (see figure 2).
Note the two buttons, “CreateConfigurationDocument” and “ScanNow” at the top. As the name implies, you use the CreateConfigurationDocument to create a Configuration document, with the information about your Vault databases and the Vault server.
NOTE:
- The button triggers the Create Configuration Document agent, which is coded to fail if the agent detects any previous Configuration document in the Configuration View. Ensure that the Configuration View is empty before attempting to click the CreateConfigurationButton button.
Figure 2. ID Vault Database Scanner
- Upon successful creation of Configuration documents, a pop-up window displays, indicating your next step (see figure 3). If the process fails for any reason, it will provide you the necessary information to deal with it.
Figure 3. Success pop-up window
- The ScanNow code is designed to delete Configuration documents that you created previously. However, if for some reason the agent has been stopped prematurely, you will end up in having the documents in the Configuration View. In those rare instances, the CreateConfigurationDocument button will remove the previous Configuration documents before creating new ones (see figure 4).
Figure 4. ScanNow detecting previous Config docs
2. After you create the Configuration doc, click the ScanNow button, to scan all your Vault databases with the directory (Names.nsf) and report any missing Vault documents.
Method 2
1. Open the Vault Scanner database on the Notes Designer client, select Code --- Agents, right-click on CreateConfigurationDocument, and select Run (see figure 5)
Figure 5. VaultScanner database in Designer client
2. After you create the Configuration documents successfully, select Code --- Agents, right-click on VaultScanner4, and select Run (see figure 6).
Figure 6. Run VaultScanner
Figure 7 illustrates the tool architecture in the form of a flow chart diagram.
Figure 7. Tool architecture in the form of a flow chart
Conclusion
The ID Vault Database Scanner automatically scans the Vault database and the Names.nsf file and reports IDs missing from the Vault database. This article provides the code for this tool and explains its architecture, so that you can deploy and configure the tool in your production environment and enjoy the full benefit of its automation.
Tell us what you think
Please visit this link to take a one-question survey about this article:
http://www.surveymonkey.com/s/9Q6ZKGN
Resources
developerworks® Lotus Notes and Domino product page:
http://www.ibm.com/developerworks/lotus/products/notesdomino/
Lotus Notes product documentation:
http://www.ibm.com/developerworks/lotus/documentation/notes/
Notes/Domino 8 Forum:
http://www-10.lotus.com/ldd/nd8forum.nsf?OpenDatabase
About the authors
Shankar Venkatachalam is a Software Engineer at IBM's India Software Labs. He works on crash, core, and performance issues for Notes/Domino servers and more recently has been working with the IBM SmartCloud Notes L3/Development team. You can reach him at svenkat7@in.ibm.com.
Ranjit S Rai is a Software Advisory Team Engineer and a member of the APAC Software Advisory Team (APAC SWAT) for Lotus Domino. He has worked with IBM and Lotus products for more than 10 years. You can reach him at ranjit.rai@in.ibm.com.