NotesDirectory + NotesDirectoryNavigator: Querying the Domino Directory from LotusScript

Your agent needs to look up a user’s mail server, check group membership, or verify that a Notes name exists. The instinct is db.GetView("($Users)") and scan — but that means opening names.nsf manually, managing view caching, and accounting for multiple directory sources (primary + extended + LDAP).

LotusScript’s NotesDirectory handles all that transparently. It’s a high-level directory query API available since Notes 7 — the server may have one directory or ten, and this class abstracts the structure away.

TL;DR

• NotesDirectory is the high-level directory query API — no need to open names.nsf yourself
• Entry point: session.GetDirectory(serverName) — empty string "" means local
• LookupNames(view, names, items) — specify a view, a batch of names, and which fields to fetch; results are cached in the object
• LookupAllNames — scans every name in a view
• GetMailInfo(name) — retrieves mail server and mail file path for a user in one call
• Walk results with NotesDirectoryNavigator — FindFirstName / FindNextName / GetFirstItemValue
• LimitMatches = True caps results at 50 (performance guard); SearchAllDirectories = True searches all configured directories

Getting a NotesDirectory object

Dim session As New NotesSession

' Query the local server's directory
Dim dir As NotesDirectory
Set dir = session.GetDirectory("")

' Query a specific server's directory
Set dir = session.GetDirectory("MailServer/ACME")

Print "Directory server: " & dir.Server

LookupNames — fetch specific fields for named entries

' Look up FullName, MailServer, MailFile for two people
Dim names(1) As String
names(0) = "John Smith"
names(1) = "Alice Chen"

Dim items(2) As String
items(0) = "FullName"
items(1) = "MailServer"
items(2) = "MailFile"

' LookupNames caches the results in the dir object
Call dir.LookupNames("($Users)", names, items)

' Build a navigator to walk the results
Dim nav As NotesDirectoryNavigator
Set nav = dir.CreateNavigator()

If nav.FindFirstName() Then
    Do
        Print "Name: " & nav.GetFirstItemValue()
        If nav.FindFirstItem("MailServer") Then
            Print "Mail server: " & nav.GetFirstItemValue()
        End If
        If nav.FindFirstItem("MailFile") Then
            Print "Mail file: " & nav.GetFirstItemValue()
        End If
    Loop While nav.FindNextName()
End If

GetMailInfo — fast mail routing lookup

Instead of a manual LookupNames, GetMailInfo retrieves a user’s mail configuration in one call:

Dim mailInfo As Variant
mailInfo = dir.GetMailInfo("John Smith")

' mailInfo(0) = MailServer (e.g. "MailServer/ACME")
' mailInfo(1) = MailFile   (e.g. "mail/jsmith.nsf")
' mailInfo(2) = MailDomain
' mailInfo(3) = MailSystem (constant: MAIL_NOTES_TYPE = 1)

If Not IsNull(mailInfo) Then
    Print "Mail server: " & mailInfo(0)
    Print "Mail file: " & mailInfo(1)
End If

This is the most practical method in day-to-day use — any time you need to open a user’s mail.nsf, auto-forward, or look up routing info, GetMailInfo saves the manual lookup.

LookupAllNames — scan a whole view

Dim items(0) As String
items(0) = "FullName"

' Scan every entry in $Users
Call dir.LookupAllNames("($Users)", items)

Dim nav As NotesDirectoryNavigator
Set nav = dir.CreateNavigator()

Dim count As Integer
count = 0
If nav.FindFirstName() Then
    Do
        count = count + 1
    Loop While nav.FindNextName()
End If
Print "Directory has " & count & " users"

Note: when LimitMatches = True, only the first 50 results are returned. Set dir.LimitMatches = False before a full scan, but be aware of the performance cost on large directories.

Walking results with NotesDirectoryNavigator

NotesDirectoryNavigator is the cursor for walking the cached LookupNames results:

Two key properties

' Search all configured directories (primary + extended + LDAP)
dir.SearchAllDirectories = True

' Cap LookupNames results at 50 per call (default True)
' Set to False for full scans — but watch the performance impact
dir.LimitMatches = False

SearchAllDirectories = False (default) queries only the primary Domino Directory — faster. True includes all configured auxiliary directories.

What about Java and SSJS?

← Back to all posts