Notes/Domino 6.x includes robust tools for translating Notes data into XML, and for bringing XML data into Notes. The IBM Lotus documentation for these features is quite detailed, but it fails to provide a simple sample that shows the full operation from start to finish. This tip corrects that oversight, with a downloadable application.
How to use the sample
1. Create a test directory named c:\notes_xml\.
2. Go to your Notes 6 software directory and find the subdirectory named xmlschemas.
3. Copy this subdirectory (xmlschemas) completely to your test directory (notes_xml). You will now have a directory named c:\notes_xml\xmlschemas\, with several DTD files in it.
4. Unzip the downloaded sample and open the Notes database using Notes 6.0 (or later).
5. There is one view in the database with several documents. Examine the documents and you will notice that they contain various Notes constructs, such as attachments, embedded pictures, links and formatted text.
6. Select one of the documents.
7. Run Action/Create XML from Doc.
8. Open the document again. It should now contain a field with the name of an XML file.
9. Using Windows Explorer, you can examine the XML file. It contains an XML rendering of the complete Notes document.
10. Within Notes, select the same document again.
11. Run Action/Create Doc from XML.
12. You should see another copy of the document appear in the database. (If not, press F9 to refresh the view.) This document is the result of importing to Notes the XML file you just examined.
How Export works (Notes to XML)
The agent Create XML from Doc contains the LotusScript code that translates a Notes document into XML. The code is fairly self-explanatory, but I will highlight a few items that may not be obvious.
- The ReplicaID of the database and the NoteID of the document are used to create the filename of the XML file. This is done so that every XML file is guaranteed to have a unique name.
- The CreateDxlExporter method (of NotesSession) creates an instance of the XML exporter tool, and CreateStream (also from NotesSession) creates an I/O stream that will be used for the file output.
- The Open method (on the stream) associates a file with the stream, SetOutput (from the exporter) attaches the stream as the output of the exporter.
- The SetInput method (of the exporter) attaches the current Notes document as the input of the exporter.
- Once the above setup is done, and simple call to Process (from the exporter) does the entire XML translation.
While the usage instructions above cover the simple case for one document, the agent can actually be used to export any number of documents at once. Just select multiple documents in the view, and then invoke the action.
How Import works (XML to Notes)
The agent Create Doc from XML contains the LotusScript code that translates an XML file into a Notes document.
- Instead of creating an instance of an XML exporter, we use CreateDxlImporter to create an import tool.
- We again use the CreateStream method, but this time the stream is the input to the XML tool.
- The output of the XML importer tool is always a Notes database. There is no option to send the output to a temporary (in memory) document or to a document handle that you provide.
- Because the imported document might overwrite a previous version of the same document, the importer tool allows you to control these conflicts. This is done with the DocumentImportOption property. I set this option to DXLIMPORTOPTION_CREATE, which means to always create a new instance of the document, even if it already exists in the target database.
For more information, see Domino Designer 6 Help/Contents /XML for Domino.
Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Domino and Notes.