With our transition to XPages, I’ve been finding more and more often that I don’t have a form interface in the Notes client to just change one field value on the back end. Too often, on the front end, in XPages, there’s a value I simply haven’t exposed for editing or don’t even display. I often don’t add the fields to the back end Notes form because it really doesn’t add much value. So, when I want to change one field, or change one field on multiple documents, I do it with an agent. Heck, over the years, we all have. We just usually did it in a very static manner – writing a quick @formula to change the value of a specific field. That requires changing the design to create the agent and then delete the agent – or leaving a mess behind that slowly grows your agent list with more and more single-use agents.
So, I wrote an agent that allowed me to replace a text field by naming the field and the value. Then, I found I wanted one for numbers as well. So, for a few weeks, I had two agents. Then, I realized the folly and wrote an agent that detects the field being updated (or asking you if the field doesn’t exist). I only did it for text, numbers and dates, so I imagine it could be extended. It’s enough for me. Since I had occasion to share it this week with another developer, I thought I’d also post it here to share via the blogosphere.
While there’s nothing brilliant about it, it sure is useful.
%REM
Agent Change Field Value
Created Jun 19, 2015 by David Navarre/DAI
Description: This Agent allows the user to name a field and change the value
It checks the field type on the first document selected and
handles strings, numbers and dates differently
%END REM
Option Public
Option Declare
Use "Utilities"
Dim ws As NotesUIWorkspace
Dim newDate As NotesDateTime
Dim newvalue As Variant
Dim fieldname As Variant
Dim change As String
Sub Initialize
Dim session As New NotesSession
' thisdb declared in Utilities '
Dim ndc As NotesDocumentCollection
Dim itemdoc As NotesDocument
Dim itemToChange As NotesItem
Dim numericValue As Double
Dim itemType As Long
Dim selectedType (2) As String
Dim choice As Variant
Dim reason As String
On Error GoTo errorhandler
Set ws = New NotesUIWorkspace
Set thisdb = session.CurrentDatabase
selectedType (0) = "Date"
selectedType (1) = "Text"
selectedType (2) = "Numbers"
Call StartAgentLogging (session )
fieldname = ws.Prompt ( PROMPT_OKCANCELEDIT, "Field Name", "Enter the name of the field to change" )
If IsEmpty ( fieldname ) Then
Exit Sub
End If
newvalue = ws.Prompt ( PROMPT_OKCANCELEDIT, fieldname, "Enter the new value for " & fieldname )
If IsEmpty ( newvalue ) Then
Exit Sub
End If
' get the collection before issuing the confirmation, so we can determine field type '
' from the first document selected, assuming it is the same on the rest '
Set ndc = thisdb.UnprocessedDocuments
Set itemdoc = ndc.GetFirstDocument
Call agentLog.LogAction ( "Items: " & ndc.Count )
If ( itemdoc.Hasitem(fieldname) ) Then
Set itemToChange = itemdoc.Getfirstitem(fieldname)
itemType = itemToChange.Type
Else
choice = ws.Prompt(PROMPT_OKCANCELLIST, "Select field type", "Field " & fieldname & " does not exist on the first document. Select field type to create", "Text", selectedType )
If IsEmpty ( choice ) Then
MessageBox "Action cancelled"
Exit Sub
End If
Select Case choice
Case "Date"
itemType = 1024
Case "Text"
itemType = 1280
Case "Number"
itemType = 768
End Select
End If
If Confirm ( itemType ) Then
While Not itemdoc Is Nothing
Select Case itemType
Case 1024 ' DATETIMES '
Call itemdoc.ReplaceItemValue ( fieldname, newDate )
Case 1280 ' TEXT '
Call itemdoc.ReplaceItemValue ( fieldname, newValue )
Case 768 ' NUMBERS '
' if the value supplied is an integer, save it that way '
If ( CInt ( CDbl ( newValue ) ) = CInt ( newValue ) ) Then
Call itemdoc.ReplaceItemValue ( fieldname, CInt ( newValue ) )
else
Call itemdoc.ReplaceItemValue ( fieldname, CDbl ( newValue ) )
End If
End Select
Call agentLog.LogAction ( change )
Call itemdoc.Save ( True, False )
Set itemdoc = ndc.GetNextDocument ( itemdoc )
Wend
MessageBox change & Chr$(10) & "Successful on " & ndc.Count & " documents"
End If
exiting:
Call agentLog.LogAction ( "-------" )
Call agentLog.LogAction ( "-------" )
Exit Sub
errorhandler:' report all errors in a messagebox '
reason = "Error #" & CStr (Err) & " (" & Error & ") on line " & CStr (Erl)
MessageBox reason, 16, "Error"
Call agentLog.LogAction ( reason )
Resume exiting
End Sub
%REM
Function ConfirmValue
Description: This function displays a confirmation dialog based on the field type
%END REM
Function Confirm ( itemType As Long ) As Boolean
Select Case itemType
Case 1024 ' DATETIMES '
Set newDate = New NotesDateTime ( newValue )
change = "Change date in " & fieldname & " to " & newDate.Dateonly
Case 1280 ' TEXT '
change = "Change text in " & fieldname & " to " & newValue
Case 768 ' NUMBERS '
change = "Change number in " & fieldname & " to " & newValue
Case 1 ' RICHTEXT '
Confirm = False
MessageBox "Cannot change rich text using this agent"
Exit Function
Case Else
Confirm = False
MessageBox "Cannot change " & fieldname & " using this agent" & Chr$(10) & "Field type: " & itemType
Exit Function
End Select
Confirm = ws.Prompt ( PROMPT_YESNO, "Confirmation", change & "?" )
End Function
Oh, and the relevant snippet of the Utilities script library….
%REM
Library Utilities
Created Mar 29, 2012 by David Navarre/DAI
Description: Some database utilities
%END REM
Option Public
Option Declare
Dim thisdb As NotesDatabase
Dim agentLog As NotesLog
Sub Initialize
End Sub
Sub StartAgentLogging ( session As NotesSession )
' this module starts agent logging '
' 29 Mar 12, David Navarre '
Dim title As String
Dim agent As NotesAgent
Set agentLog = session.CreateLog ("Agent log")
Set agent = session.Currentagent
Call agentLog.OpenAgentLog
Call agentLog.LogAction ( "Log Open" )
End Sub
Lost in Code 