#Tutorial
Posts tagged #Tutorial · 68 posts
- Domino Web View Paging: Start Isn't a Row Number, It's a Hierarchical Coordinate
"I assumed Start=31 meant the 31st row. Then I was wrong." A debugging field report on the ?OpenView Start parameter in categorized classic views: a plain number jumps to the Nth top-level category, dotted values like 1.1.1.1.6 are hierarchical coordinates, the last segment clamps but middle segments don't, and you can't URL your way to the absolute last page. Plus three practical uses — an in-category serial, @DocNumber("") (with its must-be-alone landmine), and ReadViewEntries breadcrumbs.
2026.07.23 - Why Your Domino View Header Is Forever Off by One Column: Passthrough-HTML Black Magic
Inherit an old classic-web Domino view and you'll often find the column headers sitting one cell to the right of the data — and nobody knows why. A field report on the passthrough-HTML tricks hiding in twenty-year-old view designs: square-bracket HTML in column values and titles, spacer columns, per-row checkboxes, and the real culprit — an intentionally unclosed <input tag that swallows the </td><td> boundary and merges two columns into one cell, shifting every header after it.
2026.07.22 - When DQL Says "Domino Query execution error": A Diagnostic Ladder
A DQL query fails and you get "Domino Query execution error:" followed by a wall of text. A field report on reading that message: the number 4854 you'll find in Err is useless for diagnosis (every DQL failure returns it), and the answer is always in the detailed-reason line. Covers the four-segment message structure, a three-rung ladder (catalog / view-never-built / partial TIMEDATE), the design-catalog corruption that makes queries work intermittently, and the 0-docs-no-error checklist.
2026.07.21 - DQL View Date-Column Lookups: Three Ways a Type or Time Zone Silently Eats Your Results
"Converting the column to a date, some documents match and some don't — weird." A field report: a DQL view-column date query that returned inconsistent results turned out to have three independent causes. DQL never auto-converts types (so the column's output type must match your query term), the source field held mixed text/date values, and @dt without a time-zone offset is UTC — which corrupts boundary documents without changing the total count. Two verified fixes, tested 6/6.
2026.07.20 - NotesXSLTransformer: Transforming XML and DXL with XSLT in LotusScript
NotesXSLTransformer applies an XSLT stylesheet to XML or DXL and writes the transformed result — the last piece of Domino's XML toolkit alongside the DOM and SAX parsers. This article covers session.CreateXSLTransformer and its three sources, the stylesheet-must-be-a-stream rule, the pipelining model that chains DXL export → transform → import with no temp files, and the error handling that works through the Log property and On Error, not events.
2026.07.19 - NotesJSONNavigator: Native JSON Parsing in LotusScript, Without the String Surgery
Before Domino 10.0.1, parsing JSON in LotusScript meant Evaluate tricks or hand-rolled string surgery. NotesJSONNavigator replaced that with a real parser: session.CreateJSONNavigator gives you a typed tree you navigate with GetElementByName, GetNthElement, and JSON Pointer paths. This article covers the navigator, the element/object/array classes, the type constants, and the naming surprises (GetFirstElement not GetFirstItem; AppendElement takes value-then-name).
2026.07.18 - Managing the Full-Text Index from Code: CreateFTIndex, UpdateFTIndex, and the Local-vs-Server Split
FTSearch needs a full-text index to be fast — and to support wildcards and relevance ranking — and NotesDatabase can create, update, and remove one from LotusScript. The catch is a split almost nobody expects: CreateFTIndex / UpdateFTIndex / RemoveFTIndex work on LOCAL databases only, while FTIndexFrequency is server-only, and server indexes are actually managed by the Updall task (updall -X rebuilds, it doesn't create). This article covers the options bitmask, the create-vs-update distinction, and that split.
2026.07.17 - Document Locking in LotusScript: Lock, LockProvisional, and the Prerequisites Everyone Forgets
Domino can lock a document so two users don't edit it at once — Lock, LockProvisional, UnLock, and LockHolders on NotesDocument. But the methods raise an error unless locking is enabled on the database (IsDocumentLockingEnabled) and a master lock server is configured, persistent vs provisional locks depend on that server being reachable, and locks don't work in web apps at all. This article covers the API and every prerequisite.
2026.07.16 - NotesDocument.ComputeWithForm: Running Form Validation from Code — and Why It Won't Stop Your Save
ComputeWithForm runs a form's default-value, input-translation, and input-validation formulas against a back-end document — the programmatic equivalent of a user saving on the form. But three things surprise people: it returns a pass/fail flag it never enforces (it happily lets you Save an invalid document), input translation can rewrite your field values, and it silently falls back to the default form unless you pin the Form item.
2026.07.15 - Response Documents in LotusScript: MakeResponse, ParentDocumentUNID, and Walking the Thread
Domino's parent-child document hierarchy — main document, responses, responses-to-responses — is built and traversed with a handful of NotesDocument members. This article covers MakeResponse (and the Save you must call after it), ParentDocumentUNID for walking up to the parent, and the Responses property, whose one load-bearing limitation is that it returns only immediate children — so a full tree needs recursion.
2026.07.14 - NotesDateTime and Time Zones: GMTTime, ConvertToZone, and the Sign Convention That Trips Everyone
One NotesDateTime is a single instant you can read out three ways — as GMT, as the machine's local time, and as a converted zone. This article covers GMTTime vs LocalTime vs ZoneTime, the TimeZone integer's counter-intuitive Notes sign convention (positive means west of GMT), ConvertToZone and its DST gotcha, LSGMTTime for native date math, and why GMTTime is the only safe form to store and compare across machines.
2026.07.13 - Signing and Encrypting Documents in LotusScript: Sign, Encrypt, and the Save-Order Rule
Domino can sign a document to prove who wrote it and encrypt items so only key-holders can read them — both from LotusScript, and both with a gotcha. This article covers NotesDocument.Sign and the server-agent permission it needs, Encrypt with the mandatory flag-item / Encrypt / Save ordering, per-item opt-in encryption, and why EncryptOnSend is a completely separate thing from encrypting the stored copy.
2026.07.12 - Profile Documents: The Cached Settings Store in Domino, and Why the Cache Bites
A profile document is a hidden, view-invisible document keyed by name (and optionally user) — perfect for app configuration and per-user preferences, and fast because it's cached. This article covers GetProfileDocument, the IsProfile / NameOfProfile / Key properties, per-user profiles via the unique key, and the pitfall the caching creates: another process's write may not be visible to your already-open session, with no refresh API to force a re-read.
2026.07.11 - Readers and Authors Fields in Code: Document-Level Security You Set with a NotesItem Flag
Domino's document-level access control isn't a special API — it's an ordinary item with a flag. This article covers creating Readers and Authors fields in LotusScript via ReplaceItemValue plus NotesItem.IsReaders / IsAuthors, the security model (no Readers item = everyone; an item with Readers = only those listed), and the lock-out traps: leave yourself and your agents out of the list and you can hide a document from everyone, including the code that made it.
2026.07.10 - GetAllDocumentsByKey in Multi-Level Categorized Views: Why Your Count Is Silently Wrong
In a single-level categorized view, GetAllDocumentsByKey('Belgien', True) correctly returns the 2 documents under that category. But add a second level of categorization — Form then Country — and GetAllDocumentsByKey('Customer', True) returns 3, not all the documents. It stops at the first sub-category. This article documents the empirically verified trap and the workarounds.
2026.07.09 - NotesStream and Text Encoding: Charsets, the BOM, and the Byte-vs-Character Trap
NotesStream reads and writes files, but the moment your text isn't plain ASCII, three things bite: which charset you opened with, whether a byte-order mark got written, and the fact that Position is a byte offset with 'no special support for multi-byte characters.' This article covers Open's charset argument, the EOL constants, exactly when WriteText emits a BOM (UTF-16 yes, UTF-8 no), and why Bytes never equals Len().
2026.07.08 - Attachments in LotusScript: EmbedObject, NotesEmbeddedObject, and the GetAttachment Shortcut
Attaching a file, listing what's attached, extracting it to disk, and removing it — all from code. This article covers NotesRichTextItem.EmbedObject with the EMBED_ATTACHMENT constant, the NotesEmbeddedObject class, ExtractFile, and the two traps that catch people: NotesDocument.EmbeddedObjects does NOT return file attachments (use GetAttachment or the rich-text item), and ExtractFile errors on anything that isn't an attachment.
2026.07.07 - The XML Declaration, DTD Nodes, and SAX Errors in LotusScript
The rarely-seen tier of the Domino DOM — the XML declaration, DOCTYPE, processing instructions, notations, entities — plus NotesSAXException on the SAX side. This article covers what each node actually gives you (mostly: not much), the AddXMLDeclNode flag you must set to even see the declaration, and how NotesSAXException is the one place you get rich, line-and-column error data when parsing goes wrong.
2026.07.05 - The Content-Carrying DOM Nodes: TextNode, AttributeNode, Comment, CDATASection in LotusScript
Once you're walking a parsed DOM, the actual data lives in the content nodes — text, attributes, comments, CDATA. This article covers the inheritance (CharacterData is the base of Text/Comment/CDATA; CDATA derives from Text; AttributeNode stands apart), the CharacterData editing methods, and the single biggest gotcha: the LotusScript binding reads content through NodeValue — there is no W3C-style Data, Length, Name, or Value property.
2026.07.04 - Walking a Parsed XML DOM in LotusScript: DocumentNode, ElementNode, NodeList, NamedNodeMap
Once NotesDOMParser has parsed your XML, you navigate the result with a family of node classes. This article covers getting the root from domParser.Document, reaching the root element via DocumentElement, querying with GetElementsByTagName (which returns a NotesDOMNodeList), reading attributes through an element's NamedNodeMap, and the LotusScript-specific quirks: 1-based GetItem, no ChildNodes property (walk FirstChild/NextSibling), and no GetItemByName.
2026.07.03 - NotesRichTextDocLink & NotesRichTextSection: Doclinks and Collapsible Sections in Code
Two rich-text features you'd normally insert by hand in Designer — a doclink that jumps to a database, view, or document, and a collapsible section — are scriptable. But neither class is one you construct: you create the elements through NotesRichTextItem (AppendDocLink, BeginSection/EndSection) and read them back through NotesRichTextNavigator. This article covers that write-vs-read split, the doclink properties, the BeginSection/EndSection rule, and the gotchas.
2026.07.02 - NotesRichTextParagraphStyle, NotesRichTextTab & NotesColorObject: Laying Out Rich Text in Code
Building rich text from LotusScript isn't just appending strings — margins, alignment, line spacing, tab stops, and colour are separate objects you stamp on before the text. This article covers NotesRichTextParagraphStyle (the layout), NotesRichTextTab (tab stops, born read-only from the style), and NotesColorObject (colour maths), the twips measurement system, the append-style-before-text rule, and the non-obvious bit: NotesColorObject doesn't colour text directly — you derive a Domino colour value from it.
2026.07.01 - NotesInternational: Stop Hard-Coding Date Separators and Currency Symbols
NotesInternational is a read-only window onto the regional settings of whatever machine your code runs on — date order, separators, AM/PM strings, currency symbol and format, time zone, and the DST flag. This article covers getting it from session.International, the property groups worth knowing, a runnable example that detects the locale's date order, and the three traps: it reflects the host OS (not the end user), it's read-only, and its TimeZone sign convention is the classic counter-intuitive Notes one.
2026.06.30 - NotesAdministrationProcess: Filing AdminP Requests from LotusScript
Renaming a user, deleting one cleanly, recertifying, moving a mail file, changing an Internet password — these are AdminP jobs you'd normally click through in the Administration client. NotesAdministrationProcess files those same requests from code into admin4.nsf. This article covers session.CreateAdministrationProcess, the request methods and their note-ID return value, the certifier properties, and the three things that trip people up: it needs unrestricted rights, it's asynchronous, and '*' means 'no change'.
2026.06.29 - NotesTimer: Firing an Event Every Few Seconds in the Notes Client
Want to do something every few seconds on an open Notes client screen — auto-refresh a view, poll for new documents, update a status display? NotesTimer is exactly that: give it an interval in seconds at creation and it fires an Alarm event periodically. This article covers creating it, the Interval / Enabled / Comment properties, binding a handler with On Event, and the four limitations you must know: UI-only (not agents), declare it globally, the handler must finish within the interval, and it's enabled by default.
2026.06.28 - NotesViewColumn: Reading a View's Columns, Their Formulas, and Sorting in Code
You want to inventory a view — which columns it has, whether each is a field or a formula, what's sorted or categorized, what's hidden — without opening Designer. NotesViewColumn reads that from code. This article covers getting it from view.Columns, the Title / ItemName / Formula / Position / IsSorted / IsCategory / IsHidden / IsField / IsFormula properties, and how it lines up with the earlier NotesViewEntry's ColumnValues (the same Position index).
2026.06.26 - NotesRichTextTable: Dropping a Table into Rich Text from Code
You're assembling a rich text email or document in code with NotesRichTextItem and need a table to lay out a summary or report — NotesRichTextItem.AppendTable creates a NotesRichTextTable. This article covers creating one, RowCount / ColumnCount, AddRow / RemoveRow, SetColor / SetAlternateColor for striped rows, RightToLeft, and how to walk an existing table with NotesRichTextNavigator — plus a key limitation: you can't read a cell's contents unless you already know the rich text's exact structure.
2026.06.24 - NotesDXLImporter: Pushing DXL Back into Domino — Separate Strategies for Design, Documents, and ACL
After you export design or documents to DXL (Domino XML) with NotesDXLExporter, how do you push it back into a database? NotesDXLImporter is the reverse half. This article covers creating it, the three key import strategies (DesignImportOption / DocumentImportOption / ACLImportOption and their create / ignore / replace / update choices), the Import method and retrieving imported notes, and how it pairs with DXLExporter into a full DXL round-trip.
2026.06.23 - NotesViewEntry × NotesViewEntryCollection: Reading Every Row of a View Fast, Without Opening Documents
To read a few field values from every document in a view, many people loop the documents and GetItemValue each one — but that opens every document, and a few thousand rows is painfully slow. NotesViewEntry reads the view's already-computed ColumnValues without opening a document at all; NotesViewEntryCollection is the collection of those rows, skips category/total rows, and supports set operations and StampAll batch updates. This article covers the 'read the view fast' pair, why ColumnValues is the performance key, and an entry's identity and hierarchy properties.
2026.06.22 - The ODS Developers Rarely Notice: Domino's Database Format Versions, and What Actually Triggers an Upgrade
You write LotusScript / XPages all day and probably never think about a database's ODS (on-disk structure) version — until a feature like LargeSummary needs a certain ODS, or you move an old database between servers and aren't sure whether its ODS follows. This article covers the ODS-to-release mapping from a developer's angle, the most counterintuitive point (upgrading the server version does not upgrade the ODS), and exactly what triggers an ODS change and what governs it — then answers a concrete case: an R9 ODS51 database, new-copied from an R12 client to an R12 server, does its ODS change automatically?
2026.06.21 - 'Field is too large (32K)' Is Lying to You: The Real Wall Is Usually the 64K Summary Buffer
An XPages save failure: the message says '32K', but every field checks out under 32K (the biggest is 26K) and it still won't save. Because the number the error names is usually not your problem — the wall you actually hit is 'a document's combined summary data is capped at 64K'. This article builds the summary / non-summary mental model and the two size limits first, then explains why ODS and LargeSummary are two different things, then forks the fixes on one question: should this data be summary at all?
2026.06.21 - LotusScript's Evaluate: Running @Formula Straight from Code
Sometimes the perfect tool in your head is an @function — @Name, @Unique, @Explode, @DbLookup — but you're in LotusScript. Evaluate is the bridge: pass an @formula as a string, run it at runtime, get the result back. This article covers the two call forms (with and without a document context), the trap everyone hits (the return value is always an array), and which @functions aren't supported (the UI ones — @Command, @Prompt, @PickList, and friends).
2026.06.20 - NotesRichTextStyle: Setting Bold, Font Size, and Colour in Code (and STYLE_NO_CHANGE)
You're building rich text in code with NotesRichTextItem and want a span to be bold, larger, a different colour — that 'style' is NotesRichTextStyle. This article covers creating it, the Bold / Italic / FontSize / NotesColor properties, applying it with AppendStyle and SetStyle, and one crucial design point: a freshly created style has every property set to STYLE_NO_CHANGE, so you set only the ones you want to change and leave the rest alone.
2026.06.19 - NotesNewsletter: Turning a Pile of Documents into One Doclink Digest Email
You want a 'daily digest' or 'search-results notification' — take a set of documents matching some criteria, roll them into one email, and let each entry link back to its source document. That's exactly NotesNewsletter's job: it takes a NotesDocumentCollection and produces a doclink digest with FormatMsgWithDoclinks, or renders documents one by one with FormatDocument. This article covers creating it, the DoScore / DoSubject / SubjectItemName properties, the difference between the two Format methods, and the classic FTSearch-to-email example.
2026.06.18 - NotesDbDirectory: Enumerating Every Database on a Server
Want an agent that sweeps every NSF on a server and checks each database's ACL or size? That's NotesDbDirectory's job — don't confuse it with the earlier NotesDirectory (which looks up people and groups in the Domino Directory); both end in Directory but do completely different things. This article covers creating it with GetDbDirectory, walking databases with GetFirstDatabase / GetNextDatabase, the four file-type constants, Open / CreateDatabase / OpenDatabaseByReplicaID, and the trap that bites everyone: the NotesDatabase you get back is closed by default and must be Opened before use.
2026.06.14 - NotesAgent: Calling One Agent from Another (Run vs RunOnServer)
You have a heavy processing agent and want another agent — or a button — to fire it on demand, not on a schedule but straight from code. NotesAgent is the class for that: db.GetAgent() gets the agent, then Run or RunOnServer executes it. This article unpacks the crucial difference between the two (runs on the client vs on the server), how to pass a document to the called agent via noteID, the IsEnabled / Trigger / Target properties, and the four constraints: no recursion, no debugging, no user interaction, output goes only to the Domino log.
2026.06.12 - NotesRichTextNavigator × NotesRichTextRange: Traversing and Rewriting Rich Text in Code
You have 500 documents whose Body field needs every doclink counted, or one string replaced throughout — and just getting the field with NotesRichTextItem isn't enough. NotesRichTextNavigator walks rich text one element type at a time; NotesRichTextRange selects a span and then styles or removes it. This article unpacks the two Release-6 companions, the element-type constants, FindAndReplace's options and return value, and the rule that costs people hours: every navigation marker is invalidated after a FindAndReplace.
2026.06.11 - NotesUIWorkspace × NotesUIDocument: Front-End Automation in LotusScript
The classes covered so far — NotesDatabase, NotesDocument — are all back-end. But when you need to read the value a user typed but hasn't saved yet, pop a dialog to ask them something, or flip the open document into edit mode, you reach for the other half: NotesUIWorkspace and NotesUIDocument. This article unpacks the front-end pair, the crucial 'on-screen value vs back-end Document' distinction, FieldGetText/FieldSetText, the Prompt and PickList dialogs, and the rule that trips everyone: UI classes can't run in a background or scheduled agent.
2026.06.10 - NotesName: Stop String-Parsing Hierarchical Domino Names
Need to pull "John B Goode" out of CN=John B Goode/OU=Sales/O=Acme/C=US? Still doing it with Mid, InStr, or @Name? NotesName is Domino's built-in name-parsing class — one session.CreateName() call converts between canonical, abbreviated, common, and Internet (RFC 821/822) formats, and breaks a name into its O / OU / C / G / S components. This article covers every read-only property, the three-format conversion, how flat names and Internet names behave, and the easy-to-miss rule that an abbreviation is skipped when it would be ambiguous.
2026.06.09 - Geolocation on Nomad: NotesGPS, NotesGPSPosition, and NotesGPSCoordinates
Classic LotusScript has no location API — but an app running on HCL Nomad can read the user's latitude and longitude. NotesGPS is Domino's client-side geolocation class for Nomad: start from NotesSession.CreateGPS(), authorise with RequestAccess(), fetch a NotesGPSPosition with GetCurrentPosition(), then read Latitude / Longitude off its NotesGPSCoordinates. This article walks the three-class chain, annotates the official example line by line, and covers the gotchas — error 4508, empty Speed/Heading on the first iOS call, and HighAccuracy failing indoors.
2026.06.08 - NotesLog: Production Logging for LotusScript Agents
Print statements only appear in the Designer debug window — a scheduled agent running on the server produces no trace at all. NotesLog is Domino's built-in logging class: a few lines of code and your agent's actions and errors are recorded to the agent log, a specified NSF, a file, or an email that arrives when the agent finishes. This article covers the four Open methods (OpenAgentLog / OpenFileLog / OpenMailLog / OpenNotesLog), LogAction and LogError call shapes, the NumActions / NumErrors counters, OverwriteFile for file logs, and a reusable production agent logging template.
2026.06.07 - NotesReplication + NotesReplicationEntry: Managing Database Replication Settings with LotusScript
Every Domino NSF carries a replication configuration — the same Replication Info you see in the database properties dialog. LotusScript's NotesReplication class lets you read and write that configuration programmatically: pause and resume replication, adjust priority, set cutoff filters, clear replication history. NotesReplicationEntry manages per-server-pair selective replication rules. This article covers obtaining the object (db.ReplicationInfo), the IsDisabled / Priority / Abstract properties, ClearHistory for forcing a full resync, GetEntry for per-pair rules, and why Save is non-negotiable.
2026.06.06 - NotesDirectory + NotesDirectoryNavigator: Querying the Domino Directory from LotusScript
The Domino Directory is the source of truth for every user, group, and server in your Notes environment. LotusScript's NotesDirectory provides a high-level query API — no need to open names.nsf yourself and walk a view. This article covers obtaining the object via session.GetDirectory, LookupNames for targeted field lookups, LookupAllNames for full scans, GetMailInfo for retrieving mail server information, CreateNavigator for walking cached results with NotesDirectoryNavigator, and the SearchAllDirectories / LimitMatches properties that control performance and result count.
2026.06.05 - NotesMIMEEntity + NotesMIMEHeader: Parsing Email MIME Structure in LotusScript
Incoming Domino mail is a nested MIME tree — HTML body, plain-text fallback, attachments, and inline images each live in separate nodes. LotusScript uses NotesMIMEEntity for each node and NotesMIMEHeader for its header fields. This article covers the ConvertMIME=False prerequisite, identifying node types with ContentType/ContentSubType, walking the tree with GetFirstChildEntity and GetNextSibling, extracting body text with GetContentAsText, reading header values with GetNthHeader/GetSomeHeaders, building a MIME message from scratch with CreateMIMEEntity, and a practical pattern for distinguishing attachments from body content.
2026.06.04 - NotesCalendar: Reading and Writing Domino Calendar Data with LotusScript
Domino calendar data isn't stored in ordinary documents — it lives in mail.nsf in iCalendar (RFC 5545) format, accessible only through three dedicated classes. This article covers NotesCalendar (the calendar object, entry point), NotesCalendarEntry (a single event), and NotesCalendarNotice (a meeting invitation or update notice): how to obtain them via session.GetCalendar, writing new entries with iCalendar-format strings, batch-reading a date range with ReadRange, fetching unprocessed invitations with GetNewInvitations, accepting or declining with NoticeAction, and the ConvertMIME=False prerequisite that will silently corrupt calendar data if you forget it.
2026.06.03 - NotesDocumentCollection: Complete Guide to Document Collections in LotusScript
Almost every Domino agent ends up holding a NotesDocumentCollection — but most code only uses GetFirstDocument and GetNextDocument then stops. This article covers the full picture: seven ways to obtain a collection, five navigation methods, the three in-place set operations (Intersect / Merge / Subtract), StampAll batch-write semantics and the walk-and-mutate trap, RemoveAll's force-parameter concurrency semantics, and the FTSearch + set-operations chaining pattern.
2026.06.02 - NotesRegistration: Automating User Registration with LotusScript
Every Domino admin gets the same drumbeat — new hire onboarding, employee leave, departure notifications, all eventually landing as 'create / update / disable a Notes user' tickets. Clicking through Admin Client one user at a time scales badly. NotesRegistration is LotusScript's built-in answer: a single class that programmatically wraps user registration, certification, and ID-file management. This article walks through the practical HR-system-driven scenario, RegisterNewUser's 14 parameters, the required property setup, the server-context prerequisites, and a complete CSV batch example.
2026.05.30 - db.Search: Brute-Force Document Search with @Formula — The No-Index Path
NotesDatabase.Search is LotusScript's second search mechanism — no full-text index needed, just @Formula evaluated against every document. This article breaks down the three parameters (formula / dateTime / maxDocs) and how their semantics differ from FTSearch, why the result is unsorted, how the dateTime parameter doubles as a cursor for incremental processing, the truly-unlimited maxDocs=0 (unlike FTSearch's 5000 default cap), the @function subset that doesn't work in this context (UI / lookup / write-back), the snapshot-not-live-view gotcha that catches developers after StampAll, and a production-ready incremental scheduled agent example. Part 2 of a three-part series — the follow-up compares FTSearch / db.Search / DQL side by side.
2026.05.28 - FTSearch: Domino's Three-Tier Full-Text Search API (NotesDatabase / NotesView / NotesDocumentCollection)
FTSearch is a method on three different Domino classes — and each tier returns something different. This article walks through NotesDatabase.FTSearch (returns a new collection), NotesView.FTSearch (filters the view object in place, returns a Long count), and NotesDocumentCollection.FTSearch (in-place reduction, void), the sortopt and options constants, a query-operator cheat sheet, the five CreateFTIndex options-bitmask flags and their relationship to `load updall -x`, the silent gotcha that FTSearch on a non-indexed database still runs (just slowly), the default 5000-document cap, the wildcard `*`-only-at-end constraint, and the must-be-uppercase rule for AND / OR / NOT. First in a three-part series — db.Search comes next, then a decision article tying everything together with the DQL trilogy.
2026.05.27 - Exporting NotesView Data to Excel from LotusScript: Four Paths, CSV by Default, When to Reach for POI
'Export this view to Excel for the user' is one of the most common asks in Domino dev. Four paths — CSV via NotesStream (recommended default), HTML-as-xls (legacy formatting trick), OLE Excel.Application (client-only ad-hoc), Apache POI via Java agent (production-grade .xlsx) — each with its sweet spot. This article walks the trade-off table, a complete CSV implementation (with UTF-8 BOM, CSV escaping, and NotesViewNavigator 5-10x speedup), when to use HTML-as-xls / OLE / POI, the web-download pattern, and the three traps most people forget (missing BOM, wrong escape rules, using GetFirstDocument instead of ViewNavigator).
2026.05.26 - NotesDateTime + NotesDateRange: LotusScript's Date/Time Workhorses
Two of the most frequently touched utility classes in any Domino codebase — NotesDateTime represents a single point in time, NotesDateRange spans a start-to-end interval. This article covers instantiation (New vs session.CreateDateTime), the three time-zone property families (Local / GMT / Zone) and when to use which, the six Adjust* methods for date arithmetic, TimeDifference vs TimeDifferenceDouble precision, ConvertToZone's in-place mutate semantics, NotesDateRange's four-property flat shape (with zero methods), the SetAnyDate / SetAnyTime wildcards used for view searches, the timezone trap when reading from NotesItem.DateTimeValue, and two practical examples (a stale-document reminder agent + a cross-timezone meeting scheduler).
2026.05.25 - NotesJSONArray / Element / Object: Parsing and Building JSON in LotusScript
The earlier lotusscript-http-json article walked through NotesHTTPRequest + NotesJSONNavigator — the pairing that brings the entire 'call REST API, get JSON' loop inside LS. This article picks up where that left off, going deep on the three building blocks under the navigator: NotesJSONElement (name/value pair), NotesJSONObject (object node), NotesJSONArray (array node). Full method/property tables, tree-walking patterns for parsing, the reverse path for building JSON via Append* + Stringify, the version-sensitive 64K story (including the 10.0.1 FP2 fixes via SPR# DCONB8VMAV / ASHEB95LFR and the element-value > 64K trap still live on 14.5), and a complete POST-and-parse round-trip example.
2026.05.24 - NotesLLMRequest: Call an LLM from LotusScript in 4 Lines
Domino 14.5 introduced NotesLLMRequest and NotesLLMResponse — two LotusScript classes that expose Domino IQ's local LLM as a synchronous API for app developers. This article walks the full surface: the session.CreateLlmRequest() factory method, the Completion three-parameter signature, the CompletionStream streaming variant, the IsCommandAvailable / GetAvailableCommands defensive helpers, and the Content / FinishReason / Role fields on NotesLLMResponse. Why the API takes a commandName rather than a raw prompt — the Command document abstraction lets admins and devs each control their own layer. Includes two practical examples (auto-reply agent + conditional summarization) and the Java mapping to LLMReq / LLMRes.
2026.05.23 - NotesOutline + NotesOutlineEntry Deep Dive — Programmatic UI Navigation in Domino, 4 Entry Types, 24 Properties
NotesOutline is the Domino design element behind the navigation menu in a Notes application, made up of NotesOutlineEntry items in a tree. From LotusScript you can dynamically build, modify, and walk an outline — typical use cases are multilingual menus (updating Label per user locale), role-conditional menus (hiding entries by ACL role), and personalized navigation. This guide covers the NotesOutline ↔ NotesOutlineEntry relationship, 8 tree-walking methods, 6 manipulation methods, all 24 entry properties, the 4 Set* methods, the 4 entry type constants and 9 EntryClass constants, a complete CRUD example, five pitfalls, and Java/SSJS counterparts.
2026.05.20 - NotesDOMParser Deep Dive — Loading XML into a DOM Tree, 14 Node Classes, Walking / Modifying / Serializing
NotesDOMParser loads the entire XML into memory as a DOM tree — with NotesDOMDocumentNode as the root and 14 Node subclasses (Element / Text / Attribute / Comment / CDATA / ...) representing XML constructs. You can walk anywhere, modify anything, and Serialize back to XML output. This guide covers the DOM tree model, CreateDOMParser, the 14 Node class relationships, NotesDOMNode's tree-walking API (FirstChild / NextSibling / NodeType), a complete parse → walk → modify → serialize example, five pitfalls, and Java/SSJS counterparts.
2026.05.17 - NotesSAXParser Deep Dive — LotusScript Streaming XML Parsing, 12 SAX Events, On Event Binding
NotesSAXParser processes XML in SAX (Simple API for XML) event-driven mode — instead of loading the file into memory, it fires SAX_StartElement / SAX_Characters / SAX_EndElement and other events as it reads through. The right choice for large files, read-only access, or memory-constrained scenarios. This guide covers the SAX-vs-DOM distinction, CreateSAXParser initialization, On Event binding, when each of the 12 events fires, how NotesSAXAttributeList exposes attributes, a complete LotusScript example, five common pitfalls, and the Java/SSJS counterparts.
2026.05.16 - NotesACLEntry Deep Dive — Programmatic ACL Management in Domino: 7 Access Levels, 20 Properties, Roles
NotesACLEntry represents a single entry (person, group, or server) in a Domino database's Access Control List. This guide covers the NotesACL ↔ NotesACLEntry containment relationship, three ways to obtain an entry, the seven access-level constants from NOACCESS to MANAGER, the UserType property versus the legacy IsPerson/IsGroup/IsServer flags, all twenty NotesACLEntry properties for fine-grained permissions, the Roles mechanism, the mandatory acl.Save behavior, five common pitfalls, and complete CRUD examples — closing the Domino security loop alongside the 14.5 NRPC encryption and trust-store articles.
2026.05.15 - NotesSession Deep Dive — LotusScript's Entry Point, the Single-Instance Rule, Three UserName Variants, and Evaluate
NotesSession is the class every LotusScript script reaches for first — it represents the current script's runtime environment and gives you CurrentDatabase, three user-name properties (UserName, EffectiveUserName, CommonUserName), Evaluate for running @Formula from LS, CreateLog for NotesLog, GetEnvironmentString for notes.ini reads. This guide covers the class's role, the one-session-per-script rule, key properties and methods, the three UserName variants and how they diverge under On Behalf Of agents, server-side vs workstation access-level differences, five common pitfalls, and a complete example.
2026.05.14 - NotesDocument Deep Dive — The Core LotusScript Class, Its CRUD Surface, and Five Pitfalls
NotesDocument is the core class LotusScript uses for any Domino document operation — but the details trip people up: GetItemValue always returns an array (even single values), Save's createResponse parameter is widely misread (it's not how you create response documents), Remove's force flag isn't a soft-delete switch (that's a database-level setting; use RemovePermanently to bypass it), the subtle difference between direct property syntax and ReplaceItemValue, and forgetting .Save is the most common silent bug. This guide covers every way to obtain a NotesDocument, the Item vs Field distinction, CRUD examples, the five must-know pitfalls, sibling methods, and the Java/SSJS counterparts.
2026.05.13 - NotesView.GetAllDocumentsByKey: The Lookup Workhorse, and Five Things That Trip People Up
GetAllDocumentsByKey is the LotusScript lookup method everyone uses — pass a key, get back the matching documents. But the small print — keys match the view's sorted column (not document fields), exactMatch defaults to False (so it's prefix-match unless you opt in), backslash-categorised columns silently break it, and the returned collection has no defined order — gets missed even by experienced devs. This piece walks the signature, the by-key family, five real pitfalls, and complete examples.
2026.05.09 - LotusScript's Outbound HTTP / JSON Toolchain: NotesHTTPRequest + NotesJSONNavigator
Domino V12 added NotesHTTPRequest and NotesJSONNavigator to LotusScript, so calling an external REST API and parsing the JSON response is finally a self-contained LS workflow — no more ActiveX shims or shelling out to curl. This guide covers both classes' methods and properties, the PreferJSONNavigator property that wires them together as an official path, a complete example, and where Java / SSJS land in comparison.
2026.05.07 - A Practical Guide to LotusScript NotesStream: Files Done Right
NotesStream is the LotusScript abstraction for reading and writing files from a Notes/Domino agent. This guide walks through the real Open signature, the Truncate-before-write pattern, text vs binary I/O, and the gotchas the official documentation actually warns about.
2026.05.02 - NotesRichTextItem: writing rich text fields from LotusScript
NotesRichTextItem inherits from NotesItem, so every NotesItem property and method is already available — but it adds 22 methods of its own for paragraph styles, tables, embedded objects, and Navigator/Range traversal of existing rich-text content. This post catalogues construction, the 22 methods grouped by purpose, the inheritance contract, and the gotchas you hit in real code.
2026.04.30 - NotesNoteCollection: the Swiss-army tool for NSF design elements
NotesNoteCollection is not a NotesDocumentCollection variant — it represents every kind of 'note' in an NSF, including data documents AND design elements (forms, views, agents, ACL, code libraries). This post catalogues the 32 properties, 14 methods, the True/False initialisation parameter on CreateNoteCollection, and its most common real-world use: feeding NotesDXLExporter.
2026.04.29 - NotesViewNavigator: navigate views the proper way, not GetFirstDocument loops
NotesViewNavigator is the LotusScript tool for non-trivial view traversal: it returns ViewEntry objects (which carry view metadata GetFirstDocument doesn't), it can be built over a subset of the view (a single category, all unread, descendants of an entry, a max level), and it's faster than the naive document loop — provided you remember to switch AutoUpdate off first. This post catalogues the 4 properties, ~36 methods, 7 CreateViewNav* variants, and the caveats worth knowing.
2026.04.29 - Domino V12 lets notes.ini hold multiple HTTPAdditionalRespHeader entries
Older Domino releases let you put exactly one HTTPAdditionalRespHeader in notes.ini — a second line silently overwrote the first. HCL added a numbered convention (HTTPAdditionalRespHeader01, 02, …) in V12.0.x so you can ship a full security-header baseline through notes.ini alone, which is the only path that still works when HTTP won't start and the Internet Site documents are unreachable.
2026.04.28 - Getting Started with NotesQueryResultsProcessor: Life After DQL
NQRP is a LotusScript class added in Domino V12 that lets you re-sort, categorise, project, and serialise the results of a DQL query (or any NotesDocumentCollection) — straight to JSON or to a temporary view. Walks through the create flow, every method signature, the official examples, and the safety knobs.
2026.04.28 - Getting Started with DQL: Query Notes Documents with SQL-Style Syntax
Domino Query Language (DQL) gives you a near-SQL syntax for querying Notes documents directly, without designing a new view for every query shape. This is Part 1 of the 'DQL Trilogy': DQL's design rationale, writing your first query, calling DQL from LotusScript / Java / REST API, and a syntax cheat sheet. Query-writing pitfalls are in Part 2; shipping to production (catalog maintenance and permissions) is in Part 3.
2026.04.28