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.

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.)

Back to top

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.

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).

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:

1. The user opens the custom client application, passing in the user ID and password. (Alternately, this can be provided in a configuration file.)
2. 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.
3. The Domino server authenticates the user and processes the request, sending XML data back to the client in the HTTP response.
4. 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.

Opening a document

The following steps occur when a client opens a Notes document in the All Documents view:

1. The user opens the All Documents view as described in the preceding section.
2. The user selects a document to open.
3. 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>.
4. 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).
5. The XML data of the DXL document is received by the custom client and processed.
6. A detailed view of the selected document is displayed to the user.

Figure 5 shows this process.

Creating a document

When a user creates a new Notes document, the following sequence occurs:

1. The user launches the client application and selects the appropriate menu option for creating a new document.
2. The user is presented with a custom document form within the application. The user completes this form and submits/saves it.
3. 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.
4. The Domino server authenticates the user and processes the agent request.
5. The XML data in the DXL document is processed by the DXLCreateDoc agent, and the return message is sent back to the client.
6. A success/failure message of the form submit action is displayed to the user.

Figure 6 displays these steps.

Back to top

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.)

[DXLViewDoc]

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

[DXLUpdateDoc]

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

[DXLCreateDoc]

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.

imp.DocumentImportOption=DXLIMPORTOPTION_CREATE
....

Back to top

Conclusion

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).

Back to top

Download

Information about download methods

Resources

• 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.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The DXL framework
• View and document DXL formats
• The custom DXL agents
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Notes and Domino Administrator
• Demo: Lotus Notes 8 composite applications
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Notes and Domino Administrator

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers