—

作者:

分類: 8.5.3, AI, AI 自動化, domino, hcl, hcl domino, Notes, 系統管理

Lotus Domino 為企業電子郵件與工作流程管理的核心平台，長期以來提供多種自動化代理（agent）能在郵件送達時間前或後執行自訂邏輯。
在日常的桌面與伺服器維運工作中，最常遇見的是「Before new mail arrives（郵件到達前）」與「After new mail arrived（郵件到達後）」兩類代理。雖然兩者都可針對即將到達的郵件做處理，但它們的觸發時序、可存取資料、影響範圍各有差異，錯誤配置往往導致遺失或重複處理。本文將以實務案例為例，詳細拆解兩種代理的執行流程、特色功能、常見錯誤與最佳實踐。

一句話快速對照

Before new mail arrives「新郵件到達前」：在郵件實際寫入資料庫前執行，能變更郵件內容、標籤或直接拋棄。
After new mail arrived「新郵件到達後」：在郵件寫入資料庫後執行，主要用於資料索引、通知或後續工作流程。

實際部署時，使用者常把兩者混用，尤其在「臨時拒收」或「自動歸檔」的需求上。以下分別說明兩類代理的執行環境與常見操作。

運行代理類型的任務

「新郵件到達前」代理由路由器伺服器任務運行，而非代理管理員 (AMGR) 伺服器任務運行。當代理程式在新郵件到達前觸發時，路由器任務會在將郵件傳送給收件者之前執行該代理程式。代理幾乎在收到新郵件後立即運行。

「新郵件到達後」代理程式由代理程式管理員 (AMGR) 伺服器任務執行。此類代理程式不會在郵件投遞後立即運作。相反，代理程式會在投遞後從「已觸發」狀態切換到「已調度」狀態。之後，它會進入待處理佇列並運行。從「已觸發」到「已運行」狀態的切換可能需要幾分鐘，也可能需要相當長的時間，這取決於待處理佇列中已有多少代理程式在其前面調度運行。

「Before new mail arrives」：郵件進來前的篩選與處理

此類代理執行於郵件尚未寫入「Inbox」或任何資料庫表之前。因在資料寫入前，可對「NotesItem」做完整修改，甚至決定是否放行郵件。

時間效率：因不必先寫入磁碟，執行速度較快，對高流量環境更友善。
修改能力：可修改郵件聲明、移除附件、改變主旨或加上自訂欄位。
不可讀取對象：此時尚未寫入資料庫，代理只能存取「临时記錄（Transient Document）」與「Environment」變數，無法直接取得收件者信箱資料。
指向其他代理：若需複雜處理，可在此代理內部呼叫另一個「After new mail」代理，例如用 NotesSession 產生文檔並提交。

以下為一簡單範例：將寄件者地址為 spam@example.com 的郵件直接標記為垃圾郵件並停止接收。

Sub mailFilter
  Dim session As NotesSession, mail As NotesDocument
  Set session = New NotesSession
  Set mail = session.DocumentContext

  If mail.SenderEmail Is Nothing Then Exit Sub
  If mail.SenderEmail(0) = "spam@example.com" Then
    mail.RemoveItem "Body"   '移除內容
    mail.Form = "junkmail"   '自訂表單
    mail.Save True, False    '立即寫入，停止後續處理
  End If
End Sub

「After new mail arrived」：郵件寫入後的附加流程

此類代理於郵件已成功寫入資料庫後觸發，整個郵件結構已完整形成。

完整存取：可讀取及修改所有文件項目、附件、收件者清單，並可寫入任何「Queue document」或「Replication document」。
延遲隊列：可加入到資料庫的“Delivery Queue”或“Deliver Now Queue”中，配合延遲發送或批次處理。
觸發通知：可快速送出自訂通知郵件或觸發 Webhook、REST API 呼叫。
限度挑戰：代理執行完畢前的所有改動都會同步寫入資料庫，若發生例外，可能留下不一致的紀錄。

範例：在收到郵件後自動將其存檔至「Archive」資料庫，並發送確認郵件給寄件者。

Sub mailArchiver
  Dim session As NotesSession, mail As NotesDocument
  Dim db As NotesDatabase, arch As NotesDatabase
  Dim copyDoc As NotesDocument

  Set session = New NotesSession
  Set mail = session.DocumentContext
  Set db = session.CurrentDatabase
  Set arch = db.GetReplicaId("ARCHIVE_DB_REPLICA_ID")  '替換為實際複本 ID

  '複製文件到存檔資料庫
  Set copyDoc = mail.Copy
  Call copyDoc.Save(True, False, "Archive")

  '發送確認郵件
  Dim reply As NotesDocument
  Set reply = db.CreateDocument
  reply.Form = "Memo"
  reply.Subject = "已收到您的訊息"
  reply.SendTo = mail.SenderEmail(0)
  Call reply.Send(False)
End Sub

典型錯誤與排查要點

在「Before」代理中作為「After」代理發起重複處理：若「Before」代理最後不直接寫入，而是交給「After」代理重複執行，會導致重複觸發或資料寫入錯誤。要使用 Session.CreateDocument 並直接 Save。
郵件內容未即時更新：「After」代理若在處理期間修改原始文件，必須再呼叫 Save，否則前面的修改不會反映到資料庫。
錯誤捕捉不完整：多數代理使用 On Error GoTo handler；若未加完整的錯誤訊息或回傳，造成排錯困難。使用 NotesScreen 或 log 輸出。
權限問題：「Before」代理受限於伺服器或資料庫的設定，若要寫入資料庫必須確保執行代理的用戶有相應權限。
代理與 Document Context 同時變動：若同時呼叫多個代理變更同一封信件，可能導致鎖定或覆蓋。最佳做法是一次完成所有邏輯或使用分層代理。

注意事項

一個資料庫一次只能啟用一個「新郵件到達前」代理程式。（可以存在其他「新郵件到達前」代理，但必須停用。）

一個資料庫可以有多個「新郵件到達後」代理程式。但請注意，如果太多資料庫同時啟用了多個「新郵件到達後」代理，可能會影響伺服器效能。

關於“新郵件到達後”的間隔和延遲預設值的詳細信息

Notes.ini 檔案參數可讓您控制代理程式的執行頻率（以分鐘為單位）。您可以降低這些參數的值（這將提高代理程式的執行頻率）；但是，降低參數值可能會影響伺服器效能。如果效能受到影響，請嘗試使用更高的參數值，以在效能和代理延遲時間之間找到平衡點。

AMgr_NewMailAgentMinInterval
- 此設定指定相同郵件觸發代理兩次執行之間的最短間隔時間（以分鐘為單位）。預設值為 0（執行之間無間隔）。與 AMgr_DocUpdateAgentMinInterval 類似，輸入間隔時間可能會導致代理程式運行頻率降低。
AMgr_NewMailEventDelay
- 此設定指定代理管理員在收到新郵件後，延遲多久（以分鐘為單位）才會安排新的郵件觸發代理。預設值為 1 分鐘。與 AMgr_DocUpdateEventDelay 類似，此延遲時間可確保代理程式的運作頻率不超過指定的時間間隔。當代理執行時，也會處理該時間間隔內發生的所有其他事件（如有）。時間間隔越長，代理的運作頻率越低，從而減少對伺服器時間的需求。如果文件更新事件不頻繁，您可以縮短延遲時間，以確保代理在事件發生後儘快運作。

相關文件請參考原廠說明:
https://support.hcl-software.com/csm?id=kb_article&sysparm_article=KB0032961

🧠 本文由 DreamJ AI 自動生成系統撰寫，內容經 AI 模型審核與自動優化，
僅供技術參考與研究用途。