The XML representation of Lotus Domino data is known as DXL. DXL describes Lotus Domino-specific data and design elements such as views, forms, and documents. As XML becomes the standard basis for exchanging information, DXL provides a basis for importing or exporting XML representations of data to and from a Lotus Domino application. DXL is an adaptation of XML used to describe, in detail, the structure and data contained in a Lotus Domino database.

The structure of DXL is described by the Lotus Domino document type definition (DTD) file, which can be found under the Lotus Notes installation path by default, such as IBM/lotus/notes/xmlschemas. The DTD contains the definitions of the XML tags that you can use to validate your XML documents while converting external XML data into Lotus Domino databases or to understand any XML documents produced while exporting internal Lotus Domino databases into XML.

The entities and elements that make up the Domino DTD are these:

• Core entities. Entities that function as data type categories, such as binary, Boolean, float, hex, integer, notesid, and unid.
• Common entities. Entities referenced in other entities or in more than one element, such as acl.levels, color, image.formats, length, and pixel.
• Lotus Domino elements. All the elements in the Lotus Domino DTD. They represent the types of data stored in a Lotus Domino NSF database or NTF template. The main Lotus Domino elements are listed in table 1.

Back to top

Database elements

The database element is an important element in the DXL file. Figure 1 provides a visual display of the database element in the XML schema. It contains some attributes and subelements. The attributes describe the database itself, such as title, version, path, and replicaid The subelements include two types:

• Subelement that is relevant to the database itself, such as databaseinfo, acl, fulltextsetting, and launchsetting.
• Subelement that is contained in the database element, such as note, document, form, subform, page, view, folder, and agent.

Back to top

Using DXL

During application development, you can use Java™ or LotusScript® to manipulate DXL. They provide functions to do the following:

• Import DXL to the database or template, and export the database or template from DXL
• Process DXL stream or file

Back to top

Using DXL with Java

The DxlExporter class converts Lotus Domino data to DXL. Use the createDxlExporter method in session to create a DxlExporter object. Use the exportDxl method to perform the export operation. Input to exportDxl can be a Database, Document, DocumentCollection, or NoteCollection object. Output is a String object.

The DXLImporter class converts DXL to Lotus Domino data. Use the createDXLImporter method in session to create a DxlImporter object. Input to DxlImporter can be a String, Stream, or NotesRichTextItem object. Output is a Database object.

Lotus Domino Designer also includes the XML4J parser and LotusXSL processor in the product that can be used to access XML representations of objects, parse and transform the XML data, and generate XML representations of a document through the properties and methods in the Java back-end classes.

Back to top

Using DXL with LotusScript

The NotesDXLExporter class converts Lotus Domino data to DXL. Use the CreateDXLExporter method in NotesSession to create a NotesDXLExporter object. Input to an export process can be a NotesDatabase, NotesDocument, NotesDocumentCollection, or NotesNoteCollection object. Output can be a NotesStream or NotesRichTextItem object, or any of the other XML processors.

The NotesDXLImporter class converts DXL to Lotus Domino data. Use the CreateDXLImporter method in NotesSession to create a NotesDXLImporter object. Input to an import process can be a string, a NotesStream or NotesRichTextItem object, or any of the other XML processors. Output is a NotesDatabase object.

NotesDOMParser and NotesSAXParser can be used to parse DXL. NotesDOMParser parses DXL into a standard Document Object Model (DOM) tree. Additional NotesDOM classes let you work with DOM trees. NotesSAXParser processes DXL as events using a Simple API for XML (SAX) parser.

Back to top

Use cases and solution

In the workflow system, there are many use cases that need the customization of the user’s database or template. Sometimes, it is impossible to find one proper interface from the Notes Java API or LotusScript to directly add or modify the database or template. DXL can help solve such difficult problems; it can help add design elements or modify any existing design elements and their attributes. Next, we discuss several use cases and the DXL-related solutions that you can use to facilitate practical development.

Back to top

Use case 1: Add an agent into the existing database

As you know, the user’s database is inherited from the shared template in one organization. By modifying the shared template and adding an agent in Lotus Domino Designer, the function related to the agent can be added. This method, though, has some limitations:

• The adding of the agent is static and is not up to the preference setting of users.
• The agent is added to all users’ databases, and the function is visible to all users.

To solve this problem so that only specific users can use the function, you can use a DXL technique to dynamically add agents into the existing database of specific users. The scenario could be that the administrator drafts one email that includes one hotspot and one DXL file, then sends that email to specific users. After these users receive this email, they can click the hotspot and add the agent.

First, let's look at the contents of the hotspot and the DXL file, as shown in listings 1 and 2.

