Domino XML (DXL) is the representation of Domino design elements in XML format using the Domino DTD located in the Notes\xmlschemas directory. (Lotus Notes/Domino 7 will also include XML schema documents.) DXL provides a great way for exposing Domino application data to other platforms. For example, DXL allows you to export and import Domino data and design elements as a form of XML. DXL was originally introduced in Lotus Domino 5 and, in more recent releases, has become part of the core of Lotus Domino. (For a good introduction to DXL, see the developerWorks: Lotus article, "Lotus Domino and IBM WebSphere integration solutions: Domino XML.")
In this article, we discuss the key components of a DXL framework created in Lotus Domino 6.5.x to view, create, and update Domino data. This framework consists of a Domino database containing three LotusScript agents for viewing, updating, and creating Notes documents. This article assumes that you're an experienced application developer with experience working with Lotus Domino and XML.
The DXL framework
Our custom DXL framework simplifies Notes object access from any client. There are multiple avenues to access Domino objects from various programming platforms. However, each access method presents unique challenges, based on a given scenario. For example, DIIOP access used by custom Java applications cannot traverse traditional firewalls where only HTTP traffic is permitted. Therefore, there are no out-of-the-box ways to create or read documents in an application-neutral way. This is why XML is a good choice. If you are building a Microsoft .Net client or a custom Java client with special requirements (such as a firewall), then our DXL framework can provide a good solution.
For example, you can use our DXL framework to build an application that allows a user to:
- View a list of Notes documents from a Notes view
- Select a document from that list and view the details of the Notes document
- Update values on that selected document
- Create a new Notes document
Figure 1 illustrates the key design elements that make up our DXL framework.
Figure 1. DXL framework
As Figure 1 shows, our DXL framework consists of a Domino database (database.nsf) that contains three LotusScript agents:
- [DXLUpdateDoc] accepts XML in the DXL format and processes the request from the client to update a selected document, given a document UNID.
- [DXLCreateDoc] accepts XML in DXL format and processes the client request to create a new document.
- [DXLViewDoc] returns XML of the selected document, given a document UNID.
We describe the inner workings of these agents later in this article. In addition, you can use the native ability of a Notes view to render XML data using the ?ReadViewEntries URL command to request the XML data from the selected Notes view.
In this article, we focus on the server-side components of our DXL framework. (To download the sample agents shown in Figure 1, go to the Downloads section at the end of this article.)
View and document DXL formats
Let's now look at how the DXL formats for a view and document are laid out. Figure 2 shows the DXL of a view.
Figure 2. DXL format for a Notes view
In Figure 2:
- Blue circles represent elements.
- Gray ovals represent attributes.
- Yellow rectangles represent character data.
- Green arrows indicate "contains one of."
- Black arrows indicate aggregation.
As Figure 2 shows, viewentries is the top level element. It contains one or more viewentry elements, which in turn contain one or more entrydata elements. Each entrydata element can have one of the following elements: text, number, datetime, and numberlist.
NOTE: In this section, we discuss the DXL viewentries element, which gives the contents of the view in DXL format. Do not confuse this with the DXL view element, which is the actual description of the view in DXL format.
The key attributes that we use during XML processing are illustrated as well. For viewentries elements, we use toplevelentries to get a count of all documents in a view. From viewentry, we get the UNID (to be stored for later use) and the columnnumber attribute from entrydata to look for the field values we need.
The following is a snippet of the view DXL code:
<?xml version="1.0" encoding="UTF-8"?> <viewentries toplevelentries="26"> <viewentry position="1" unid="F0C7DF1BE84F48B685256F0800720716" noteid="1392" siblings="26"> <entrydata columnnumber="0" name="$18"> <number>0</number></entrydata> <entrydata columnnumber="1" name="$17"> <text>Styles, Ron</text></entrydata> <entrydata columnnumber="2" name="$12"> <text></text></entrydata> <entrydata columnnumber="3" name="CompanyName"> <text></text></entrydata> <entrydata columnnumber="4" name="$16"> <text>R Styles@ABC</text></entrydata> <entrydata columnnumber="5" name="$21"> <text>NotesMail/HQ/ABC</text></entrydata> </viewentry> ...... </viewentries>
Figure 3 illustrates the Notes document DXL (in our case, a Person document in database.nsf).
Figure 3. DXL format for a Notes document
In this article, we focus on the elements and attributes shown in the preceding figure for a DXL Notes document. (We do not use the noteinfo and updatedby elements, so we excluded them from Figure 3.) As the illustration shows, document is the top level element and contains one or more item elements. In turn, each item element can have one of the following elements: text, number, datetime, numberlist, and textlist. The key attribute for the item element is name and is used to check for the field values we are interested in.
The following is a snippet of an example document's DXL code:
<?xml version='1.0' encoding='utf-8'?> <!DOCTYPE document SYSTEM 'xmlschemas/domino_6_5_1.dtd'> <document xmlns="http://www.lotus.com/dxl" version='6.5' maintenanceversion='1.0' replicaid='85256F080071E637' form='Person'> <noteinfo >......</noteinfo> <updatedby>......</updatedby> <item name='Title'><text/></item> ...... <item name='Owner' authors='true' names='true' protected='true'><text> CN=Ron Styles/OU=HQ/O=ABC</text></item> </document>
Opening a view
Now that we have an understanding of the DXL formats for the view and the document, let's look at the internal sequence of events that occurs when a client views a list of documents in our sample database's All Documents view:
- The user opens the custom client application, passing in the user ID and password. (Alternately, this can be provided in a configuration file.)
- The client application creates an HTTP request to the Domino server against the target database view, using the ?ReadViewEntries query string. In this case, the view is our sample All Documents view, showing all the documents in the example database.
- The Domino server authenticates the user and processes the request, sending XML data back to the client in the HTTP response.
- The client application processes the XML data received from the server and displays the list of documents in the All Documents view.
Figure 4 illustrates this process.
Figure 4. Viewing documents
Opening a document
The following steps occur when a client opens a Notes document in the All Documents view:
- The user opens the All Documents view as described in the preceding section.
- The user selects a document to open.
- The client application obtains the UNID of the selected document and sends an HTTP request to the Domino server against the target database with a URI of /ViewDXLDoc?Open&unid=<doc UNID>.
- The Domino server processes the request, authenticating the user and processing the agent request, which outputs the DXL format of the document (whose UNID was sent in the request).
- The XML data of the DXL document is received by the custom client and processed.
- A detailed view of the selected document is displayed to the user.
Figure 5 shows this process.
Figure 5. Opening a document
Creating a document
When a user creates a new Notes document, the following sequence occurs:
- The user launches the client application and selects the appropriate menu option for creating a new document.
- The user is presented with a custom document form within the application. The user completes this form and submits/saves it.
- The application extracts the form data and formats it into XML (conforming to DXL document format) and invokes the DXLCreateDoc agent. This sends the DXL content in the HTTP request.
- The Domino server authenticates the user and processes the agent request.
- The XML data in the DXL document is processed by the DXLCreateDoc agent, and the return message is sent back to the client.
- A success/failure message of the form submit action is displayed to the user.
Figure 6 displays these steps.
Figure 6. Creating a document
The custom DXL agents
In this section, we examine how our [DXLViewDoc], [DXLUpdateDoc], and [DXLCreateDoc] LotusScript agents work internally. These agents are critical components of our DXL framework. We examine code snippets for each agent, explaining what each snippet is doing. (To download the full code for these agents, go to the Downloads section.)
The [DXLViewDoc] agent returns the XML of a selected document. This agent begins by setting up the standard variables. We get the document object using the session document context method. Response to the HTTP request is handled using standard print statements. The first thing we do is initialize the response content type to text/xml. We also catch any errors.
Sub Initialize Dim s As New notessession Dim db As notesdatabase Dim doc As notesdocument Dim doc1 As notesdocument Set doc1 = s.DocumentContext Print "Content-type: text/xml" On Error Goto err1 Set db = s.currentdatabase Dim stg As String
We then look for the UNID passed-in via query string of the requesting URL with minimal error checking.
stg = doc1.Query_String(0) If Len(stg) < 5 Then Goto err1 End If If Instr(stg,"unid=") < 1 Then Goto err1 Else stg = Right(stg,Len(stg)-Instr(stg,"=")) End If
After we have a valid UNID, we get a handle to the Notes document and export the content to XML using the NotesDXLExporter, ensuring that there are no DTD requirements set as part of the XML.
Set doc = db.GetDocumentByUnID(stg) Dim exporter As NotesDXLExporter Dim stream As notesstream Set exporter = s.CreateDXLExporter exporter.OutputDOCTYPE=False Set stream = s.CreateStream Call exporter.SetInput(doc) Call exporter.SetOutput(stream) Call exporter.Process
We then get the text from the stream object and output it to the client.
Print stream.ReadText() End err1: Print "You reached in error" Resume End Sub
The [DXLUpdateDoc] agent processes client requests to update a selected document. We use the Request_Content attribute of the request to get a handle on the actual XML sent by the client and to pipe it to the stream object.
Dim x As NotesItem Dim stream As NotesStream Set x =doc.GetFirstItem("Request_Content") ........... ..... Call stream.WriteText(x.Text)
We then instantiate NotesDXLImporter to consume the stream within the database context and specify that this import is an update (and not a create).
Dim imp As NotesDXLImporter Set imp = session.CreateDXLImporter(stream, db) imp.DocumentImportOption=DXLIMPORTOPTION_UPDATE_ELSE_IGNORE imp.ReplicaRequiredForReplaceOrUpdate = False Call imp.Process
The [DXLCreateDoc] agent processes client requests to create a new document. This agent closely resembles DXLUpdateDoc agent. The major difference between these agents is that during the process of consuming the stream within the database context, we specify that this import is a creation type so that a new document can be created.
In this article, we described how you can leverage the DXL features offered in Lotus Notes/Domino 6 and later to create a framework for viewing and updating existing Notes documents using custom LotusScript agents. This framework is designed to simplify access to Notes objects. It uses XML rather than HTML and is, therefore, simple to process by any application that knows how to deal with XML. Because it is transmitted over HTTP, it is firewall friendly.
The goal of this article is to prepare you to design applications to access and process Domino data using the DXL framework we have described. You can use this framework when designing applications for both the Web (JSR168 portlets) and the rich client (Eclipse RCP).
|Sample agents code||agents.ZIP||1.52KB|
- For a good introduction to DXL, see the developerWorks: Lotus article, "Lotus Domino and IBM WebSphere integration solutions: Domino XML."
- The developerWorks: Lotus articles, "LotusScript: XML classes in Notes/Domino 6" and "LotusScript: More XML classes Notes/Domino 6," offer addition information about working with DXL.
- Get involved in the developerWorks community by participating in developerWorks blogs.
- Browse for books on these and other technical topics.