NotesLog: Production Logging for LotusScript Agents

Your scheduled agent runs every night, and occasionally something goes wrong — but you have no idea until a user complains. Print statements? Visible in the Designer debug console, silent on a server. There’s no log, no trace, no way to diagnose after the fact.

NotesLog is Domino’s built-in logging class. A few lines of code and your agent records its actions and errors to the agent log, a dedicated NSF, a disk file, or an email sent when the agent finishes. This article covers the full class.

TL;DR

• Create with New NotesLog("programName") — the name appears in log entries
• Four Open methods: OpenAgentLog (writes to the agent’s own log), OpenFileLog (disk file, client only), OpenMailLog (emails log on Close), OpenNotesLog (writes to an NSF)
• OpenAgentLog is the right choice for most production agents — visible in Designer Agent properties and Admin Client
• LogAction(msg) for regular events; LogError(errNum, errMsg) for errors
• NumActions / NumErrors: read-only counters
• Close() finalises the log and sends the email (for OpenMailLog)
• OverwriteFile: True overwrites the log file; False (default) appends

Creating a NotesLog

' Create the log object with a program name
Dim log As New NotesLog("OrderProcessor")

' Open the agent log (most common choice)
Call log.OpenAgentLog()

After creating the object, you must call one Open method before logging anything. Calling LogAction without opening first throws an error.

The four Open methods

1. OpenAgentLog — write to the agent’s own log (recommended)

Call log.OpenAgentLog()

Records to the agent design element’s log document — viewable in Domino Designer (Agent properties) and in Admin Client. The standard choice for production agents.

2. OpenNotesLog — write to a specified NSF

' Record logs to a centralized logs.nsf database
Call log.OpenNotesLog("LogServer/ACME", "logs.nsf")

Use when you want centralised log management. Build logs.nsf from the Domino Log (log.ntf) template.

3. OpenMailLog — email the log on Close

' When Close() is called, mail the full log to these addresses
Call log.OpenMailLog(Array("admin@acme.com"), "OrderProcessor Results")

Useful for “only notify if something went wrong” scenarios — pair with a check on log.NumErrors before deciding to send.

4. OpenFileLog — write to a disk file (client only)

' Only works in Notes Client agents — throws an error on server
log.OverwriteFile = True  ' overwrite on each run
Call log.OpenFileLog("C:\Logs\order_processor.log")

⚠️ OpenFileLog cannot be used in server agents — it throws an error.

Recording actions and errors

' Log a regular action
Call log.LogAction("Starting order batch")
Call log.LogAction("Processed order #" & orderNum)

' Log an error (typically inside On Error handlers)
On Error GoTo ErrHandler
' ... code that might fail ...
Exit Sub

ErrHandler:
    Call log.LogError(Err, Error())
    Resume Next

LogAction message length has no strict limit, but very long messages may be truncated in the agent log UI.

NumActions / NumErrors — post-run counters

' Report at the end
Print "Logged " & log.NumActions & " actions"
Print "Logged " & log.NumErrors & " errors"

' Conditional alerting based on error count
If log.NumErrors > 0 Then
    ' Send an alert or escalate
End If

Reusable production agent template

Sub Initialize
    Dim log As New NotesLog("OrderProcessor")
    Call log.OpenAgentLog()
    Call log.LogAction("=== Run started ===")

    Dim session As New NotesSession
    Dim db As NotesDatabase
    Set db = session.CurrentDatabase

    On Error GoTo ErrHandler

    ' Main logic
    Dim docs As NotesDocumentCollection
    Set docs = db.Search("Type = ""Order"" & Status = ""New""", Nothing, 0)
    Call log.LogAction("Found " & docs.Count & " orders to process")

    Dim doc As NotesDocument
    Set doc = docs.GetFirstDocument()
    Dim processed As Integer
    processed = 0

    Do Until doc Is Nothing
        On Error GoTo DocErrHandler
        doc.ReplaceItemValue "Status", "Processed"
        Call doc.Save(True, False)
        processed = processed + 1
        On Error GoTo ErrHandler

        Set doc = docs.GetNextDocument(doc)
    Loop

    Call log.LogAction("Successfully processed " & processed & " orders")
    GoTo Done

DocErrHandler:
    Call log.LogError(Err, "Error processing document: " & Error())
    Resume Next

ErrHandler:
    Call log.LogError(Err, Error())

Done:
    Call log.LogAction("=== Run finished (" & log.NumErrors & " errors) ===")
    Call log.Close()
End Sub

LogErrors / LogActions — toggle logging by type

' Log only errors, skip action entries
log.LogActions = False
log.LogErrors = True

Both default to True. In high-frequency agents where action volume would clutter the log, disable LogActions and keep only errors (see the LogError method docs).

What about Java and SSJS?

← Back to all posts