1 Sub Click(Source As Button)
 2  Dim session As New NotesSession    
 3  Dim stream As NotesStream
 4  Dim importer As NotesDXLImporter
 5  Dim curdirname As String  
 6  
 7  REM Set current database  
 8  Set db = session.CurrentDatabase  
 9  curdirname = Curdir()  
10  
11  Dim workspace As New NotesUIWorkspace
12  Dim uidoc As NotesUIDocument
13  Dim doc As NotesDocument
14  Dim db As NotesDatabase
15  
16  REM Get the DXL file from current document
17  Set uidoc = workspace.CurrentDocument
18  Set doc= uidoc.Document
19  Set rtitem = doc.GetFirstItem("Body")   
20  
21  Forall eo In rtitem.EmbeddedObjects         
22    Call eo.ExtractFile( curdirname + eo.source )          
23  End Forall        
24  
25  REM Open DXL file
26  Set stream = session.CreateStream
27  If Not stream.Open(curdirname + "AddMyAgent.dxl") Then
28    Msgbox "Cannot open AddMyAgent.dxl", , "Error"
29    Exit Sub
30  End If
31  If stream.Bytes = 0 Then
32    Msgbox "File did not exist or was empty", , "Error"
33    Exit Sub
34  End If  
35  
36  REM Import DXL into new database
37  Set importer = session.CreateDXLImporter
38  importer.ReplaceDBProperties = True
39  importer.ReplicaRequiredForReplaceOrUpdate = False
40  importer.ACLImportOption = DXLIMPORTOPTION_REPLACE_ELSE_IGNORE
41  importer.DesignImportOption = DXLIMPORTOPTION_CREATE
42  Call importer.Import(stream, db)
43  
44  REM Sign agents with current user
45  Call db.sign(DBSIGN_DOC_AGENT)
46  Call stream.Close
47 End Sub

This procedure is written in LotusScript. It can also be written in Java. From line 16 to line 23, it detaches the DXL file from the email into disk. From line 25 to line 42, the DXL file is read into the stream and imported into the database. After line 42, the new agent named MyAgent can be added into the user’s database. In line 45, you sign the agents with the current user so that the agents can run correctly.

<?xml version="1.0"?>
<database>
<launchsettings>
<noteslaunch whenopened="openframeset" frameset="MailFS"/>
  </launchsettings>
  <agent name="MyAgent" alias="MyAgentAlias" hide="v3" publicaccess="false" 
  designerversion="7" noreplace="true">
    <noteinfo noteid="20a" unid="720F0C26242BEBBD8825741F004932A3" 
    sequence="19">
      <created>
        <datetime dst="true">20080402T061930,91-07</datetime>
      </created>
      <modified>
        <datetime dst="true">20080901T151520,50-07</datetime>
      </modified>
      <revised>
        <datetime dst="true">20080901T151520,49-07</datetime>
      </revised>
      <lastaccessed>
        <datetime dst="true">20080901T151520,49-07</datetime>
      </lastaccessed>
      <addedtofile>
        <datetime dst="true">20080402T061930,91-07</datetime>
      </addedtofile>
    </noteinfo>
    <updatedby>
      <name>CN=Administrator/O=ibm</name>
    </updatedby>
    <designchange>
      <datetime dst="true">20080901T151520,48-07</datetime>
    </designchange>
    <trigger type="actionsmenu"/>
    <documentset type="runonce"/>
    <code event="options">
      <lotusscript><![CDATA[Option Public]]><![CDATA[]]>
      </lotusscript>
    </code>
    <code event="initialize">
      <lotusscript><![CDATA[
       Sub Initialize
             Dim workspace As New NotesUIWorkspace
             Dim session As New NotesSession
             MsgBox "MyAgent", , "MyAgentTitle" 
       End Sub]]>
</lotusscript>
    </code>
    <rundata processeddocs="0" exitcode="0">
      <agentmodified>
        <datetime dst="true">20080901T151520,48-07</datetime>
      </agentmodified>
    </rundata>
    <item name="$POID">
      <datetime>20080328T172442,06+08</datetime>
    </item>
  </agent>
</database>

After reopening the database, the user can see the new agent named MyAgent in the action menu, as shown in figure 2. In the bottom right of the window is the preview of the received mail from the administrator that contains the hotspot and the DXL file. In addition to the agent design element, any other design element can be imported into the database or the template as shown in figure 3. In this DXL file, the agent, view, and imageresource design elements are included. After importing this file to the database, two agents, two views, and four GIF resource files can be added to the database.

Back to top

Use case 2: Modify the property in the database

Notes Java API and LotusScript provide many methods to access the property of the database and its subset, but not all the properties can be modified by these methods. To solve this problem, you can choose the DXL technique. All data and design elements can be represented in the DXL file. You can modify the value of property in the DXL file and then import the modified DXL file into the database. Thus, the property in the database can be modified.

