XPages 用 DXL:方法名是 createDxlExporter(不是 DXL),匯入看 DocumentImportOption

XPages 用 DXL:方法名是 createDxlExporter(不是 DXL),匯入看 DocumentImportOption

2026.11.22 約 749 字

你要在 XPages 把一份文件、或整個 view 丟給外部系統當 XML;或反過來,把一段別人給的 XML 餵進來變成 Notes 文件。DXL(Domino XML)就是 Domino 原生的 XML 格式,而 session 兩個方向都內建好了。

但這裡第一個坑就在名字。匯出用的是 session.createDxlExporter()——注意是 Dxl,不是你直覺會打的 createDXLExporter(DXL 三個字母大寫)。大小寫打錯,SSJS 就找不到這個方法。匯入同理,是 createDxlImporter。

這篇講匯出、匯入、那個命名坑,以及匯入時最關鍵的一個選項。


匯出:exportDxl

匯出很直接:建一個 exporter,把要轉的東西丟給 exportDxl,拿回一段 DXL 字串。NotesDxlExporter 官方是「Represents the conversion of Domino data to DXL (Domino XML).」:

var exporter = session.createDxlExporter();
exporter.setOutputDOCTYPE(false); // 不輸出 <!DOCTYPE>,方便當片段嵌進別的 XML
var dxl = exporter.exportDxl(doc); // doc 可換成 DocumentCollection / database

exportDxl 吃的東西很彈性:一份 Document、一個 DocumentCollection、整個 database,甚至一個 NoteCollection 都行。幾個常調的屬性:OutputDOCTYPE(要不要輸出 DOCTYPE 宣告,嵌片段時通常關掉)、RichTextOption(rich text 要轉成 DXL 還是保留原始)、OmitRichtextAttachments(要不要省略附件,DXL 會很大)。轉完記得看 Log——它是唯讀的,把過程的警告、錯誤都收在那。拿到的 DXL 字串要給前端下載,可以接 SSJS 的 Stream 那篇 的 getContents 做法。

匯入:importDxl,以及那個決定一切的選項

匯入是把 DXL 寫回某個資料庫:

var importer = session.createDxlImporter();
importer.setDocumentImportOption(NotesDxlImporter.DXLIMPORTOPTION_REPLACE_ELSE_CREATE);
importer.importDxl(dxl, targetDb);
var n = importer.getImportedNoteCount(); // 匯進幾筆

NotesDxlImporter 官方「Represents the conversion of DXL (Domino XML) to Domino data.」,importDxl 就是「Converts DXL data to Domino data.」。但這裡最關鍵、也最容易出事的是一個屬性:DocumentImportOption。它決定匯入碰到「已經存在的文件」要怎麼辦,而預設值是 DXLIMPORTOPTION_CREATE(2)——永遠新建。也就是說,你拿同一份 DXL 匯兩次,預設行為不是覆蓋、而是多出一份重複文件。

要「有就更新、沒有才建」,得自己把它設成 DXLIMPORTOPTION_REPLACE_ELSE_CREATE(6)或 DXLIMPORTOPTION_UPDATE_ELSE_CREATE(10);只想更新既有、不新建用 ..._ELSE_IGNORE 版;完全不碰既有用 DXLIMPORTOPTION_IGNORE(1)。動手前先確定這個選項是你要的那個——預設的 CREATE 很容易在重跑時悄悄堆出重複資料。

匯完一樣看兩個東西:ImportedNoteCount(匯進幾筆)、getFirstImportedNoteID / getNextImportedNoteID(逐一拿匯進來的 note),還有 Log(哪幾筆失敗、為什麼)。DXL round-trip(匯出再匯入)本身有不少格式眉角,見 DXL round-trip 的坑那篇。

命名與 Log,兩個反覆踩的點

把這篇最實際的兩點再講一次:

  • 方法名是 Dxl 不是 DXL:createDxlExporter / createDxlImporter。這在一個全大寫慣例的 API 裡特別反直覺,打錯第一時間會以為「SSJS 沒這方法」。
  • 每次都看 Log:匯出入都是「可能部分成功」的操作——幾筆轉失敗、某個 rich text 省略了,都只會寫進 Log,不會丟例外。不看 Log,你不會知道少了什麼。

同類別在其他語言

同一組 DxlExporter / DxlImporter:

  • LotusScript:NotesDXLExporter / NotesDXLImporter(LS 這邊慣例反而是大寫 DXL),ExportDXL / ImportDXL、DocumentImportOption 都在;round-trip 的坑見 DXL round-trip 那篇。
  • Java:DxlExporter / DxlImporter,API 相同,從 session.createDxlExporter() 建,用完要 recycle。
  • SSJS 專屬的不是 API(方法共用),而是在 XPages 的接法:exportDxl 的字串直接串給下載、或 importDxl 把前端送來的 XML 落地成文件,而且要記得名字是 Dxl、以及每次檢查 Log。

參考來源

← 回到文章列表