#LotusScript
Posts tagged #LotusScript · 92 posts
- NotesView AutoUpdate=False: Why Modifying Documents in a View Loop Slows Down and Throws 'Entry not found in index'
An agent loops a view, tweaks each document, and gets slower and slower — sometimes even throwing 'Entry not found in index.' The culprit: NotesView refreshes itself by default, so when your loop modifies the very documents the view indexes, the view keeps re-sorting under your feet — killing performance and invalidating your navigation position. The fix is one line before the loop: view.AutoUpdate = False. This piece explains the mechanism, the correct 'grab the next handle before modifying' pattern, and three side effects to know (snapshot, current-code-only, must Refresh to see updates).
2026.09.15 - NoteID, UNID, @DocumentUniqueID: What Actually Separates Domino's Three Document IDs
To point at a Domino document you might grab its NoteID, its UniversalID (UNID), or use @DocumentUniqueID in Formula — three that look alike and behave nothing alike. A NoteID only means something inside one database file and changes across replicas; the UNID is a 32-character identity that's identical across every replica; @DocumentUniqueID returns that UNID (but without @Text it's a doclink, not text). This piece pins down each one's scope, stability, and when to use it — including the 'change the UNID and it becomes a new document' and 'save a duplicate UNID and get error 4000' traps, and where that /0/UNID in web URLs comes from.
2026.09.14 - 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 - 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 - 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 - LotusScript Has No removeElementAt: Removing One Element from an Array, List, or Multi-Value Field
Removing one multi-value element is easy in SSJS/XPages — java.util.Vector has removeElementAt, loop backwards and delete by index. In LotusScript you hit a wall: no Vector, no removeElementAt, and Erase clears a whole array rather than dropping one element. This is a field report on the real options — figure out what your collection actually is first, then reach for Split/Join, an array rebuild, a List's Erase(tag), or Evaluate + @Replace.
2026.08.11 - Why Does the Same Notes User Fail a Comparison? Understanding NotesName's Three Name Formats
You compare a name to session.EffectiveUserName and it's never equal, even though it's obviously the same person. Or you write a user into a Readers field and they still can't see the document. Same root cause: a Notes name has three text forms — canonical, abbreviated, common — and you compared two different ones. A field report on NotesName: what each format is, which one Notes stores internally, and why every name comparison should normalise through NotesName first.
2026.08.06 - 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 - Who Does Your Agent Run As? Signer, Effective User, and the Error 201 / Readers-Field Traps
Your agent works perfectly when you run it — because you're the admin who signed it. Deploy it as a web agent, or schedule it signed by a service ID, and it fails with Error 201 or silently sees no documents. The cause is identity: a Domino agent runs as someone, and that someone isn't always you. A field report on the signer vs the effective user, how session.EffectiveUserName flips on 'run as web user', the runtime security level behind Error 201, and the Readers-field trap that makes documents vanish.
2026.08.03 - 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 - Button, Field, Navigator: the LotusScript Classes With Zero Properties and Zero Methods
Open the LotusScript help for Button and you expect properties and methods — there are none. Same for Field, same for Navigator. All three are empty on purpose: they exist only as event entry points, the typed Source parameter that tells a front-end event handler which element fired it. A field report on the three classes you never call anything on — what their events are (Click, Entering / Exiting / OnChange), and why the real work always goes through NotesUIDocument.
2026.08.01 - 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 - Save(True, False) or Save(False, True): the Two Booleans That Decide Who Loses Data
Two processes touch the same document — a web agent and a user with the form open, or a scheduled agent and a replica. One save wins, the other's edit either vanishes or turns into a mysterious $Conflict. Which one happens is decided entirely by the two booleans you passed to NotesDocument.Save. A field report on force and createResponse: last-write-wins vs the conflict document the replicator makes, why Save(True, False) quietly loses data, and how to pick on purpose.
2026.07.27 - 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'll Never Instantiate: the Read-Only DTD Corner
NotesDOM implements the full W3C node model, which means four node types exist for the DTD corner most XML developers never touch: DocumentType, Entity, EntityReference, and Notation. A short map of what they are, which one you can actually create (EntityReference), which are read-only reflections of a parsed DTD, and why in 2026 you can usually walk past all of them — plus the one case where knowing they exist saves an afternoon.
2026.07.25 - 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 - 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 - NotesPropertyBroker / NotesProperty: How Composite Applications Wire Components Together
Composite Applications were a Notes 8.x feature — assembling several components (Notes components, Java/Eclipse components) on one screen and letting them pass values to each other. NotesPropertyBroker is the mediating layer; NotesProperty is the single property being passed. This article is honest about where these classes sit (fairly legacy), covers getting the broker with GetPropertyBroker, the GetPropertyValue / SetPropertyValue / Publish / HasProperty methods, InputPropertyContext, and what it actually means today.
2026.06.27 - 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 - NotesIDVault: Pulling IDs from the ID Vault, Syncing, and Resetting Passwords in Code
The ID Vault is Domino's policy-based facility for centrally storing user ID files. NotesIDVault lets you operate it from code — pull a user's ID file out of the vault, sync a local ID back, check whether someone's ID is in the vault, even reset a vault password. This article covers getting it, the GetUserIDFile / SyncUserIDFile / IsIDInVault / ResetUserPassword / PutUserIDFile methods, its relationship to NotesUserID, and the permission prerequisites for these operations.
2026.06.25 - 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 - '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 - NotesForm: Reading a Database's Forms, Fields, and Who Can Use Them in Code
You inherit an undocumented NSF and want to figure out which forms it has, what fields each defines, and who's allowed to create documents — without opening Designer. NotesForm reads that design information from code. This article covers getting forms from db.Forms / db.GetForm, the Name / Aliases / Fields / FormUsers / Readers properties, GetFieldType and Remove, and how ProtectReaders / ProtectUsers relate to replication.
2026.06.17 - 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 - FTSearch vs db.Search vs DQL: Choosing the Right Domino Search Mechanism
Starting with Domino 14, there are three technical paths for searching documents: FTSearch (full-text index), db.Search (@Formula full scan), and DQL (introduced in V12, structured query using the design catalog and NIF indexes). This article puts the three side by side in a multi-dimensional comparison table, walks a three-question decision tree, and digs into Domino 14's integration of `@FTSearch()` as a DQL term — which finally lets you express text + structured conditions in a single query. Three practical scenarios (one-off lookup, scheduled agent, high-frequency REST API) map to recommended paths, with cross-links to the full search series and the DQL trilogy.
2026.05.29 - 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 - Parsing XML in LotusScript — DOM or SAX? Five Questions That Pick the Right Tool
LotusScript offers three routes for XML processing: NotesDOMParser (whole-tree load), NotesSAXParser (event-driven streaming), and NotesXMLProcessor + NotesXSLTransformer (rule-based XSLT transformation). This guide compares the three at a fundamental level, walks five decision questions (file size / modification needs / traversal direction / memory budget / transformation scenario), gives practical scenario picks, code-style side-by-side, performance numbers, and a consolidated pitfalls table. After reading you'll know exactly which tool to reach for when an XML file lands.
2026.05.18 - 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 - Domino 14.5 Changes Where NotesHTTPRequest Loads Trusted CAs From — Read Before You Upgrade
Starting with Domino 14.5, server-side LotusScript NotesHTTPRequest loads trusted root CAs from the Domino Directory by default, no longer from cacerts.pem in the data directory. The Notes client is unaffected, and a notes.ini fallback (NotesHTTPRequest_Use_CACerts=1) reverts to the old behavior — but long term, you should migrate self-signed CAs into the Domino Directory. This piece walks the change, scope, pre-upgrade checklist, and ties back to the 5/7 deep-dive on the NotesHTTPRequest toolchain.
2026.05.10 - 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 - OpenNTF's LotusScript Class Map: 97 Classes on One Interactive Page, Open-Source Data Behind It
OpenNTF released a LotusScript Class Map for HCL Domino 14.5.1 in 2026 — 97 classes, 1,001 properties, 997 methods, 72 events laid out on one interactive visual map, every node clickable through to the HCL docs. This piece covers what the tool does, the open-source license and JSON data behind it, and why it's useful for picking topics, planning learning paths, and exploring the API surface.
2026.05.08 - 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 - NotesXMLProcessor: The Common Base for LotusScript XML Handling
NotesXMLProcessor is the abstract base class behind every LotusScript XML handler — DOMParser, SAXParser, DXLExporter, DXLImporter, and XSLTransformer all inherit from it. This guide covers the role it plays, the five derived classes and when to pick which, the inherited properties, the SetInput / SetOutput / Process trio, and the Release 6 / no-COM caveats that don't make it into most quick refs.
2026.05.06 - DQL Production-Ready: Catalog Maintenance, Permissions, and sessionAsSigner
The two real walls when shipping DQL to production: how the Design Catalog gets maintained automatically (bootstrapping brand-new NSFs, incremental refresh after design changes), and why regular users hit the 'You don't have permission' error — plus the sessionAsSigner / scheduled-agent solutions. The final pattern is verified against Domino 12 production logs, with a production-ready Java helper class to drop in.
2026.05.03 - 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 - DQL Pitfalls: 6 Query-Writing Details the Official Docs Don't Spell Out
Domino Query Language (DQL)'s syntax looks SQL-like, but writing real queries surfaces a whole set of Notes-specific traps — view selection silently scopes results, the `'view'.column` references the view column's programmatic name (not a doc field), comparison operators need whitespace on both sides, backslashes in view names need escaping, `@formula` is a separate Formula Language parser, and string-stored date fields need `@TextToTime`. Each trap below comes with the verbatim error message and a working fix.
2026.05.01 - 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 - 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