A custom DXL framework for accessing Notes/Domino data

Use Domino XML (DXL) to enable other applications to create, view, and update Notes documents in Lotus Notes/Domino 6.x. With LotusScript agents, you can view a Notes document in DXL, create a document from DXL, and update a document from DXL.

Share:

Raj Balasubramanian, Product Architect, Lotus

Raj Balasubramanian is a Consulting IT Architect for IBM Software Group. He works on customer engagements delivering application and infrastructure related projects. His interests range from anything technical to history and physics. During his copious spare time, he enjoys dating his wife and talking about robots with his sons. You can read about his technical and personal escapades on his personal blog Gurukulam.



03 May 2005

Also available in Japanese

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
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
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
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:

  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.

Figure 4. Viewing documents
Viewing documents

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.

Figure 5. Opening a document
Opening a document

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.

Figure 6. Creating a document
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.)

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


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


Download

DescriptionNameSize
Sample agents codeagents.ZIP1.52KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=82475
ArticleTitle=A custom DXL framework for accessing Notes/Domino data
publish-date=05032005