#Tutorial
Posts tagged #Tutorial · 101 posts
- Domino on Linux: the Case-Sensitivity Trap, and Why the Path Cache Hides It
After moving Domino from Windows to Linux, a URL with the wrong case (the folder on disk is /FFH/ but you request /ffh/) sometimes 404s with 'File does not exist' and sometimes works — the same URL, flaky, and it always works by the time you go to check, so everyone assumes it's fine. The truth: Linux's filesystem is case-sensitive, and the Domino HTTP task caches successful path lookups, so the 404 only shows up when the cache is cold AND the very first hit uses the wrong case. This piece uses three rounds of curl tests on a real R12 (12.0.2 FP8) Linux server to reproduce the trap cleanly, explains why it stays hidden, and measures the symlink and directory-link workarounds.
2026.10.09 - Domino Maintenance Commands in Practice — Option Rules, the Transaction-Log Branch, and Scenario Playbooks (Daily / Repair / Won't Open)
The options for updall, compact, and fixup are all over the web, but the same compact run with -b vs -B — and whether transaction logging is on — produces wildly different results: one keeps the DBIID, the other reassigns it and breaks your backup chain. This piece turns HCL's own maintenance manual into a practical reference: three syntax rules first (parameter position, case-sensitivity -b≠-B, keyword options), then compact's three compaction styles, then the full command sequences for three scenarios — scheduled daily maintenance, corruption repair, and work-hours-no-downtime — each marked for whether transaction logging is enabled.
2026.10.08 - DXL in Java: Exporting and Importing Domino Data with DxlExporter / DxlImporter
To move design elements between databases, or snapshot documents as XML for diffing/backup, DXL is Domino's XML representation. In Java the two workhorses are DxlExporter (Domino→DXL, exportDxl returns a String) and DxlImporter (DXL→Domino, importDxl writes into a target DB). The catch: import isn't just 'load the XML' — you tell it how to handle design, documents, and ACL (create/replace/update/ignore) with setDesignImportOption / setDocumentImportOption / setAclImportOption, and whether the replica must match. This covers both classes, the import options, and the relationship to the LotusScript version.
2026.10.04 - NotesThread: The Rules for Background Threads in Domino — init Each Thread, Give It Its Own Session
Want to run Domino local calls on a background thread in Java? A plain new Thread won't do — it has no Notes runtime. You either extend NotesThread and override runNotes(), implement Runnable handed to NotesThread, or call sinitThread()/stermThread() yourself. And every thread needs its own Session and its own recycle — you can't share across threads. This covers the three NotesThread patterns, the sinitThread/stermThread pairing rule, the one-session-per-thread law, and why a background thread can't get sessionAsSigner.
2026.09.30 - The Four XPages Scopes: How Long Each Lives, What to Put in Each, and What Blows Up
XPages has four scopes — requestScope, viewScope, sessionScope, applicationScope — with lifetimes from a single request to the whole application. Pick the wrong one and values vanish or leak across users; but the sharpest trap is that scopes get serialized to disk, so stuffing a NotesDocument, NotesView, or an SSJS function into one eventually throws NotSerializableException. This covers how long each scope lives, how unqualified names resolve tightest-first, what's safe to store, and why you keep a UNID or view name rather than the object.
2026.09.27 - XPages Save Conflicts: Why You Get One Even When You're the Only User
"Document has been saved by another user" — except no one else is touching the document, yet a save conflict shows up now and then anyway. This is an old XPages trap: mixing the dominoDocument data source's save with a back-end Document save on the same document makes Domino's conflict detection misfire and spawn a conflict document. Starting from the official conflict mechanism ($Revisions), it breaks down assono's classic reproduction and re-tests this 2013-era gotcha on both Domino 12.0.2 and 14.5.1.
2026.09.16 - Multi-Select Attachment Delete in XPages: Native Deletes One at a Time — Add 'Check Several, Delete on Save'
The XPages File Download control gives you one delete link per row — one attachment at a time — with no native 'check several, delete together.' Even a fully built production form lacks it. This piece first clears up something by testing: the native delete is actually 'commit on save' and well-behaved; then it adds multi-select batch delete with the same save-bounded official API (NotesXspDocument.removeAttachment), building a real check-mark, reversible, one-save implementation on a test server (Domino 12.0.2).
2026.09.13 - Classic Domino Web Attachment UI Tricks: Hide the Crude Default with $V2AttachmentOptions, Then Draw Your Own List and Delete
Drop a File Upload Control on a Domino web form, add a save button, and it works — but it looks crude: Domino dumps the attachments at the bottom of the page, and in edit mode adds a row of un-styleable 'mark for deletion' checkboxes. This piece covers the classic Domino web developer's toolkit: hide the default attachment area with $V2AttachmentOptions="0", draw your own download list with pass-through HTML and @AttachmentNames, and the rarely-explained delete mechanism %%Detach (roll your own checkboxes, or use WebQuerySave). Includes the gotchas: $V2AttachmentOptions is 0/1 only, and it's text not a number.
2026.09.11 - Multi-File Upload and Selective Attachment Delete in Domino: Classic Web and XPages 14.5.1
The last piece covered attaching one file three ways; this one goes to 'many at once': a classic web form uses the HTML5 multiple attribute to select several files, XPages only got native multi-select by default in 14.5.1 (before that it was OpenNTF community controls), and the case you actually hit most but is thinly documented — deleting attachments by criteria: iterate EmbeddedObjects and Remove by a condition on .Source (with a runnable example). With a figure showing how the selected files land in one rich text field.
2026.09.09 - File Attachments in Domino Three Ways: Notes Client, Classic Web Form, and XPages
Attaching a file in the Notes client is so easy it barely feels like a feature — drag it into a rich text field, done. But move that same need to the web, or into XPages, and 'how do users upload a file' becomes three different answers: the client uses a rich text field, a classic web form uses the File Upload Control embedded element, and XPages uses xp:fileUpload paired with xp:fileDownload. This piece lines up the three front-end upload mechanisms and points out the reassuring part — all three land as an attachment on the same rich text field of the document, so the backend code to list, extract, and delete them is shared.
2026.09.08 - The Java Fix for Domino IQ Timeouts: LLMReq.completionStream, and How XPages SSJS Calls It
Yesterday's piece used LotusScript's CompletionStream to get past Domino IQ's 5-minute timeout; if your code is Java (an agent, a bean) or XPages (SSJS), you hit the same timeout. This is the Java version: LLMReq.completionStream with the CompletionStreamCallback interface (return Continue/Stop to control the stream), plus a key fact — SSJS has no native LLM class, but SSJS's session IS a lotus.domino.Session, so you call the Java API directly or wrap the streaming in a Java class and reference it from SSJS. With a three-language comparison table.
2026.09.06 - Domino IQ Requests Timing Out at 5 Minutes? No Setting to Raise — Switch to Streaming
You build a long-document summary on Domino IQ; in testing the prompts are short and it's instant. In production someone feeds in a huge thread on a modest GPU, and you hit a 'network processing did not complete in time' timeout. You go hunting for a timeout setting to raise — there isn't one. Domino IQ requests time out at about 5 minutes, by design, and it can't be changed. This piece walks a real scenario: why it times out, how to switch from Completion to CompletionStream to get past it, and one important caveat — streaming keeps it from timing out, but doesn't make it faster.
2026.09.05 - Wiring Domino CertMgr to Let's Encrypt: Automatic TLS Certificate Requests and Renewals over ACME
Manual certificate import still means swapping every 90 days, and still means forgetting. This piece (part two of the certstore series) covers CertMgr's real killer feature: requesting, configuring, and renewing free, trusted TLS certificates from Let's Encrypt automatically over the ACME protocol. Set up the two ACME account profiles (Staging/Production) and Global Settings, walk the request flow and the six things CertMgr does automatically after Submit, understand HTTP-01 vs DNS-01 challenges, and see why the micro CA is test-only, plus ECDSA and key rollover.
2026.09.03 - Getting Started with Domino Certificate Management: CertMgr and certstore.nsf Instead of Scattered .kyr Keyrings
Since Domino 12, TLS certificates no longer live as .kyr keyring files scattered across each server's disk — one CertMgr server task plus one certstore.nsf database manages them all: certificates stored in TLS Credentials documents, private keys encrypted with 256-bit AES, protected by the database ACL, and readable only by the servers you choose. Part one of the certstore series: the model, how to stand certstore.nsf up, what a TLS Credentials document holds, and the full steps to import an existing third-party CA certificate.
2026.09.02 - Formula's @For Loop: When You Actually Need It, and a Real 'Reverse an Org Hierarchy' Example
The list functions (@Transform, @Explode…) handle a whole list in one line, but some jobs still need a real loop — accumulate state, build a string in order, reverse a list. This piece goes deep on @For: the four parts (initialize/condition/increment/body), a thing that trips people up (@For returns 1, not your accumulated value, so you return the variable on a separate final line), and a real need worked through — turning an A\B\C org hierarchy into C\B\A. Plus how @While/@DoWhile differ, and the infinite-loop guard.
2026.09.01 - Error Handling and Evaluation in Formula: @IfError, @Eval, and Where a Formula Runs
Series finale. The first six parts covered what formula can do; this one covers two things you hit no matter what you write: what happens when a formula errors, and where and when a formula actually runs. Catch errors with @IfError and a fallback, test with @IsError — but remember @IfError hides the real error message, so drop it while debugging. @Eval runs a string as a formula at runtime. And 'which context a formula runs in' is the root of half the series' gotchas (@DbLookup not allowed in column formulas...). Part seven (final) of the Formula @function series.
2026.08.31 - Control Flow and Variables in Formula: :=, @If, @Do, @For/@While
A real formula branches, holds intermediate values, and occasionally loops. This piece covers structuring formulas: temp variables x := ... are the modern backbone (semicolon-separated, the last statement is the return value); @If chains up to 99 condition/action pairs — formula's switch; @Do evaluates in sequence and returns the last; and real loops @For/@While/@DoWhile exist but, because formula is list-oriented, are rarely needed. Part six of the Formula @function series.
2026.08.30 - Date Arithmetic in Formula: @Adjust to Add/Subtract, @Now/@Today for Now, and @Modified's Two Versions
Date math in formula isn't a big date library — it's a few @functions. Add or subtract with @Adjust (seven positions for year/month/day/hour/minute/second, positive or negative); get now with @Now (full timestamp) or @Today (date only); get document times with @Created/@Modified. This piece also flags two traps: @Now re-evaluates every run and hurts efficiency in column/selection formulas, and @Modified (modified initially) vs @ModifiedInThisFile (last modified in this file) differ once you have replicas. Part five of the Formula @function series.
2026.08.29 - @Name Is the Swiss Army Knife for Notes Names: Three Formats, Any Component
In formula you constantly handle Notes names — comparing, displaying, extracting the OU. @Name is the Swiss army knife: [ABBREVIATE]/[CANONICALIZE]/[CN] convert among canonical/abbreviated/common, and [O]/[OU1]/[S] extract any part. Get the current user with @UserName (canonical) or @V3UserName (abbreviated) — but there's a trap: inside a server agent the 'current user' is the signer, and it isn't a security mechanism. Part four of the Formula @function series.
2026.08.28 - String Functions in Formula: @Left/@Right/@Middle, @Word, @ReplaceSubstring
Cutting strings in formula: many people only know @Left(s; 3), the count form — but @Left/@Right/@Middle also take a delimiter string: @Left(email; "@") is everything before the @. @Middle has four signatures, so 'grab what's between X and Y' is one line. This piece covers formula's string tools: @Middle's four forms, @Left/@Right's dual form, @Word to grab the nth piece by separator (-1 for the last, for surnames), and @ReplaceSubstring with parallel lists for multiple replacements. Part three of the Formula @function series.
2026.08.27 - Why You Barely Write Loops to Process a List in Formula
Coming from LotusScript/Java, you'd loop over a list. But formula has almost no loops — because one formula already operates on a whole list at once. This piece treats formula as a functional list language: an operation on a multi-value field runs element-wise (implicit map), @Transform is the explicit map (with @Nothing for filter, a returned list for flatMap), @Explode/@Implode split and join, and @Sort sorts (with [CUSTOMSORT] using $A/$B). What's a ten-line loop elsewhere is often one line of formula. Part two of the Formula @function series.
2026.08.26 - Reading Values Across Views and Databases in Formula: @DbColumn and @DbLookup
To read another view or another database from formula, two functions do ninety percent of the work: @DbColumn grabs a whole column (keyword lists, dropdowns), @DbLookup finds a value by key (resolve a code to a label, pull a related field). This piece covers both signatures, the cache keyword (""/NoCache/ReCache), and the rules you must know — the first column must be sorted, equality-only matching, the 64KB cap, and where they can't be used. Part one of the Formula @function series.
2026.08.25 - Your DQL Is Correct but Returns Nothing? The Form Is Missing a dql Mode
Last part fetched a single document by unid. What you usually want is 'the batch that matches' — all incomplete todos, all customers in a region. DRAPI gives two paths: GET /lists/{view} to read a view/folder, or POST /query to run DQL. DQL even supports parameterized queries (?VAR + variables, injection-safe). But there's a trap that follows from the last part's modes: a form without a dql mode is completely invisible to DQL. This part covers both query paths, pagination, the mode trap, and DQL access control. Part five of the DRAPI series.
2026.08.23 - Creating a Document in the Domino REST API: Why It Needs a Form Field and a dataSource
The door is open (schema + scope); this part does the real work: create/read/update/delete NSF documents over REST. Create is POST /document with a required Form field in the body, and the response @meta carries a unid; read is GET /document/{unid}/{mode}. Every CRUD call carries dataSource — and that value is the scope name you made last part. It also covers two things that give Domino developers pause: why the Form field is required, and what a mode is. Part four of the DRAPI series.
2026.08.22 - A Cross-DB Embedded View Won't Start in the Test Region? It's the Replica ID Baked into the DXL
A cross-database embedded view on a form worked fine in dev, then showed 'cannot start' the moment it reached the customer's test region. Nowhere in Designer's embedded-view UI is there a field to change the source database. Export the form to DXL and the reason shows up: the embeddedview element pins its source by the source database's replica ID — change environments and that ID no longer resolves. This is a field report: how to diagnose it, how to swap it in bulk with a NotesDXLExporter/Importer agent, and the faster way I found afterward — editing the DXL directly in Designer.
2026.08.18 - Stop Hand-Rolling Parallel Arrays: LotusScript's List Is the Built-In HashMap for Counting, Dedup, and Lookups
You need to count documents by category, dedup a set of names, or build a code-to-label lookup. The Domino reflex is two parallel arrays and a linear scan, or a throwaway view. But LotusScript has had a native keyed collection all along and almost nobody reaches for it: the List. A field report on the built-in associative array — its keyed access, ForAll + ListTag iteration, Erase, and the two gotchas (guarding reads with IsElement, and tag case sensitivity following Option Compare).
2026.08.05 - NotesUIScheduler: Driving the Embedded Free/Busy Grid From LotusScript
A custom room-booking or meeting form has the embedded scheduler control — the busy-time grid where you add attendees and see everyone's free/busy. NotesUIScheduler is how you drive that control from code: get it by name off the UI document, add or remove participants, refresh the schedule data, and read back the interval the user picked. A field report on the one front-end scheduling class, its GetScheduleData refresh, and the two events you hook.
2026.08.02 - The LotusScript Web Agent I/O Model: Print Is Your Response, DocumentContext Is Your Request
A LotusScript web agent has no request object and no response object — it has Print, whose output becomes the HTTP body, and DocumentContext, a special document holding the CGI variables. A field report on the two halves: how the first Print line sets Content-Type so you can return JSON instead of HTML, how to read the query string and POST body from DocumentContext, the CGI-fields gotcha that leaves them empty, and how it all fits with a top-level error handler.
2026.07.31 - DXL Round-Trip Pitfalls: Why Export-Then-Import Gives You Duplicates, Not the Same Documents
You export documents to DXL, import the DXL into another database, and end up with copies carrying brand-new UNIDs instead of the same documents updated in place — because the importer creates by default and only matches on UNID when you tell it to. A field report on the DXL round-trip: the DocumentImportOption that decides create-vs-replace, why default rich text isn't binary-identical (and when to switch to RAW), and the stale-handle trap that hides the whole thing.
2026.07.30 - LotusScript Error Handling: On Error Is Per-Procedure, and Resume Next Is Not 'Ignore Errors'
Two habits sink most LotusScript error handling: treating On Error as if it were global (it's per-procedure, and uncaught errors climb the call stack), and reaching for On Error Resume Next as a blanket 'ignore errors' switch (it hides the bug, it doesn't handle it). A field report on doing it deliberately — the per-procedure scope, the Err / Error$ / Erl lifecycle, the difference between Resume, Resume Next, and Resume label, and the clean-error pattern a web agent actually needs.
2026.07.29 - NotesUIDatabase: the One Place to Catch a Delete
In the Notes client a user can delete a document from any view, with the Delete key, a cut, or a drag to the trash — you can't guard each path separately. NotesUIDatabase is the single chokepoint that sees all of them: its QueryDocumentDelete event fires once, database-wide, before anything is marked for deletion. A field report on the front-end database class — the Database bridge, the delete/archive events, and the soft-delete guard you hang off the one event that catches every path.
2026.07.28 - NotesUIView: the Only Class That Knows What the User Selected
A view action button is supposed to act on the rows the user highlighted — but the back-end NotesView has no concept of a selection. That gap is exactly what NotesUIView fills. A field report on the front-end view class: its Documents property (the live selection), the bridge back to the back-end View, the QueryOpenDocument / QueryClose events you hook to intercept the user, and the hard boundary that keeps all of it out of web and agent code.
2026.07.26 - The NotesDOM Node Types You Skipped — Until a Round-Trip Drops Your Comments
You built a NotesDOMParser pipeline for element and text nodes. Then you parsed XML with a comment, a CDATA block, and a processing instruction, changed one value, serialised it back — and the comment and PI were gone. A field report on the rest of the NotesDOM node family: NodeList's 1-based GetItem (not the W3C 0-based item()), DocumentFragment for batch inserts, and the CDATA / Comment / ProcessingInstruction nodes you have to create yourself to preserve on the way out.
2026.07.24 - 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