Let's take a look at one simple example. If you want to change the launch property of the database, you can choose the DXL-related technique to implement it.

Table 2 lists the options that you have when you open the database in the Lotus Notes client. If you want to have a frameset display automatically, such as MailFS when you open a Lotus Notes database, you can import the Modifydatabaseproperty DXL file shown in listing 3.

<?xml version="1.0"?>
<database>
<launchsettings>
<noteslaunch whenopened="openframeset" frameset="MailFS"/>
  </launchsettings>
</database>

Back to top

Use case 3: Modify the default event processing function of the database

When you work with Lotus Notes design elements, Lotus Notes tracks their operations as events (for example, opening a database, opening a view, or opening a document). As far as the database is concerned, the event processing functions are saved under the code element of the databasescript element, which belongs to the database element as shown in figure 4.

Database events pinpoint database-wide activities, such as opening and closing a database or deleting and undeleting documents. These are some examples:

• PostOpen. Opens a specific view to direct users to action items.
• QueryDocumentDelete. Prevents users from deleting a particular document when the value of a status field on an action item is open.
• PostDocumentDelete. Archives a deleted document.
• QueryClose. Prevents users from closing a database when there are still action items in the action item view assigned to them.

By modifying the PostOpen procedure, you can change the default behavior for the database open event. For example, you can add one welcome window so that the welcome window can show up when the user opens the database by using the DXL technique instead of using Lotus Domino Designer. The advantage of using the DXL technique is that the logic used to modify the PostOpen procedure can be encapsulated in one hotspot or one button. Users can apply this change by clicking a button instead of manually opening Lotus Domino Designer to make the modification.

To modify the PostOpen procedure, you need to export the existing PostOpen first. You can do this step using the DXL exporter and the SAX parser. The DXL exporter is used to export the databasescript element into the DXL stream; see line 19 to line 54 in listing 4. Then the SAX parser is used to parse the DXL stream and navigate the code elements in the databasescript element, as shown in line 77 to line 164. If it happens to process the PostOpen code, the code snippet for displaying welcome windows can be inserted into the existing PostOpen procedure, as shown in line 124 to line 141. Finally, you can use the DXL importer to import the updated DXL file into the database, as shown in line 57 to line 73.

  1 (Declarations)
  2 Dim isPostOpenEvent As Boolean
  3 Dim isPostOpenCode As Boolean
  4 Dim isCode As Boolean
  5
  6 Sub Initialize
  7  
  8  Dim session As New NotesSession
  9  Dim db As NotesDatabase
 10  Dim streamIn As NotesStream 
 11  Dim streamOut As NotesStream
 12  Dim dxlExporter As NotesDXLExporter 
 13  Dim dxlImporter As NotesDXLImporter
 14  Dim saxParser As NotesSAXParser 
 15  
 16  REM get current database
 17  Set db = session.CurrentDatabase
 18  
 19  REM Create DXL exporter
 20  Set dxlExporter = session.CreateDXLExporter
 21  
 22  REM Create the stream that will store the DXL
 23  Set streamIn = session.CreateStream 
 24  Call streamIn.Truncate
 25  Set streamOut = session.CreateStream
 26  Call streamOut.Truncate
 27  
 28  REM Create note collection
 29  Dim nc As NotesNoteCollection
 30  Set nc = db.CreateNoteCollection(False)
 31  nc.SelectDatabaseScript = True  
 32  Call nc.BuildCollection
 33  
 34  REM Export note collection as DXL  
 35  Set dxlExporter = session.CreateDXLExporter(nc)
 36  dxlExporter.OutputDOCTYPE = True
 37  
 38  filename$ = "c:\" & Left(db.FileName, Len(db.FileName) - 3) & "xml"
 39  If Not streamIn.Open(filename$) Then
 40    Messagebox "Cannot open " & filename$,, "Error"
 41    Exit Sub
 42  End If
 43  streamIn.Truncate
 44  
 45  REM Create the SAX Parser, the results of the parse will be 
       pushed into stream (streamIn)
 46  Set saxParser = session.CreateSAXParser(dxlExporter, streamIn)
 47  On Event SAX_Characters From saxParser Call SAXCharacters
 48  On Event SAX_EndElement From saxParser Call SAXEndElement
 49  On Event SAX_StartDocument From saxParser Call SAXStartDocument
 50  On Event SAX_StartElement From saxParser Call SAXStartElement
 51  
 52  REM Initiate parsing, by doing this the SAX events are called
 53  REM It is in there that the DXL is rewritten and the 
       PostOpen() method was modified.
 54  Call dxlExporter.Process()  
 55  streamIn.Close  
 56  
 57  REM Open xml file named after current database 
 58  If Not streamOut.Open(filename$) Then
 59    Messagebox "Cannot open " & filename$,, "Error"
 60    Exit Sub
 61  End If
 62  If streamOut.Bytes = 0 Then
 63    Messagebox "File did not exist or was empty",, filename$
 64    Exit Sub
 65  End If
 66  
 67  REM Import DXL into new database
 68  Dim importer As NotesDXLImporter
 69  
 70  Set importer = session.CreateDXLImporter(streamOut, db)
 71  importer.ReplaceDBProperties = ture 
 72  importer.DesignImportOption =DXLIMPORTOPTION_REPLACE_ELSE_CREATE 
 73  Call importer.Process
 74  
 75 End Sub
 76
 77 Sub SAXStartDocument (Source As Notessaxparser)
 78  REM Write DXL header
 79  Source.Output("<?xml version='1.0'?>" & Chr(10))  
 80 End Sub
 81
 82 Sub SAXStartElement (Source As NotesSAXParser,_
 83 Byval strElementName As String, Attributes As NotesSaxAttributeList)  
 84  
 85  Dim i As Integer  
 86  REM Open Element
 87  Source.Output("<" & strElementName) 
 88  If Attributes.Length > 0 Then
 89    For i = 1 To Attributes.Length
 90      REM Get the name and value of the attribute
 91      strAttrName = Attributes.GetName(i)
 92      strAttrValue = Attributes.GetValue(i)     
 93      REM Check whether current element is code
 94      If strElementName = "code" Then
 95        bCode = True
 96        If  strAttrName = "event" Then          
 97          If strAttrValue = "postopen" Then
 98            REM found postopen event
 99            bPostOpenEvent = True           
