DXL in XPages: It's createDxlExporter (not DXL), and Import Hinges on DocumentImportOption

DXL in XPages: It's createDxlExporter (not DXL), and Import Hinges on DocumentImportOption

Nov 22, 2026 513 words

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 fragment
var dxl = exporter.exportDxl(doc); // doc can be a DocumentCollection / database instead

exportDxl 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 in

NotesDxlImporter 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, not DXL: 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 Log every 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), with ExportDXL / ImportDXL and DocumentImportOption; the round-trip wrinkles are in the DXL round-trip piece.
  • Java: DxlExporter / DxlImporter, same API, created from session.createDxlExporter(), recycle when done.
  • What’s SSJS-specific isn’t the API (the methods are shared) — it’s wiring it into XPages: stream the exportDxl string straight to a download, or importDxl the XML a front end posted into documents — remembering the name is Dxl and checking the Log each time.

Sources

← Back to all posts