Extract Attachment Names from Specific Rich Text Fields and Update Existing Documents Using LotusScript

1. Introduction

HCL Notes/Domino applications frequently use Rich Text fields to store information such as documents, reports, images, and other file attachments.

A single Notes document can contain multiple Rich Text fields, with each field storing multiple attachments.

In certain application scenarios, users need to identify the attachment filenames associated with a particular Rich Text field and display those filenames separately in a Notes view.

However, retrieving attachment filenames at the document level does not necessarily provide the field-level separation required for this purpose.

This article demonstrates how to use LotusScript to:

  • Retrieve attachment filenames from individual Rich Text fields.
  • Store the extracted filenames in corresponding text fields.
  • Display attachment filenames in separate columns in a Notes view.
  • Automatically update the attachment-name fields when new or existing documents are saved through the form.
  • Process existing documents in bulk using a LotusScript agent configured to run on selected documents.

The approach provides a way to handle both newly created documents and existing documents without requiring users to manually open and save every existing document.

2. Understanding the Requirement

Consider a Notes application containing a form named Attachment.

The form contains three Rich Text fields: RT_A, RT_B, RT_C

Each Rich Text field can contain multiple attachments.

For example, a document might contain the following attachments:

Rich Text field Attachment filenames
RT_A A1.txt; A2.txt
RT_B B1.txt; B2.txt
RT_C C1.txt
The requirement is to display the attachment filenames separately in a Notes view. Expected view output
RT_A Attachments RT_B Attachments RT_C Attachments
A1.txt; A2.txt B1.txt; B2.txt C1.txt
2.1 Why is @AttachmentNamesAttachmentNames not sufficient?@AttachmentNames

The @AttachmentNames formula retrieves attachment filenames associated with a document.

However, when a document contains multiple Rich Text fields, it does not provide the field-level association required to identify which Rich Text field contains each attachment.

For example, if a document contains attachments in RT_A, RT_B, and RT_C, the formula returns the attachment filenames without identifying which Rich Text field contains each @AttachmentNamesttachment.

Therefore, using @AttachmentNames directly in a view column does not meet the requirement of displaying attachment filenames separately for each Rich Text field.

Proposed approach : Instead of retrieving filenames at the document level, process each Rich Text field individually using LotusScript. Store the extracted filenames in separate text fields and use those fields as the source for the Notes view columns.

3. Solution Design

To implement this approach, create a corresponding text field for each Rich Text field.

The sample form uses the following field structure:

Field type Field name Purpose
Rich Text RT_A Stores attachments for category A
Rich Text RT_B Stores attachments for category B
Rich Text RT_C Stores attachments for category C
Text RT_A_Attachments Stores filenames from RT_A
Text RT_B_Attachments Stores filenames from RT_B
Text RT_C_Attachments Stores filenames from RT_C

The attachment-name fields should be created as Text fields on the form. They will contain the extracted filenames as a semicolon-separated string.

For example:

RT_A_Attachments = A1.txt; A2.txt

RT_B_Attachments = B1.txt; B2.txt

RT_C_Attachments = C1.txt

These text fields can then be referenced directly from Notes view column formulas.

The solution has two processing paths.

Path 1: New and subsequently saved documents

  • User creates or edits a document.
  • The form’s QuerySave event executes.
  • The LotusScript attachment extraction function processes each Rich Text field.
  • The corresponding attachment-name text fields are updated.
  • The document continues through the normal save operation.

Path 2: Existing documents

  • User selects documents from a Notes view.
  • User runs the LotusScript agent from the Actions menu.
  • The agent retrieves the selected documents.
  • The agent extracts attachment filenames from each Rich Text field.
  • The corresponding text fields are updated.
  • The backend documents are saved.
  • The Notes view displays the updated attachment filenames.

4. Implementing the LotusScript Attachment Extraction Function

The first step is to create a reusable LotusScript function that retrieves attachment filenames from a specified Rich Text field.

4.1 LotusScript used

The implementation uses the following Notes classes, properties, and methods:

LotusScript Class Purpose
NotesDocument Represents the Notes document being processed
NotesRichTextItem Represents an individual Rich Text field
NotesEmbeddedObject Represents an embedded object, including a file attachment
GetFirstItem Retrieves the specified item from the document
EmbeddedObjects Provides access to embedded objects associated with the Rich Text item
Type Identifies the type of embedded object
Name Retrieves the attachment filename

The EMBED_ATTACHMENT constant is used to identify file attachments.

4.2 LotusScript function

Add the following function under : Form → Globals → Declarations

Sample LotusScript code

Function GetAttachmentNamesRTF(doc As NotesDocument, rtfFieldName As String) As String

Dim rtitem As NotesRichTextItem