100          End If
101        End If                  
102      End If                
103               REM Write the attribute
104      Source.Output(| | & strAttrName & |="| & strAttrValue & |"|) 
105    Next        
106  End If
107  
108  If strElementName = "lotusscript"  And bPostOpenEvent  Then
109    REM found postopen code
110    bPostOpenCode = True
111  End If
112  
113     REM Close the element tag here
114  Source.Output(">")  
115 End Sub
116
117 Sub SAXCharacters (Source As Notessaxparser, Byval Characters As String, _
118 Count As Long)
119  
120  If  isCode Then
121    Source.Output("<![CDATA[")    
122  End If  
123  
124  If (isPostOpenCode)  Then
125    REM insert code into this place
126    Dim header As String
127    Dim pos As Integer
128    Dim newchar As String
129    
130    header = "Notesuidatabase"
131    pos = Instr(Characters,header)
132    
133    If (pos = 1) Then
134      REM at the begining 
135    Else    
136      REM found the patten, and insert the code
137      newchar = Left(Characters, pos+16)        
138      newchar = newchar + Chr(13) + "Msgbox" + Chr(34) + "Welcome"+ Chr(34) + Chr(13)
139      newchar = newchar + Mid(Characters, pos+ 17)      
140    End If    
141    Source.Output(newchar)
142  Else 
143    Source.Output(Characters) 
144  End If
145  
146  If  bCode Then
147    Source.Output("]]>")    
148 End If
149  
150 End Sub
151
152 Sub SAXEndElement (Source As NotesSAXParser, Byval ElementName As String)
153  
154  REM Terminate the element
155  Source.Output("</" & ElementName & ">" & Chr(10))
156  
157  If ElementName = "lotusscript"  And isPostOpenEvent  Then
158    isPostOpenCode = False
159    isPostOpenEvent = False
160  Elseif elementName = "code" Then
161    isCode = False
162  End If
163  
164 End Sub					

Thus, the behavior for the database open event is changed, and one welcome window displays when the database is opened.

Back to top

Conclusion

In this article, we introduced the concept of Domino XML Language (DXL) and showed how to use DXL. We detailed several use cases and solutions with the DXL technique that you can use to facilitate practical development. Although these examples are simple, they demonstrate the powerful use and expansibility of DXL.

Resources

Learn

• Get started with IBM Lotus Notes and Domino V8 technical content.
  
  
• Read the developerWorks® article, "What's new in IBM Lotus Notes and Domino V8."
  
  
• Read the "Lotus Notes and Domino 8 Reviewer's Guide."
  
  

Get products and technologies

• Download a trial of IBM Lotus Domino.
  
  
• Download a trial of IBM Lotus Notes, Domino Designer, and Domino Administrator clients.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Database elements
• Using DXL
• Using DXL with Java
• Using DXL with LotusScript
• Use cases and solution
• Use case 1: Add an agent into the existing database
• Use case 2: Modify the property in the database
• Use case 3: Modify the default event processing function of the database
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
• Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into Lotus on developerWorks

Cloud computing for developers

Virtual workshop: Learn how to build a cloud infrastructure and develop/deploy cloud-based applications. (6-8 Apr 2010)

Special offers