[Code] - Mail Merge/Form Letters in Lotuscript domino lotusscript lsx notes rich text script library application bleedyellow bleedyellow.com database email server

Back in 2003 or so, I wrote some code to take a form letter (stored in a Notes document) and merge that with data stored in another Notes document in order to create a personalized letter that could be printed or emailed. Back then we were still on Notes 5, so very limited rich text functionality and no budget to purchase Ben's excellent Midas LSX. The end result worked, but any formatting in the form letter template was lost.

Eventually we upgraded to Notes 7 and letar to Notes 8.5. Now I had much more rich text functionality to play with, so I rewrote the code as a class. I added some additional functionality, like formatting values using a mask, and some lookup functionality. The class support all kind of formatting in the form letter template, including fonts, colors, tables, graphics, etc.

As you can see, the placeholders are using curly brackets to hold either a field name or a command. The commands are indicated by the percent sign (%). There can also be different arguments, for formatting, lookup into the NAB/Domino Directory, etc. I even have functionality to present a nice dialog box where the user can pick recipient from a list of everyone associated with the claim (as this is from a claim system used by an insurance company).

And now the code, from a script library called Class.MailMerge.
Right now I don't have the time to move the code out of my application and build a working sample database (the form letters are actually stored in a separate database), but I hope that this code can still help someone.

	Option Public
Option Declare

' *** Script Library for MailMerge, preserving formatting in Rich Text field
' *** Requires Notes 6.5 or higher (tested in 7.0)
' *** Written by Karl-Henry Martinsson, Deep South

Const TYPE_FIELD = 1
Const TYPE_CMD = 2
Dim picklist List As NotesDocument 
Dim variable List As String

