#SSJS
Posts tagged #SSJS · 16 posts
- DXL in XPages: It's createDxlExporter (not DXL), and Import Hinges on DocumentImportOption
In XPages you need to hand a document, or a whole view, to an external system as XML — or the reverse, feed a chunk of XML in and turn it into Notes documents. DXL (Domino XML) is Domino's native XML, and session has both directions built in: createDxlExporter() out, createDxlImporter() in. The first trap is the name — it's createDxlExporter, not the createDXLExporter (uppercase DXL) you'd instinctively type; wrong case and SSJS can't find the method. The second is on import: DocumentImportOption defaults to DXLIMPORTOPTION_CREATE (always create), so importing the same DXL twice makes two duplicate documents; for "update if it exists, create if not" you have to set REPLACE_ELSE_CREATE or UPDATE_ELSE_CREATE yourself. This covers export, import, that naming trap, and why you check the Log every time.
2026.11.22 - ACL in XPages: Check Access with queryAccess, Change It Only Through sessionAsSigner
Dealing with the ACL in XPages is usually two different jobs with different code. One is checking: is the logged-in user Editor or above, do they have a given role — to decide whether a button shows or a panel renders. That's just database.getCurrentAccessLevel(), queryAccess(name), and queryAccessRoles(name); no ACL object needed. The other is changing: an admin screen to adjust other people's access — that means getACL, edit, and save, but the web user is usually not a Manager and can't touch the ACL, so you go through sessionAsSigner to run as the design element's signer. This piece keeps the two apart: the access-checking shortcuts, comparing against the LEVEL constants, role gating, and why changing the ACL always routes through sessionAsSigner.
2026.11.20 - NotesName in XPages: getCommonUserName Saves a Step, Comparing Still Needs Normalizing
In XPages, to show the logged-in user's name many people write session.createName(session.getUserName()).getCommon(). You don't have to — session has getCommonUserName() to get the common name in one step, and getUserNameObject() hands you a NotesName object directly. That's where XPages is more convenient than back-end Java. But one thing XPages can't skip: comparing user names, or using OU for conditional visibility (rendered), still hits the "same person, canonical and abbreviated aren't equal" trap, and you still have to createName and normalize both sides. This covers the session name shortcuts, comparing and checking OU correctly in XPages, and which form to use when writing a name into a Readers field.
2026.11.17 - ViewEntry in XPages: Read the View with getColumnValues, Without Opening Each Document
In XPages you need to list a batch of data — a typeahead list, a chunk of JSON, a custom repeat. The columns you want to show are already laid out in some view. The reflex is to walk the view, getDocument on each row, and read the fields — but that opens every document, and a big view is slow. NotesViewEntry lets you read the index-level column values directly: getColumnValues returns each column's value for that row, and the whole walk can open zero documents. This covers getting a ViewEntry in XPages, reading column values, one confusing point (the collection from getAllEntries holds only document rows — category rows need a ViewNavigator), and that XPages, unlike Java, doesn't make you recycle.
2026.11.15 - Stream in XPages: Build a Download with getContents, and Set the Charset Yourself
In XPages you want the user to click a button and download a report file you generate on the spot, or read a file they just uploaded and parse it. The back-end NotesStream (session.createStream) is the tool for that. It has one method that's especially handy in XPages: getContents pours the stream's contents straight into a java.io.OutputStream — which is exactly what the HTTP response's output stream is — so you can stream the generated file to the browser without landing a temp file on disk first. This covers building a download with Stream, reading an uploaded file via fileUpload, writeText's no-line-ending default, and the charset-defaults-to-System trap (the deep dive on that lives in the Java Stream piece; here it's just the fix).
2026.11.12 - DocumentCollection in SSJS: stampAll Updates Them All, removeAll Deletes Them All
In SSJS a search, an FTSearch, or a view lookup by key hands you a NotesDocumentCollection. To do something to that pile of documents, the reflex is a getFirstDocument / getNextDocument loop; but the collection has batch operations of its own: stampAll sets one field to the same value across every document, and removeAll permanently deletes the whole batch — one line, no loop. Powerful, and removeAll especially will do exactly what you tell it, permanently. This covers getting and walking a collection in SSJS (including the Count-is-a-property-not-getCount gotcha), the stampAll / removeAll batch moves and their risks, combining collections with FTSearch and intersect/merge/subtract, and whose rights these run under.
2026.11.09 - In XPages the Database Is Free — the Question Is Whose Rights Opened It
LotusScript and Java both make you write a few lines to get a Database; in XPages SSJS, database is just there, pointing at the current NSF — you don't even call getDatabase. So the hard part of the Database in SSJS isn't how to get it, it's a question LS and Java rarely force on you: whose rights is this code running with? The user's? Or the XPage's signer's? This covers the database global, how to open other databases (session.getDatabase / getCurrentDatabase), and the session vs sessionAsSigner vs sessionAsSignerWithFullAccess rights model — when you have no choice but to run as the signer.
2026.11.06 - XPages Has Two Documents — Don't Edit the Wrong One
When you write document1 in XPages SSJS, you're holding the data-source wrapper (NotesXspDocument). But document1.getDocument() hands you a different object — the back-end NotesDocument. Both point at the same note, but they're two APIs: the wrapper uses getValue / setValue, the back end uses getItemValue / replaceItemValue, and each has its own save. This piece is about the back-end one: how to get it in SSJS, what it does (replaceItemValue / computeWithForm / save / remove / universalID), where the line between it and the wrapper sits, and why saving on both sides spawns a save-conflict document.
2026.11.04 - Three Kinds of Date in XPages — You Have to Know Which One You're Holding
The thing that bites you with dates in XPages SSJS isn't a method you can't call — it's not noticing that three different 'dates' are in play at once: the back-end NotesDateTime, the Java-layer java.util.Date, and JavaScript's own Date. What you read from a document is a NotesDateTime; what @Today hands you might be something else, and putting the wrong one in the wrong place throws or stores a bad value. This covers building a NotesDateTime in SSJS (session.createDateTime), converting between the three types (toJavaDate), the common methods (adjustDay / setNow / timeDifference / convertToZone), and the two classic traps — 'Today has no time' and '@Today isn't necessarily a NotesDateTime'.
2026.11.03 - Running @Formula from SSJS: session.evaluate — Its Vector Return, Limits, and Why It Can't Change a Document
You already have Formula logic — an @DbLookup, an @Name formatting call — and you don't want to rewrite it in SSJS. session.evaluate() runs a Formula string straight from SSJS and hands the result back. But it has sharp edges: it returns a java.util.Vector (not a scalar), field references need the document as a second argument, UI @functions (@Command/@Prompt/@PickList…) don't work in it, and it can't change a document — only compute a result. This covers the two signatures, the return and limits, and how to write the result back when you need to persist it.
2026.10.05 - XPages Managed Beans: Giving SSJS a Real Java Object You Use Like database
SSJS in a script library is fine as glue, but logic gets unwieldy fast — no real types, hard to test, and serialization headaches when you stash it in scope. A managed bean lets you declare a Java class in faces-config.xml, and it becomes a top-level variable in SSJS and EL that you use just like database or session — bean.method(), #{bean.prop}. This covers how to declare one (the name/class/scope elements), the three class requirements (no-arg constructor, get/set, Serializable), the scope lifecycle, and when logic should move out of SSJS into a bean.
2026.10.03 - partial refresh vs partial execution: the XPages JSF Lifecycle, and Why Refreshing One Area Still Recomputes the Whole Page
You click one button in XPages and a validator on a completely unrelated field blocks you — because by default the whole page runs a round of the JSF lifecycle, not just your button's area. XPages has two independent 'partial' knobs: partial refresh (refreshMode/refreshId) controls which HTML fragment goes back to the client; partial execution (execMode/execId) controls which components run the server-side lifecycle. This uses the six JSF phases to explain the difference, why partial refresh alone still recomputes the whole page on the server, and how partial execution scopes the server work down.
2026.10.01 - sessionAsSigner: Running XPages Code as the Signer — Who the Signer Is, and Where It Bites
XPages gives you three global session objects: session is the current user, sessionAsSigner is the XPage's signer, and sessionAsSignerWithFullAccess is the signer plus full access. Using it to let a user do what their ACL forbids (write a restricted DB, bypass Readers) is handy — but 'who counts as the signer' is decided per design element, so a script library uses its own signer, not the XPage's, and mixed signatures give inconsistent elevation. This covers the three identities, how the signer is determined, and the setConvertMime / full-access traps.
2026.09.28 - 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 - 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 - XPages/SSJS: Working with Multi-Value Fields Using java.util.Vector
LotusScript has no removeElementAt, so dropping one multi-value element means rebuilding an array. SSJS is the opposite — it runs on Java, a multi-value field reads in as a java.util.Vector, and addElement/removeElementAt/insertElementAt are right there, then you write it back with replaceItemValue. A field report on using Vector for multi-value work, why removeElementAt loops backwards, and the two traps you will hit (the empty field's [""], and getValue's type).
2026.08.12