Dim objects As Variant

Dim obj As NotesEmbeddedObject

Dim i As Integer

Dim result As String

Set rtitem = doc.GetFirstItem(rtfFieldName)

If rtitem Is Nothing Then

GetAttachmentNamesRTF = ""

Exit Function

End If

objects = rtitem.EmbeddedObjects

If Isarray(objects) Then

For i = Lbound(objects) To Ubound(objects)

    Set obj = objects(i)

     If obj.Type = EMBED_ATTACHMENT Then

        If result = "" Then

            result = obj.Name

        Else

            result = result & "; " & obj.Name

        End If

    End If

Next

End If

GetAttachmentNamesRTF = result

End Function

4.3 Understanding the function

Let’s examine the important sections.

Step 1: Retrieve the specified Rich Text field

Set rtitem = doc.GetFirstItem(rtfFieldName)

GetFirstItem retrieves the item whose name is passed through the rtfFieldName argument.

For example: GetAttachmentNamesRTF(doc, “RT_A”)

This retrieves the Rich Text item named RT_A.

Step 2: Check whether the Rich Text field exists

If rtitem Is Nothing Then

GetAttachmentNamesRTF = ""

Exit Function

End If

If the specified Rich Text field does not exist, the function returns an empty string.

This prevents further processing when the requested item is unavailable.

Step 3: Retrieve the embedded objects

objects = rtitem.EmbeddedObjects

The EmbeddedObjects property retrieves the embedded objects associated with the specified Rich Text item.

Step 4: Identify file attachments

If Isarray(objects) Then

For i = Lbound(objects) To Ubound(objects)

    Set obj = objects(i)

     If obj.Type = EMBED_ATTACHMENT Then

The code iterates through the returned objects and checks whether each object is a file attachment.

Objects that are not identified as EMBED_ATTACHMENT are excluded.

Step 5: Retrieve and concatenate attachment filenames

If result = “” Then

result = obj.Name

Else

result = result & "; " & obj.Name

End If

The Name property retrieves the filename of the attachment.

If multiple attachments are present, their names are concatenated using a semicolon separator.

Step 6: Return the result

GetAttachmentNamesRTF = result

The function returns the extracted filenames to the calling procedure.

The same function can be reused for different Rich Text fields simply by passing the appropriate field name.

5. Automatically Updating Attachment Names When Saving a Document

After creating the extraction function, the next step is to invoke it whenever a document is saved through the form.

This can be implemented in the form’s QuerySave event.

5.1 QuerySave implementation

Open the form and navigate to:

Form → Events → QuerySave

Add the following LotusScript code:

Sub Querysave(Source As Notesuidocument, Continue As Variant)

Dim doc As NotesDocument

Set doc = Source.Document

doc.RT_A_Attachments = GetAttachmentNamesRTF(doc, “RT_A”)

doc.RT_B_Attachments = GetAttachmentNamesRTF(doc, “RT_B”)

doc.RT_C_Attachments = GetAttachmentNamesRTF(doc, “RT_C”)

End Sub

5.2 How does this work?

When a user saves a document:

The QuerySave event is executed.

Source.Document provides access to the backend Notes document.

The extraction function is called separately for RT_A, RT_B, and RT_C.

The extracted filenames are assigned to their corresponding attachment-name fields.

The document continues through the normal save operation.

For example: doc.RT_A_Attachments = GetAttachmentNamesRTF(doc, “RT_A”)

This retrieves the attachment filenames from RT_A and updates RT_A_Attachments.

The same operation is performed for the other Rich Text fields.

Result: Whenever a document is saved through this form, the corresponding attachment-name fields are populated based on the attachments currently stored in each Rich Text field.

This implementation handles new documents and subsequently edited documents. However, it does not automatically update historical documents that have not been saved through the form since the implementation was introduced.

6. Creating a Notes View to Display Attachment Names

Once the attachment-name fields are populated, they can be displayed in separate Notes view columns.

6.1 Create a view

Create a new view named: Attachment

Configure the view selection formula according to the form names used in the application.

For example: SELECT ((Form = “Attachment”) | (Form = “frm_attachment”))

The example includes two form names. Modify the selection formula to match the actual form names in your database.

6.2 Configure the view columns

Create three columns and configure their formulas as follows:

Column title Column formula
Attachment1 RT_A_Attachments
Attachment2 RT_B_Attachments
Attachment3 RT_C_Attachments

6.3 Expected result

Open the Notes client and preview the newly created view.

For a document containing the following attachments:

  • RT_A: A1.txt, A2.txt
  • RT_B: B1.txt, B2.txt
  • RT_C: C1.txt

The view displays:

RT_A Attachments RT_B Attachments RT_C Attachments
A1.txt; A2.txt B1.txt; B2.txt C1.txt

This makes it possible to identify the attachment filenames associated with each Rich Text field separately.

At this stage, the solution works for documents saved through the form.

But what happens when the application already contains thousands of existing documents?

That is where a bulk-update agent becomes useful.

7. Updating Existing Documents Using a LotusScript Agent

In an existing application, adding the extraction logic to the form’s QuerySave event does not automatically populate the attachment-name fields for historical documents.

For example, consider an application that already contains more than 5,000 documents.

Manually opening each document, entering edit mode, updating it, and saving it would require considerable effort.

A LotusScript agent can automate the update process by processing selected documents directly.

The proposed approach is to:

  • Select documents from a Notes view.
  • Run a LotusScript agent from the Actions menu.
  • Retrieve the selected documents.
  • Extract attachment filenames from each Rich Text field.
  • Update the corresponding text fields.
  • Save the documents using NotesDocument.Save.

7.1 Create the LotusScript agent

Create a new agent with the following configuration:

Property Configuration
Agent name Update Attachment Names
Code LotusScript
Target Selected documents
Trigger Action menu / manual execution

The agent must be configured to run on selected documents.

7.2 LotusScript agent code

Sample LotusScript code

Option Public

Option Declare

Sub Initialize

Dim session As New NotesSession

Dim db As NotesDatabase

Dim dc As NotesDocumentCollection

Dim doc As NotesDocument

Dim count As Integer

Set db = session.CurrentDatabase

Set dc = db.UnprocessedDocuments

Set doc = dc.GetFirstDocument()

Do Until doc Is Nothing

Call doc.ReplaceItemValue("RT_A_Attachments",GetAttachmentNamesRTF(doc, "RT_A"))

Call doc.ReplaceItemValue("RT_B_Attachments",GetAttachmentNamesRTF(doc, "RT_B"))

Call doc.ReplaceItemValue("RT_C_Attachments",GetAttachmentNamesRTF(doc, "RT_C"))

Call doc.Save(True, False)

 count = count + 1

Set doc = dc.GetNextDocument(doc)

Loop

MsgBox CStr(count) & " document(s) processed."

End Sub

Function GetAttachmentNamesRTF(doc As NotesDocument,rtfFieldName As String) As String

Dim rtitem As NotesRichTextItem

Dim objects As Variant

Dim obj As NotesEmbeddedObject

Dim i As Integer

Dim result As String

Set rtitem = doc.GetFirstItem(rtfFieldName)

If rtitem Is Nothing Then

GetAttachmentNamesRTF = ""

Exit Function

End If

objects = rtitem.EmbeddedObjects

If IsArray(objects) Then

For i = LBound(objects) To UBound(objects)

    Set obj = objects(i)

     If obj.Type = EMBED_ATTACHMENT Then

        If result = "" Then

            result = obj.Name

        Else

            result = result & "; " & obj.Name

        End If

    End If

 Next

End If

GetAttachmentNamesRTF = result

End Function

7.3 Understanding the agent implementation

Step 1: Initialize the Notes session and database

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

The current Notes session and database are retrieved.

Step 2: Retrieve the selected documents

Dim dc As NotesDocumentCollection

Set dc = db.UnprocessedDocuments

UnprocessedDocuments provides the document collection supplied to an agent configured to run on selected documents.

This allows the agent to process the documents selected by the user from the Notes view.

Step 3: Retrieve the first document

Set doc = dc.GetFirstDocument()

The first document in the selected collection is retrieved.

Step 4: Process the documents

Do Until doc Is Nothing

The agent iterates through the selected documents until there are no more documents to process.

For each document, the attachment extraction function is called separately for all three Rich Text fields.

Step 5: Update the corresponding text fields

Call doc.ReplaceItemValue(“RT_A_Attachments”,GetAttachmentNamesRTF(doc, “RT_A”))

This retrieves attachment filenames from RT_A and updates RT_A_Attachments.

The same operation is performed for RT_B and RT_C.

Step 6: Save the document

Call doc.Save(True, False)

The updated backend document is saved using NotesDocument.Save.

This approach does not require the agent to open each document through the Notes user interface.

Step 7: Move to the next document

Set doc = dc.GetNextDocument(doc)

The agent retrieves the next document from the selected collection and continues processing.

Step 8: Display the processing count

MsgBox CStr(count) & " document(s) processed."

After processing the selected documents, a message displays the number of documents processed.

Note: The supplied sample counts documents as processed; it does not check the Boolean result returned by NotesDocument.Save. Therefore, the count represents the number of documents attempted, not necessarily the number successfully saved. For production implementations, consider adding explicit save-result checking, error handling, and logging.