Class PlaceHolderData
    Public placeholderstring As String
    Public placeholdertype As Integer
    Public fieldname As String
    Public fieldtype As Long
    Public Command As String
    Public argument List As String
    Public Text As String 
    
    Public Sub New(ByVal placeholder As String)
        ' Store the original placeholder
        placeholderstring = placeholder        
        ' Strip out curly brackets before and after
        placeholder = Mid$(placeholder,2,Len(placeholder)-2)
        If Left$(placeholder,1) = "%" Then    ' Check if it is a command
            Me.placeholdertype = TYPE_CMD
            ' Remove the % in front of the command
            placeholder = Right$(placeholder,Len(placeholder)-1)    
        Else
            Me.placeholdertype = TYPE_FIELD
        End If
        Call ParsePlaceHolder(placeholder)
    End Sub
    
    Private Sub ParsePlaceHolder(ByVal placeholder As String)
        Dim startpos As Integer 
        Dim midpos As Integer 
        Dim endpos As Integer 
        Dim args As Integer                            ' Boolean to indicate argements present or not
        Dim argstring As String
        Dim qt As Integer 
        Dim eq As Integer
        Dim char As String
        Dim argname As String
        Dim argvalue As String
        Dim i As Integer
        
        ' First we need to find the end of the command or field.
        ' It is either at the end of the placeholder or when we encounter a space
        endpos = InStr(placeholder," ")        ' Search for space
        If endpos = 0 Then                    ' No space, e.g. no arguments
            endpos = Len(placeholder)                
            args = False
        Else                                ' We have some arguments
            endpos = endpos -1                ' Reduce by one to get rid of trailing space
            args = True
        End If
        If Me.placeholdertype = TYPE_CMD Then
            Me.command = UCase(Left$(placeholder,endpos))
        Else
            Me.fieldname = Left$(placeholder,endpos)            
        End If
        If args = True Then 
            ' Get arguments
            argstring = FullTrim(Right$(placeholder,Len(placeholder)-endpos)    )    ' Get arguments only
            qt = False
            eq = False
            For i = 1 To Len(argstring)
                char = Mid$(argstring,i,1)    ' Get character
                If eq = True Then
                    argvalue=argvalue & char
                Else
                    argname=argname & char
                End If
                
                If char = |"| Then                    ' We found a quote
                    If qt = False Then
                        qt = True                        
                    Else
                        qt = False
                    End If
                ElseIf char="=" Then             ' Found a equal, e.g. now we are getting to a value
                    If eq = False Then
                        eq = True                        
                    Else
                        eq = False
                    End If
                End If
                If i = Len(argstring) Then        ' We are at the end
                    char = " "                        ' Fake a space
                End If
                If char = " " Then                    ' Found a space
                    If qt = False Then            ' Make sure it is not within quotes
                        eq = False                    ' Now we are back at argument name again
                        If Right$(argname,1) = "=" Then                    
                            argname = Left$(argname,Len(argname)-1)    ' Remove trainling equal sign
                        End If
                        Me.argument(UCase(argname)) = FullTrim(Replace(argvalue,|"|,""))    ' Create list item, remove quotes
                        argname = ""
                        argvalue = ""
                    End If
                End If
            Next
        End If
    End Sub
    
    Public Sub ProcessPlaceHolder(sourcedoc As NotesDocument, lossnotice As NotesDocument, selected List As String)
        Dim session As New NotesSession                
        Dim thisdb As NotesDatabase
        Dim ws As New NotesUIWorkspace
        Dim pickcollection As NotesDocumentCollection
        Dim pickdoc As NotesDocument
        Dim servername As String
        Dim dbname As String
        Dim viewname As String        
        Dim fieldvalue As String
        Dim formatstring As String
        Dim inputstr As String
        Dim prompt As String
        Dim title As String
        Dim default As String
        Dim filterfield As String
        Dim filtervalue As String
        Dim nabdoc As NotesDocument
        
        On Error GoTo errCase
        ' Read any formatting specified in arguments
        If IsElement(Me.argument("FORMAT")) Then
            formatstring = Me.argument("FORMAT")
        ElseIf IsElement(Me.argument("FMT")) Then
            formatstring = Me.argument("FMT")
        Else 
            formatstring = ""
        End If
        
        If placeholdertype = TYPE_FIELD Then
            If sourcedoc Is Nothing Then
                MsgBox "Error: sourcedoc not defined, unable to retrieve data from field '" & _
                Me.fieldname & "'.",,"MailMerge::PlaceHolder.ProcessPlaceHolder()"
                fieldvalue = "*** ERROR ***"                
                Exit Sub
            Else
                If IsElement(Me.Argument("LOSSNOTICE")) Then
                    fieldvalue = lossnotice.GetItemValue(Me.fieldname)(0)
                    Me.FieldType = lossnotice.GetFirstItem(Me.fieldname).Type
                ElseIf IsElement(Me.Argument("SOURCE")) Then
                    If UCase(Me.Argument("SOURCE")) = "LOSSNOTICE" Then
                        fieldvalue = lossnotice.GetItemValue(Me.fieldname)(0)
                        Me.FieldType = lossnotice.GetFirstItem(Me.fieldname).Type
                    End If
                ElseIf IsElement(Me.Argument("SELECTED")) Then
                    me.FieldName = StrConv(me.fieldname,3)    ' ProperCase
                '    MsgBox selected("SendTo_" & Me.fieldname),,"Debug"
                    If IsElement(selected("SendTo_" & Me.fieldname)) = True Then
                        fieldvalue = selected("SendTo_" & Me.fieldname)
                    Else 
                        fieldvalue = "n/a"
                    End If
                    Me.FieldType = 1280        ' Force Text
                ElseIf IsElement(Me.Argument("NABFIELD")) Then
                    fieldvalue = GetNABField(sourcedoc.GetItemValue(Me.fieldname)(0), Me.Argument("NABFIELD"))
                Else
                    fieldvalue = sourcedoc.GetItemValue(Me.fieldname)(0)
                    Me.FieldType = sourcedoc.GetFirstItem(Me.fieldname).Type
                End If
                If formatstring <> "" Then
                    If IsDate(fieldvalue) Then           ' Check if it might be a date/time value
                        fieldvalue = Format$(CDat(fieldvalue),formatstring)
                    ElseIf IsNumeric(fieldvalue) Then    ' Check if it might be a numeric value
                        fieldvalue = Format$(CDbl(fieldvalue),formatstring)
                    End If
                End If
            End If
            Me.text = fieldvalue
        Else
        '    MsgBox Me.Command,,"Command"
            ' *** Fix legacy commands
            If UCase(Me.Command) = "USR" Then    
                Me.Command = "USER"
            End If
            ' *** Process placeholder commands
            Select Case UCase(Me.Command)
            Case "USER" :
                If IsElement(Me.Argument("NABFIELD")) Then
                    Me.Text = GetNABField(session.CommonUserName, Me.Argument("NABFIELD")) 
                Else
                    Me.Text = session.CommonUserName 
                End If
            Case "INPUT"        :        ' *** Ask the user to enter information
                prompt = Me.Argument("PROMPT")
                If IsElement(Me.Argument("TITLE")) Then
                    title = Me.Argument("TITLE")
                Else
                    title = "FormLetter Mail Merge"
                End If
                If IsElement(Me.Argument("DEFAULT")) Then
                    default = Me.Argument("DEFAULT")
                Else
                    default = ""
                End If
                If IsElement(Me.Argument("REQUIRED")) Then
                    ' Repeat until user enter a value
                    Do                
                        inputstr = InputBox$(prompt, title, default)                        
                    Loop While FullTrim(inputstr)=""
                Else
                    inputstr = InputBox$(prompt, title, default)                        
                End If
                If formatstring <> "" Then
                    If IsDate(inputstr) Then                    ' Check if it might be a date/time value
                        inputstr = Format$(CDat(inputstr),formatstring)
                    ElseIf IsNumeric(inputstr) Then    ' Check if it might be a numeric value
                        inputstr = Format$(CDbl(inputstr),formatstring)
                    End If
                End If
                Me.Text = inputstr
                ' *** Check for SETVAR argument
                If IsElement(Me.argument("SETVAR")) Then
                    variable(UCase(Me.argument("SETVAR")))=Me.Text
                End If
                
            Case "PICKLIST"    :        ' Present the user with a list of documents to choose from
                Set thisdb = session.CurrentDatabase
                Set pickdoc = Nothing        ' Clear pickdoc
                ' *** We need to get the view argument to perform a lookup into the list...
                If IsElement(Me.Argument("VIEW")) Then
                    viewname = UCase(Me.Argument("VIEW"))
                End If
                ' *** If CLAIMANT argument is specified, set arguments to predefined values
                If IsElement(Me.Argument("CLAIMANT")) Then
                    Me.Argument("VIEW") = "(SysLookupClaimantsCatByParentUNID)"
                    Me.Argument("FILTER") = "ParentUNID"
                    Me.Argument("PROMPT") = "Select Claimant:"
                End If
                ' *** Check if user requested to clear cached data
                If IsElement(Me.Argument("CLEARCACHE")) Then
                    If IsElement(picklist(viewname)) Then
                        Erase picklist(viewname)    ' Delete this cached item (document)
                    End If
                End If
                ' *** If user want to use cached data, load pickdoc with cached data
                If IsElement(Me.Argument("CACHED")) Then
                    If IsElement(picklist(viewname)) Then
                        Set pickdoc = picklist(viewname)
                    End If
                End If
                If pickdoc Is Nothing Then    ' No cached document for this view 
                    If IsElement(Me.Argument("SERVER")) Then
                        servername = Me.Argument("SERVER")
                    Else
                        servername = thisdb.Server
                    End If
                    If IsElement(Me.Argument("DB")) Then
                        dbname = Me.Argument("DB")
                    Else
                        dbname = thisdb.FilePath 
                    End If
                    If IsElement(Me.Argument("VIEW")) Then
                        viewname = Me.Argument("VIEW")    
                    Else
                        MsgBox "Missing Required Argument - VIEW" & Chr$(13) & Me.PlaceHolderString,,"Missing Argument"
                        Exit Sub
                    End If
                    If IsElement(Me.Argument("PROMPT")) Then
                        prompt = Me.Argument("PROMPT")
                    Else
                        MsgBox "Missing Required Argument - PROMPT" & Chr$(13) & Me.PlaceHolderString,,"Missing Argument"
                        Exit Sub
                    End If
                    If IsElement(Me.Argument("TITLE")) Then
                        title = Me.Argument("TITLE")
                    Else
                        title = "FormLetter Mail Merge"
                    End If
onemoretime:                
                    If IsElement(Me.Argument("FILTER")) Then
                        filterfield = Me.Argument("FILTER")                         ' Get field to filter on
                        filtervalue = sourcedoc.GetItemValue(filterfield)(0)        ' Get value of field on source document
                        Set pickcollection = ws.PicklistCollection(3, False, servername, dbname, viewname, title, prompt, filtervalue)
                    Else
                        Set pickcollection = ws.PicklistCollection(3, False, servername, dbname, viewname, title, prompt)
                    End If
                    If IsEmpty(pickcollection) Then
                        If IsElement(Me.Argument("REQUIRED")) Then
                            If UCase(Me.Argument("REQUIRED")) <> "NO" Then
                                MsgBox "You need to select one item/document in the list.", , title
                                GoTo onemoretime
                            End If
                        End If
                    Else
                        Set pickdoc = pickcollection.GetFirstDocument        
                    End If
                    If pickdoc Is Nothing Then
                        MsgBox "Error: No document returned.",,"MailMerge::PlaceHolder.ProcessPlaceHolder()"
                        Exit Sub
                    End If
                    Set picklist(UCase(viewname)) = pickdoc
                End If
                If IsElement(Me.Argument("FIELD")) Then
                    fieldname = Me.Argument("FIELD")
                Else
                    MsgBox "Missing Required Argument - FIELD" & Chr$(13) & Me.PlaceHolderString,,"Missing Argument"                        
                    Exit Sub
                End If
                inputstr = pickdoc.GetItemValue(fieldname)(0)
                If formatstring <> "" Then
                    If IsDate(inputstr) Then                    ' Check if it might be a date/time value
                        inputstr = Format$(CDat(inputstr),formatstring)
                    ElseIf IsNumeric(inputstr) Then    ' Check if it might be a numeric value
                        inputstr = Format$(CDbl(inputstr),formatstring)
                    End If
                End If
                Me.Text = inputstr
                ' *** Check for SETVAR argument
                If IsElement(Me.argument("SETVAR")) Then
                    variable(UCase(Me.argument("SETVAR")))=Me.Text
                End If
                
            Case "DATE"            :         ' *** Current Date
                If formatstring = "" Then 
                    Me.Text = Format$(Now(),"mm/dd/yyyy")
                Else
                    Me.Text = Format$(Now(),formatstring)
                End If
                
            Case "TIME"            :         ' *** Current Time
                If formatstring = "" Then 
                    Me.Text = Format$(Now(),"hh:nn:ss")
                Else
                    Me.Text = Format$(Now(),formatstring)
                End If
                
            Case "GETVAR"    :    ' *** Get variable previously stored
                If IsElement(variable(UCase(Me.argument("NAME")))) Then
                    Me.Text = variable(UCase(Me.argument("NAME")))
                End If
            
            Case Else                :
                Me.Text = "**** undefined command ***"
                
            End Select
        End If
exitSub:
        Exit Sub
errCase:        
        If placeholdertype = TYPE_FIELD Then
            Me.Text = "**** unknown field '" & me.FieldName & "' ***"
            MsgBox "Unknown field '" & me.FieldName & "'.",,"Class.MailMerge:ProcessPlaceholder()"
        Else
            Me.Text = "**** unknown command '" & UCase(me.Command) & "' ***"
            MsgBox "Unknown command '" & UCase(me.Command) & "'.",,"Class.MailMerge:ProcessPlaceholder()"
        End If
        Resume exitSub
    End Sub
    
    ' *** Private supporting functions/subs
    
    Private Function GetNABField(user As String, fieldname As String) As String
        Dim session As New NotesSession
        Dim curdb As NotesDatabase    
        Dim nabdb As NotesDatabase
        Dim view As NotesView
        Dim col As NotesDocumentCollection
        Dim userdoc As NotesDocument
        
        Set curdb = session.CurrentDatabase
        Set nabdb = New NotesDatabase(curdb.Server, "names.nsf")
        Set view = nabdb.GetView("PeopleByFirstname")
        Set col = view.GetAllDocumentsByKey(user)
        If col Is Nothing Then
            GetNABField = ""
            Exit Function
        End If
        Set userdoc = col.GetFirstDocument
        If userdoc Is Nothing Then
            GetNABField = ""
            Exit Function
        End If
        GetNABField = userdoc.GetItemValue(fieldname)(0)
    End Function
    
    
    
End Class


Class MailMergeObject
    Public templatedoc As NotesDocument    ' Where to get layout from
    Public sourcefield As NotesRichTextItem    
    Public targetfield As NotesRichTextItem    ' Where to put the merged text
    Public placeholder List As PlaceHolderData
    Public selected List As String 
    Private sourcedoc As NotesDocument     ' The document containing data to be merged
    Private lossnotice As NotesDocument        ' The loss notice for the processed document
    
    Public Sub New()
        
    End Sub
    
    Public Sub SetSourceDoc(doc As NotesDocument)
        Dim session As New NotesSession
        Dim db As NotesDatabase
        Dim view As NotesView 
        Set sourcedoc = doc                
        Set db = session.CurrentDatabase 
        Set view = db.GetView("(SysLookupLossNoticeByParentUNID)")
        Set lossnotice = view.GetDocumentByKey(doc.ParentUNID(0),True)
    End Sub
    
    Public Function LoadTemplate(doc As NotesDocument) As Integer
        Dim body As NotesRichTextItem                 ' Temporary copy of body field for this function
        Dim temp As String            
        Dim bodytext As String
        Dim startpos As Long
        Dim endpos As Long
        Set sourcefield = doc.GetFirstItem("Body")    ' Put template body field (rich text) into global object
        Set body = sourcefield                        ' Put rich text into temporary body object
        bodytext = body.GetUnformattedText()
        startpos = InStr(bodytext,"{")
        Do While startpos > 0
            endpos = InStr(startpos,bodytext,"}")
            If endpos>0 Then
                temp = Mid$(bodytext,startpos,endpos-startpos+1)
                Set placeholder(temp & "~" & startpos) = New PlaceHolderData(temp)    ' Add to list of placeholder objects        
            End If
            startpos = InStr(endpos,bodytext,"{")
        Loop
    End Function
    
    Public Function MergedRichText() As NotesRichTextItem
        Dim body As NotesRichTextItem        
        Dim range As NotesRichTextRange         
        Dim cnt As Integer
        Set body = sourcefield
        Set range = body.CreateRange 
        ForAll p In placeholder
            Call p.ProcessPlaceHolder(sourcedoc, lossnotice, me.selected)
            If p.text = "" Then
                p.text = " -- "
            End If
            cnt =  range.FindAndReplace(p.placeholderstring, p.text, 1+4+8+16)            
        End ForAll
        Call body.Compact 
        Call body.Update 
        Set targetfield = body
        Set MergedRichText = body
    End Function    
    
    Public Function Content() As NotesRichTextItem
        Set Content = targetfield
    End Function
    
End Class

Here is an example of how the functions in teh script library can be called. I have stripped some code out of of this example, in order to make it easier to see the actual functionality. There are a number of additional functions (logging the letters, stopping after creation so the user can edit the resulting letter, force a copy of the letter to be saved in the database, etc.

You can see the code to select recipients. The form letter template document also has a number of additional fields that I haven't mentioned, where the creator of the template can decide if a particular recipient (e.g. the insured or the agency that wrote the policy) should be forced in, or if the user should be able to pick the recipient from all persons/companies associated with teh claim, or just the claimants (people having part of the claim, which excludes the agency but include anyone else involved in teh accident).