TABLE A: Agent Basics
| Item | Description |
| Type | Shared Agent |
| Suggested name | Change Field Values or ChangeFieldValues |
| When should this agent run? | Manually from actions menu |
| Which document(s) should it act on? | Selected documents |
How to Activate the Agent
Open the database in which you want to use the agent in design mode. Create a shared action and give it the following formula:
| @Command ( [ToolsRunMacro] ; "ChangeFieldValues" ) |
To create a shared action, navigate to Resources->Other->Shared Actions in the database design hierarchy and then choose Create->Shared Action from the menu.
Open the view in which you would like for this shared action to appear, click on one of the existing actions in the action pane and choose Create->Insert Shared Action from the menu.
Agent code
Paste the following code into the agent that you create. Or, for a sample database containing the code, go to http://dan.velasco.com.
The code below consists of the following components:
- Options;
- Declarations;
- Initialize;
- CreateFieldChoiceList;
- ConfirmChange;
- SortArray;
- Swap.
And now for the code:
'-OPTIONS SECTION
Option Public
Option Explicit
%INCLUDE "lsconst.lss" |
'-DECLARATIONS SECTION
'--Dim the global variables
'--DATABASES
Dim currentDB As NotesDatabase
'--DOCUMENTS
Dim selectedDoc As NotesDocument
'--ARRAYS
Dim formName As String
Dim fieldNames() As String
Dim newValue As String
Dim continue As String
Dim fieldChoice As Variant
Dim fieldChoiceList As Variant |
Sub Initialize
'--Dim the local variables
Dim session As New NotesSession
Dim workspace As New NotesUIWorkspace
Dim selectedDocs As NotesDocumentCollection
Dim notesItem As NotesItem
'--Set the variables
Set currentDB = session.CurrentDatabase
Set selectedDocs = currentDB.UnprocessedDocuments
'--Return an error and exit the sub if no document is selected
If ( selectedDocs.Count = 0 ) Then
Msgbox "Please select a document.", MB_OK, "Error:"
Exit Sub
End If
'--Get the name of the form of the first selected document
Set selectedDoc = selectedDocs.GetFirstDocument
formName = selectedDoc.Form(0)
'--Call the CreateFieldChoiceList sub which will return a list of all the fields on the form for the user to choose from
Call CreateFieldChoiceList
'--Ask the user which field they would like to change
fieldChoice = workspace.Prompt ( PROMPT_OKCANCELLIST, "Field Name:", "Please choose the name of the field you would like to change.", fieldChoiceList(0), fieldChoiceList )
'--Get the current value of the selected field from the first document
'--and present it to the reader as the default choice.
Set notesItem = selectedDoc.GetFirstItem ( fieldChoice )
newValue = Inputbox ( "What is the new value for this field?", "New Value:", notesItem.Text )
'--Call the ConfirmChange sub to confirm they want to make this change
Call ConfirmChange
'--Exit this sub if the user chooses not to make the change
If ( continue = "No" ) Then
Exit Sub
End If
'--Replace the value on the selected documents
Do Until ( selectedDoc Is Nothing )
Set notesItem = selectedDoc.GetFirstItem ( fieldChoice )
notesItem.Values = newValue
Call selectedDoc.Save ( True, True )
Set selectedDoc = selectedDocs.GetNextDocument ( selectedDoc )
Loop
End Sub |
Sub CreateFieldChoiceList
'--Dim the local variables
Dim form As NotesForm
Dim i As Integer
i = 0
'--Get the form that the first selected document uses
Set form = currentDB.GetForm ( formName )
'--Build an array of the field names from the selected document
Forall item In selectedDoc.Items
Redim Preserve fieldNames(i)
'--If the field name begins with a "$", then skip it
If ( Left ( item.Name, 1 ) <> "$" ) _
And ( item.Type <> RICHTEXT ) _
And ( item.Name <> "UNID" ) _
And ( item.Name <> "FORM" ) Then
fieldNames(i) = item.Name
i = i + 1
End If
End Forall
'--Sort the fields by name before you present them as choices to the user
fieldChoiceList= SortArray ( fieldNames )
End Sub |
Sub ConfirmChange
'--Dim the local variables
Dim confirm As Integer
'--Ask the user if they are sure they want to make the change
confirm = Msgbox ( "Are you sure you want to change the " & Cstr ( fieldChoice ) & _
" field to """ & newValue & """ for all selected documents?", _
MB_OKCANCEL, "Confirm Change:" )
'--Set the value of the continue variable to either "Yes" or "No"
If ( confirm = IDOK ) Then
continue = "Yes"
Else
continue = "No"
Exit Sub
End If
End Sub |
Function SortArray ( inarray As Variant ) As Variant
'--This SortArray function can be put into a script library along with the
'--Swap sub and called from there
Dim i%, j%, max%
Dim array As Variant
array = inarray
max% = Ubound(array)
For i% = 0 To max% - 1
For j% = i% + 1 To max%
If array(i%) > array(j%) Then
Swap array(i%), array(j%)
End If
Next
Next
SortArray = array
End Function |
Sub Swap ( v1 As Variant, v2 As Variant )
'--This Swap sub can be placed in a script library along
'--with the SortArray function and called from there
Dim v As Variant
v = v1
v1 = v2
v2 = v
End Sub |
Conclusion
The possibilities for customizing this agent are many. You can modify it so that you further narrow down the fields and even types of fields that you allow the user to change. You can make it an agent that worms its way through all of the documents in a database changing any fields that have a specific value that you specify. Or you can use it as is and save yourself from having to constantly create simple agents that change specific fields.
It's been a while since I've done a how-to article and I've definitely had fun doing this one. If you have any comments or questions, you can reach me at my new company at dan_velasco@idg.com. And, for a sample database containing all of the code contained in this article, go to http://dan.velasco.com. |
|