Useful agents for IBM Lotus Notes and Domino administrators
Sudhakar Kunam
Staff Software Engineer
IBM Software Group
Pune, India
September 2009
Summary: This article is a collection of code examples that IBM® Lotus® Notes® / Domino® Administrators can use to automate common, complex tasks for which there are no existing default features. All these agents can be customized to suit your requirements.
Contents
1. Determining what folder contains a particular document in Lotus Notes when the FolderReferences property is not enabled for the database. 1
2. Deleting script libraries (using IBM Lotus Domino Designer) from the Notes mail database programmatically 3
3. Determining programmatically whether a particular Domino Server policy has been applied to users 4
4. Moving users from one OU to a different OU programmatically. 5
5. Deleting Calendar Profiles for multiple users. 6
6. Changing the default setting of a Location document programmatically. 7
7. Unchecking the option 'Prohibit design refresh or replace to modify' in “About Database" docs, "Using Database" docs, and Db Icons in all the databases programmatically. 8
About the author 10
About this agent: Folders let you store and manage related documents, and they are convenient because you can drag/drop documents into them. At times, you may need to find which folder contains a specific document.
To do this, we create an agent, navigate to the All Documents view, select the specific document for which you want to find the folder, and run the agent from the Actions menu. Here are the steps:
- Create an agent and name it.
- Specify the trigger set as: Action Menu Selection.
- Specify the Target as: All Selected documents.
- Add the following code in the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Dim doc As notesdocument
Dim doc2 As notesdocument
Dim view As notesview
Dim noteid1 As String
Dim noteid2 As String
Dim item As notesitem
Dim collection As notesdocumentcollection
Set db=session.CurrentDatabase
Set collection=db.UnprocessedDocuments
Set doc=collection.getfirstdocument
noteid1=doc.NoteID
Forall v In db.Views
If v.isfolder Then
Set doc2=v.GetFirstDocument
While Not doc2 Is Nothing
noteid2=doc2.NoteID
If noteid1=noteid2 Then
Messagebox v.name
End If
Set doc2=v.getnextdocument(doc2)
Wend
End If
End Forall
- Save the agent.
- Navigate to the All Documents view and select a document against which you want the agent to run.
(For more information, see IBM Support Technote #1295618)
About this agent: When troubleshooting the mail template/database issues, a Notes developer may need to delete the script libraries and replace the design of the database with the template. Instead of doing it manually, you can create an agent with the below code and run it from the user’s mail file.
NOTE: The below code is written to delete the "CommonUI" script library. You can change the name of the Script library as per your requirement.
- Launch Lotus Domino Designer.
- Create an agent and name it.
- Specify the trigger set as: Action Menu Selection.
- Specify the Target as: None.
- Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Dim doc As notesdocument
Dim nc As NotesNoteCollection
Set nc = db.CreateNoteCollection(False)
nc.SelectScriptLibraries=True
Call nc.BuildCollection
nid = nc.GetFirstNoteId
For i = 1 To nc.Count
Set doc = db.GetDocumentByID(nid)
subj = doc.GetItemValue("$TITLE")
If subj(0)="CommonUI" Then
Messagebox subj(0), , "removing document"
Call doc.Remove(True)
End
End If
nid = nc.GetNextNoteId(nid)
Next
- Save the agent
(For more information, see IBM Support Technote #1303742)
About this agent: The below code gets executed on closing the database for the first time and sends an email to the administrator stating whether the given policy has been applied on the Client.
- Write the below code in QueryClose event of the Database Script.
- Here we have used some variable names; you may need to change them per your configuration.
- We tried the code with Desktop policy named as "DSKTP" and Administrator as "Lotus Admin/org8".
Dim session As New notessession
Dim db As New notesdatabase("","names.nsf")
Dim view As notesview
Dim doc As notesdocument
Dim doc1 As notesdocument
Set view=db.GetView("$Policies")
Set doc=view.GetFirstDocument
Dim check As String
check=session.GetEnvironmentString("polvar")
If check="" Then
Call session.SetEnvironmentVar("polvar","No")
End If
Dim status As String
While Not doc Is Nothing
status=session.GetEnvironmentString("polvar")
If doc.FullName(0)="DSKTP" Then
If status="No" Then
Set doc1=db.CreateDocument
doc1.form="Memo"
doc1.subject="Policies Applied"
doc1.SendTo=" Lotus Admin/org8"
Call doc1.send(True,True)
Call session.SetEnvironmentVar("polvar","Yes")
End If
End
End If
Set doc=view.GetNextDocument(doc)
Wend
About these agents: Here we create two agents in the Domino Directory: The first is the Main agent, and the second is the AP agent. Administrators need to select the Person document from Domino Directory and run the agent (Main) from the Action menu to move the user to different OU.
· In the below code, we have used Cert.id for Org name, Test703/Org703 for Server name, and ITD for the new OU name.
· When you run the Main agent, it calls the ‘AP’ agent which runs on the server.
The steps to create the agent and the code for “Main” are as follows:
1. Create an agent and name it.
2. Specify the trigger set as: Action Menu Selection.
3. Specify the Target as: All Selected documents.
4. Add the following code in the Script Area:
Sub Initialize
Dim session As New notessession
Dim db As notesdatabase
Dim agent As NotesAgent
Set db=session.CurrentDatabase
Dim collection As NotesDocumentCollection
Set collection=db.UnprocessedDocuments
Set doc=collection.GetFirstDocument
Set agent=db.GetAgent("AP")
If agent.RunOnServer(doc.noteid) = 0 Then
Messagebox "Agent ran",, "Success"
Else
Messagebox "Agent did not run",, "Failure"
End If
End Sub
The agent creation and the code for “AP” are as follows:
- Create an agent and name it.
- Specify the trigger set as: Agent List Selection.
- Specify the Target as: None.
- Add the following code in the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Set db=session.CurrentDatabase
Dim adminp As NotesAdministrationProcess
Dim agent As NotesAgent
Set agent=session.CurrentAgent
Dim doc1 As NotesDocument
Set doc1=db.GetDocumentByID(agent.ParameterDocID)
Set adminp=session.CreateAdministrationProcess("LOTUS703/ORG703")
adminp.CertifierFile="C:\Lotus703\data\cert.id"
adminp.CertifierPassword="12345"
nid$= Adminp.MoveUserInHierarchyRequest(doc1.fullname(0),"OU=ITD/O=ORG703")
adminp.CertifierFile="C:\Lotus703\data\itd.id"
adminp.CertifierPassword="12345"
Call adminp.MoveUserInHierarchyComplete(nid$)
Call adminp.ApproveRenamePersonInDirectory(nid$)
About this agent: At times, when troubleshooting the mail database issues, we need to delete the Calendar Profile of multiple users. To do this, follow these steps:
1. Open the Domino Directory.
2. Create an agent and name it.
3. Specify the trigger set as: Action Menu Selection.
4. Specify the Target as: Selected Documents.
5. Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim db As NotesDatabase
Dim db1 As NotesDatabase
Dim doc As NotesDocument
Dim doc1 As NotesDocument
Dim mailfil As String
Dim mailserv As String
Dim collection As notesdocumentcollection
Dim view As NotesView
Set db=session.CurrentDatabase
Set collection=db.UnprocessedDocuments
Set doc=collection.GetFirstDocument
While Not doc Is Nothing
mailserv=doc.GetItemValue("MailServer")(0)
mailfil=doc.GetItemValue("MailFile")(0)
Set db1=session.GetDatabase(mailserv,mailfil)
Set doc1=db1.GetProfileDocument("CalendarProfile")
Call doc1.Remove(True)
Set doc=collection.GetNextDocument(doc)
Wend
- Save the agent.
- Open the Admin Client with full admin access.
- Select the users from the People view in the Domino Directory and run the agent. So if, for example, you select two users, the agent will delete the Calendar Profile document in these two user's mail files.
About this agent: The below code is written to change the Recipient Name Lookup field in the Location document to “Exhaustively check all address books”. You can change the name of the field per your requirements.
- Create a new mail message.
2. Select Create > Hotspot > Button.
3. Add a label for the button, such as "Click here".
4. Set it to Run > Client, and select "LotusScript" instead of "Formula".
5. Paste in the code below:
Dim session As New notessession
Dim db As New notesdatabase("","names.nsf")
Dim view As NotesView
Dim doc As notesdocument
Set view=db.GetView("Locations")
Set doc=view.GetDocumentByKey("Online")
doc.ExhaustiveNameLookup="1"
Call doc.save(True,True)
- Send this email to the user who needs to change to this setting. When the user clicks the button, the setting will change to “Exhaustively check all address books.”
About this Agent: The below code unchecks the option “Prohibit design refresh or replace to modify” in "About Database" docs, "Using Database" Docd, and Db Icons in all the databases. Here are the steps:
1. Open the Domino Directory.
2. Create an agent and name it.
3. Specify the trigger set as: Action Menu Selection.
4. Specify the Target as: Selected Documents.
5. Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim doc As notesdocument
Dim db As notesdatabase
Dim db1 As notesdatabase
Set db1=session.currentdatabase
Dim doc1 As NotesDocument
Dim mailfil As String
Dim mailserv As String
Dim collection As notesdocumentcollection
Set collection=db1.UnprocessedDocuments
Set doc1=collection.GetFirstDocument
While Not doc1 Is Nothing
mailserv=doc1.GetItemValue("MailServer")(0)
mailfil=doc1.GetItemValue("MailFile")(0)
Set db=session.GetDatabase(mailserv,mailfil)
' Get handle to the "Icon" design element
Set doc = db.getdocumentbyID("ffff0010")
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
' Get handle to the "Using Database" document
Set doc = db.getdocumentbyID("ffff0100")
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
' Get handle to the "About Database" document
' and check if handle is valid. Db's derived from 3.X templates
' cannot be reset to allow Refresh/Replace to modify this document
Set doc = db.getdocumentbyID("ffff0002")
'If doc Is Nothing Then
'Exit Sub
'End If
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
Set doc1=collection.GetNextDocument(doc1)
Wend
6. Save the agent, and open the Admin Client with full admin access.
7. Select the users from People vew in the Domino Directory and run the agent. So, if for example, you select two users, it will uncheck 'Prohibit design refresh or replace to modify' in "About Database" docs, "Using Database" docs, and Db Icons in these two user's mail files.
Sudhakar Reddy is a Software Engineer currently working on the Domino Application Development team at IBM’s Technical Support Center in Pune, India, before which he worked extensively with the Lotus Domino/Notes Mail & Messaging team. He is an IBM Certified System Administrator for Lotus Notes and Domino 6/6.5. You can reach him at sudkunam@in.ibm.com.
Useful agents for IBM Lotus Notes and Domino administrators
Sudhakar Kunam
Staff Software Engineer
IBM Software Group
Pune, India
September 2009
Summary: This article is a collection of code examples that IBM® Lotus® Notes® / Domino® Administrators can use to automate common, complex tasks for which there are no existing default features. All these agents can be customized to suit your requirements.
Contents
1. Determining what folder contains a particular document in Lotus Notes when the FolderReferences property is not enabled for the database. 1
2. Deleting script libraries (using IBM Lotus Domino Designer) from the Notes mail database programmatically 3
3. Determining programmatically whether a particular Domino Server policy has been applied to users 4
4. Moving users from one OU to a different OU programmatically. 5
5. Deleting Calendar Profiles for multiple users. 6
6. Changing the default setting of a Location document programmatically. 7
7. Unchecking the option 'Prohibit design refresh or replace to modify' in “About Database" docs, "Using Database" docs, and Db Icons in all the databases programmatically. 8
About the author 10
About this agent: Folders let you store and manage related documents, and they are convenient because you can drag/drop documents into them. At times, you may need to find which folder contains a specific document.
To do this, we create an agent, navigate to the All Documents view, select the specific document for which you want to find the folder, and run the agent from the Actions menu. Here are the steps:
- Create an agent and name it.
- Specify the trigger set as: Action Menu Selection.
- Specify the Target as: All Selected documents.
- Add the following code in the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Dim doc As notesdocument
Dim doc2 As notesdocument
Dim view As notesview
Dim noteid1 As String
Dim noteid2 As String
Dim item As notesitem
Dim collection As notesdocumentcollection
Set db=session.CurrentDatabase
Set collection=db.UnprocessedDocuments
Set doc=collection.getfirstdocument
noteid1=doc.NoteID
Forall v In db.Views
If v.isfolder Then
Set doc2=v.GetFirstDocument
While Not doc2 Is Nothing
noteid2=doc2.NoteID
If noteid1=noteid2 Then
Messagebox v.name
End If
Set doc2=v.getnextdocument(doc2)
Wend
End If
End Forall
- Save the agent.
- Navigate to the All Documents view and select a document against which you want the agent to run.
(For more information, see IBM Support Technote #1295618)
About this agent: When troubleshooting the mail template/database issues, a Notes developer may need to delete the script libraries and replace the design of the database with the template. Instead of doing it manually, you can create an agent with the below code and run it from the user’s mail file.
NOTE: The below code is written to delete the "CommonUI" script library. You can change the name of the Script library as per your requirement.
- Launch Lotus Domino Designer.
- Create an agent and name it.
- Specify the trigger set as: Action Menu Selection.
- Specify the Target as: None.
- Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Dim doc As notesdocument
Dim nc As NotesNoteCollection
Set nc = db.CreateNoteCollection(False)
nc.SelectScriptLibraries=True
Call nc.BuildCollection
nid = nc.GetFirstNoteId
For i = 1 To nc.Count
Set doc = db.GetDocumentByID(nid)
subj = doc.GetItemValue("$TITLE")
If subj(0)="CommonUI" Then
Messagebox subj(0), , "removing document"
Call doc.Remove(True)
End
End If
nid = nc.GetNextNoteId(nid)
Next
- Save the agent
(For more information, see IBM Support Technote #1303742)
About this agent: The below code gets executed on closing the database for the first time and sends an email to the administrator stating whether the given policy has been applied on the Client.
- Write the below code in QueryClose event of the Database Script.
- Here we have used some variable names; you may need to change them per your configuration.
- We tried the code with Desktop policy named as "DSKTP" and Administrator as "Lotus Admin/org8".
Dim session As New notessession
Dim db As New notesdatabase("","names.nsf")
Dim view As notesview
Dim doc As notesdocument
Dim doc1 As notesdocument
Set view=db.GetView("$Policies")
Set doc=view.GetFirstDocument
Dim check As String
check=session.GetEnvironmentString("polvar")
If check="" Then
Call session.SetEnvironmentVar("polvar","No")
End If
Dim status As String
While Not doc Is Nothing
status=session.GetEnvironmentString("polvar")
If doc.FullName(0)="DSKTP" Then
If status="No" Then
Set doc1=db.CreateDocument
doc1.form="Memo"
doc1.subject="Policies Applied"
doc1.SendTo=" Lotus Admin/org8"
Call doc1.send(True,True)
Call session.SetEnvironmentVar("polvar","Yes")
End If
End
End If
Set doc=view.GetNextDocument(doc)
Wend
About these agents: Here we create two agents in the Domino Directory: The first is the Main agent, and the second is the AP agent. Administrators need to select the Person document from Domino Directory and run the agent (Main) from the Action menu to move the user to different OU.
· In the below code, we have used Cert.id for Org name, Test703/Org703 for Server name, and ITD for the new OU name.
· When you run the Main agent, it calls the ‘AP’ agent which runs on the server.
The steps to create the agent and the code for “Main” are as follows:
1. Create an agent and name it.
2. Specify the trigger set as: Action Menu Selection.
3. Specify the Target as: All Selected documents.
4. Add the following code in the Script Area:
Sub Initialize
Dim session As New notessession
Dim db As notesdatabase
Dim agent As NotesAgent
Set db=session.CurrentDatabase
Dim collection As NotesDocumentCollection
Set collection=db.UnprocessedDocuments
Set doc=collection.GetFirstDocument
Set agent=db.GetAgent("AP")
If agent.RunOnServer(doc.noteid) = 0 Then
Messagebox "Agent ran",, "Success"
Else
Messagebox "Agent did not run",, "Failure"
End If
End Sub
The agent creation and the code for “AP” are as follows:
- Create an agent and name it.
- Specify the trigger set as: Agent List Selection.
- Specify the Target as: None.
- Add the following code in the Script Area:
Dim session As New notessession
Dim db As notesdatabase
Set db=session.CurrentDatabase
Dim adminp As NotesAdministrationProcess
Dim agent As NotesAgent
Set agent=session.CurrentAgent
Dim doc1 As NotesDocument
Set doc1=db.GetDocumentByID(agent.ParameterDocID)
Set adminp=session.CreateAdministrationProcess("LOTUS703/ORG703")
adminp.CertifierFile="C:\Lotus703\data\cert.id"
adminp.CertifierPassword="12345"
nid$= Adminp.MoveUserInHierarchyRequest(doc1.fullname(0),"OU=ITD/O=ORG703")
adminp.CertifierFile="C:\Lotus703\data\itd.id"
adminp.CertifierPassword="12345"
Call adminp.MoveUserInHierarchyComplete(nid$)
Call adminp.ApproveRenamePersonInDirectory(nid$)
About this agent: At times, when troubleshooting the mail database issues, we need to delete the Calendar Profile of multiple users. To do this, follow these steps:
1. Open the Domino Directory.
2. Create an agent and name it.
3. Specify the trigger set as: Action Menu Selection.
4. Specify the Target as: Selected Documents.
5. Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim db As NotesDatabase
Dim db1 As NotesDatabase
Dim doc As NotesDocument
Dim doc1 As NotesDocument
Dim mailfil As String
Dim mailserv As String
Dim collection As notesdocumentcollection
Dim view As NotesView
Set db=session.CurrentDatabase
Set collection=db.UnprocessedDocuments
Set doc=collection.GetFirstDocument
While Not doc Is Nothing
mailserv=doc.GetItemValue("MailServer")(0)
mailfil=doc.GetItemValue("MailFile")(0)
Set db1=session.GetDatabase(mailserv,mailfil)
Set doc1=db1.GetProfileDocument("CalendarProfile")
Call doc1.Remove(True)
Set doc=collection.GetNextDocument(doc)
Wend
- Save the agent.
- Open the Admin Client with full admin access.
- Select the users from the People view in the Domino Directory and run the agent. So if, for example, you select two users, the agent will delete the Calendar Profile document in these two user's mail files.
About this agent: The below code is written to change the Recipient Name Lookup field in the Location document to “Exhaustively check all address books”. You can change the name of the field per your requirements.
- Create a new mail message.
2. Select Create > Hotspot > Button.
3. Add a label for the button, such as "Click here".
4. Set it to Run > Client, and select "LotusScript" instead of "Formula".
5. Paste in the code below:
Dim session As New notessession
Dim db As New notesdatabase("","names.nsf")
Dim view As NotesView
Dim doc As notesdocument
Set view=db.GetView("Locations")
Set doc=view.GetDocumentByKey("Online")
doc.ExhaustiveNameLookup="1"
Call doc.save(True,True)
- Send this email to the user who needs to change to this setting. When the user clicks the button, the setting will change to “Exhaustively check all address books.”
About this Agent: The below code unchecks the option “Prohibit design refresh or replace to modify” in "About Database" docs, "Using Database" Docd, and Db Icons in all the databases. Here are the steps:
1. Open the Domino Directory.
2. Create an agent and name it.
3. Specify the trigger set as: Action Menu Selection.
4. Specify the Target as: Selected Documents.
5. Copy and paste the following script into the Script Area:
Dim session As New notessession
Dim doc As notesdocument
Dim db As notesdatabase
Dim db1 As notesdatabase
Set db1=session.currentdatabase
Dim doc1 As NotesDocument
Dim mailfil As String
Dim mailserv As String
Dim collection As notesdocumentcollection
Set collection=db1.UnprocessedDocuments
Set doc1=collection.GetFirstDocument
While Not doc1 Is Nothing
mailserv=doc1.GetItemValue("MailServer")(0)
mailfil=doc1.GetItemValue("MailFile")(0)
Set db=session.GetDatabase(mailserv,mailfil)
' Get handle to the "Icon" design element
Set doc = db.getdocumentbyID("ffff0010")
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
' Get handle to the "Using Database" document
Set doc = db.getdocumentbyID("ffff0100")
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
' Get handle to the "About Database" document
' and check if handle is valid. Db's derived from 3.X templates
' cannot be reset to allow Refresh/Replace to modify this document
Set doc = db.getdocumentbyID("ffff0002")
'If doc Is Nothing Then
'Exit Sub
'End If
FlagSettings = doc.getitemvalue("$Flags")
If Instr(1,FlagSettings(0),"R")=0 Then
AddR = FlagSettings(0) & "R"
Call doc.replaceitemvalue("$Flags", AddR)
Call doc.save(1,1)
End If
Set doc1=collection.GetNextDocument(doc1)
Wend
6. Save the agent, and open the Admin Client with full admin access.
7. Select the users from People vew in the Domino Directory and run the agent. So, if for example, you select two users, it will uncheck 'Prohibit design refresh or replace to modify' in "About Database" docs, "Using Database" docs, and Db Icons in these two user's mail files.
Sudhakar Reddy is a Software Engineer currently working on the Domino Application Development team at IBM’s Technical Support Center in Pune, India, before which he worked extensively with the Lotus Domino/Notes Mail & Messaging team. He is an IBM Certified System Administrator for Lotus Notes and Domino 6/6.5. You can reach him at sudkunam@in.ibm.com.