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 in a chunk of someone else’s XML and turn it into Notes documents. DXL (Domino XML) is Domino’s native XML, and session has both directions built in.
But the first trap is the name. Export uses session.createDxlExporter() — note it’s Dxl, not the createDXLExporter (uppercase DXL) you’d instinctively type. Wrong case and SSJS can’t find the method. Import is the same: createDxlImporter.
This covers export, import, that naming trap, and the one import option that decides everything.
Export: exportDxl
Export is direct: create an exporter, hand exportDxl the thing to convert, get back a DXL string. NotesDxlExporter is, in the docs, “Represents the conversion of Domino data to DXL (Domino XML).”:
var exporter = session.createDxlExporter();exporter.setOutputDOCTYPE(false); // no <!DOCTYPE>, handy for embedding as a fragmentvar dxl = exporter.exportDxl(doc); // doc can be a DocumentCollection / database insteadexportDxl takes a flexible input: a Document, a DocumentCollection, a whole database, even a NoteCollection. A few commonly-tuned properties: OutputDOCTYPE (whether to emit the DOCTYPE declaration — usually off when embedding a fragment), RichTextOption (convert rich text to DXL or keep it raw), OmitRichtextAttachments (whether to leave attachments out — DXL gets large). After converting, check Log — it’s read-only and holds the run’s warnings and errors. To stream the DXL string to the browser as a download, the getContents approach in the SSJS Stream piece applies.
Import: importDxl, and the option that decides everything
Import writes DXL back into a database:
var importer = session.createDxlImporter();importer.setDocumentImportOption(NotesDxlImporter.DXLIMPORTOPTION_REPLACE_ELSE_CREATE);importer.importDxl(dxl, targetDb);var n = importer.getImportedNoteCount(); // how many came inNotesDxlImporter is “Represents the conversion of DXL (Domino XML) to Domino data,” and importDxl is “Converts DXL data to Domino data.” But the most important — and most error-prone — part is one property: DocumentImportOption. It decides what import does when it meets an “already-existing document,” and its default is DXLIMPORTOPTION_CREATE (2) — always create. So import the same DXL twice and the default behavior isn’t to overwrite, it’s to leave you with a duplicate document.
For “update if it exists, create if not,” set it to DXLIMPORTOPTION_REPLACE_ELSE_CREATE (6) or DXLIMPORTOPTION_UPDATE_ELSE_CREATE (10); to only update existing and not create, use the ..._ELSE_IGNORE variants; to never touch existing, DXLIMPORTOPTION_IGNORE (1). Set this before you import — the default CREATE quietly piles up duplicate data on a re-run.
After importing, check the same two things: getImportedNoteCount() (how many), getFirstImportedNoteID / getNextImportedNoteID (walk the imported notes), and Log (which failed and why). DXL round-trip (export then import) has its own format wrinkles — see the DXL round-trip pitfalls piece.
Naming and the Log, two repeat offenders
The two most practical points, once more:
- The method name is
Dxl, notDXL:createDxlExporter/createDxlImporter. In an API that otherwise capitalizes DXL, this is counter-intuitive, and a wrong guess first reads as “SSJS doesn’t have this method.” - Check the
Logevery time: both export and import are “may partially succeed” operations — a few notes failing to convert, a rich-text item omitted — all of it goes to the Log, not an exception. Skip the Log and you won’t know what’s missing.
What about LotusScript and Java?
The same DxlExporter / DxlImporter:
- LotusScript:
NotesDXLExporter/NotesDXLImporter(LS, by contrast, capitalizes DXL), withExportDXL/ImportDXLandDocumentImportOption; the round-trip wrinkles are in the DXL round-trip piece. - Java:
DxlExporter/DxlImporter, same API, created fromsession.createDxlExporter(), recycle when done. - What’s SSJS-specific isn’t the API (the methods are shared) — it’s wiring it into XPages: stream the
exportDxlstring straight to a download, orimportDxlthe XML a front end posted into documents — remembering the name isDxland checking theLogeach time.
Sources
- NotesDxlExporter (JavaScript) (exportDxl, OutputDOCTYPE, RichTextOption, Log) — HCL Domino 14.5 Designer Help (official)
- NotesDxlImporter (JavaScript) (importDxl, DocumentImportOption, ImportedNoteCount, Log) — HCL Domino 14.5 Designer Help (official)
- NotesSession (JavaScript) (createDxlExporter / createDxlImporter) — HCL Domino 14.5 Designer Help (official)