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.
- Back up the database : Always take an appropriate backup before performing bulk document updates.
- 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.
- 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.
- 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.
- 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.
- Review document save results : For production implementations, consider checking the return value of NotesDocument.Save and recording failures with document identifiers.
- 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.
- 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.