XPages 用 DXL:方法名是 createDxlExporter(不是 DXL),匯入看 DocumentImportOption
你要在 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>,方便當片段嵌進別的 XMLvar dxl = exporter.exportDxl(doc); // doc 可換成 DocumentCollection / databaseexportDxl 吃的東西很彈性:一份 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。
參考來源
- NotesDxlExporter (JavaScript)(exportDxl、OutputDOCTYPE、RichTextOption、Log)— HCL Domino 14.5 Designer Help(官方)
- NotesDxlImporter (JavaScript)(importDxl、DocumentImportOption、ImportedNoteCount、Log)— HCL Domino 14.5 Designer Help(官方)
- NotesSession (JavaScript)(createDxlExporter / createDxlImporter)— HCL Domino 14.5 Designer Help(官方)