7.4 Executing the agent from a Notes view

  • Once the agent has been created:
  • Open the Notes view containing the existing documents.
  • Select a small number of documents that need to be updated.
  • Navigate to the Actions menu.
  • Select the Update Attachment Names agent.
  • Allow the agent to process the selected documents.
  • Verify the updated attachment-name fields.
  • Refresh the view and check the corresponding columns.

The agent retrieves the selected documents, extracts the filenames from their individual Rich Text fields, updates the text fields, and saves the documents.

This eliminates the need to manually open, update, and save every existing document.

8. Why Use a Backend Agent Instead of Automating the Notes UI?

One alternative is to automate the Edit → Update → Save workflow by programmatically opening each document using NotesUIDocument.

However, UI-based processing introduces additional complexity when many documents need to be updated.

During our investigation, we also evaluated a UI-based approach using NotesUIDocument.

Although the QuerySave event was triggered, the updated values were not reliably persisted in our test scenario after the programmatically opened document was closed.

Therefore, we did not recommend this UI-based approach for bulk processing.

Instead, we validated a backend LotusScript agent that directly processes the selected NotesDocument objects.

The backend approach offers the following advantages:

  • No requirement to open and close each document through the Notes UI.
  • Direct access to the selected backend documents.
  • Reuse of the same attachment extraction logic.
  • Ability to process selected documents in manageable batches.
  • Less manual effort when updating historical records.

9. Testing and Validation

The proposed implementation was evaluated in a controlled test environment to verify the attachment extraction logic, view display, and bulk-update functionality.

The following scenarios were covered:

Test scenario Expected result Outcome
Multiple attachments in RT_A Filenames retrieved separately Successful
Multiple attachments in RT_B Filenames retrieved separately Successful
Multiple attachments in RT_C Filenames retrieved separately Successful
Display filenames in separate view columns Correct field-wise display Successful
Update one existing document using the agent Corresponding text fields updated Successful
Update three existing documents using the agent Corresponding text fields updated Successful
Process selected documents without UI-based editing Backend document updates saved Successful

The tests demonstrated that the LotusScript function could retrieve attachment filenames from individual Rich Text fields and that the backend agent could update the corresponding text fields in selected existing documents.

Note: The validation was limited to the scenarios described above. The implementation was not tested against the entire existing document population or all possible attachment-storage scenarios.

10. Important Considerations Before Production Deployment

Although the implementation provides a practical solution, a few considerations should be addressed before using it in a production database.

  1. Back up the database : Always take an appropriate backup before performing bulk document updates.
  2. Start with a small selection : Initially, select one or two documents and verify the results. Increase the batch size only after confirming that the implementation works as expected.
  3. Validate attachment types : The sample specifically processes objects identified as EMBED_ATTACHMENT. Other embedded object types or specialized attachment storage patterns may require separate handling.
  4. Verify field names : Ensure that the Rich Text fields and corresponding text fields exist in the application and that the field names used in the LotusScript code match the actual design.
  5. Review agent execution settings : Confirm that the agent is configured to run on selected documents and that its execution context and access rights are appropriate.
  6. Review document save results : For production implementations, consider checking the return value of NotesDocument.Save and recording failures with document identifiers.
  7. Process documents in batches : For databases containing thousands of records, process a manageable number of documents at a time rather than starting with the entire database.
  8. Validate the view after processing : Refresh the Notes view and confirm that the attachment filenames are displayed in their corresponding columns.

11. Disclaimer and Backup Recommendation

The sample LotusScript agent provided in this article is a reference implementation based on the described requirement. Developers should review and customize the code according to their application’s design and business requirements.

Before running the agent or performing bulk document updates:

  • Consult your application development team to review and validate the implementation.
  • Take an appropriate database backup before making changes.
  • Test the agent on a small selection of documents in a non-production environment.
  • Ensure that a recovery or rollback approach is available in case any unexpected issues occur.

The backup is important because the agent directly updates and saves existing backend documents.

12. Conclusion

Retrieving attachment filenames from individual Rich Text fields can be challenging when a Notes document contains multiple Rich Text items.

By using the NotesRichTextItem.EmbeddedObjects property and a reusable LotusScript function, it is possible to extract attachment filenames from a specific Rich Text field and store them in corresponding text fields.

A Notes view can then display those filenames separately, providing users with better visibility into the attachments stored within each field.

For newly created and subsequently saved documents, the form’s QuerySave event can maintain the attachment-name fields.

For existing documents, a LotusScript agent configured to run on selected documents can perform the required updates directly through backend document processing.

Together, these approaches provide a practical way to manage attachment-name information in HCL Notes/Domino applications while reducing manual effort.

1 Like