Table of contents | Next | Previous

Click to view this article in PDF Format

Introduction to Quickr for Domino Architecture (Quickr-D)

The objective of this article is to introduce the Quickr-D Architecture to allow developers of all levels to customize and interact with Quickr-D server.

Before you begin to customize a Quickr Place , you should have a basic understanding of the Lotus Quickr services for Domino architecture. Despite the many similarities with Domino Server, Quickr-D has its own object model and metaphors. Quickr uses the Domino data structures and is implemented using core domino technologies. Accordingly, when talking about Quickr-D architecture is important to first talk about Domino server architecture. The picture below illustrates some of the elements that constitute the Domino Server.

Figure 1 – Simplified Domino Server Architecture

Domino Server Tasks are responsible for implementing all the functions that a Domino server performs. We can group server tasks into five categories:

• Tasks that maintain Notes applications ( Agent Manager, Cataloger, Designer, Replicator, etc);
• Tasks that monitor server and administration activities ( Administration Process, Cluster Replicator, etc);
• Tasks that manage mail, calendars, and scheduling ( Calendar Connector and Schedule Manager, IMAP, POP3, SMTP Listener, Router, etc);
• Tasks that manage protocols (HTTP service, DIIOP, LDAP, etc);
• Tasks that monitor server activity ( Activity Trends Collector, iSPY, Statistics, etc).

Notes Object Services is a set of cross-platform C/C++ functions that create and access data and files. They are also responsible for compilation and interpretation of formulas and scripts (Notes Formula, LotusScript ®, Java and JavaScript . Interacting with all domino server tasks are Notes Object Services (NOS). It is s also responsible to interface with operating system services. NOS can be customized using C-language callback functions. Another way of thinking about this is to equate NOS as the glue that maintains all Notes/Domino elements together. To learn more about the C/C++ API toolkit take a look at the following documentation found in this article:

http://www.ibm.com/developerworks/lotus/documentation/?OpenDatabase

The shared databases and local files consist of database files, templates, static html files, java script files, servlets and other elements. A Notes database is a collection of documents; each document is a collection of fields. These elements are commonly called notes. Every note represents an element in a Notes database.

Extrapolating further from the diagram shown in picture 1, it is possible to see where the main Quickr services are inserted. The Quickr engine is an extension of the Domino HTTP process, and when the HTTP task is started, it automatically starts the Quickr services and loads the JVM. The HTTP task writes status messages for these operations to the server console and log file. This is illustrated in Figure 2.

Figure 2 – IBM Lotus Quickr services for IBM Lotus Domino

Behind the scenes of the Quickr UI

From an end-user perspective, the Quickr focus is on the user experience. It provides an intuitive and customizable UI to serve as a collaborative knowledge and document repository, independent of infrastructure and interoperability with other repositories.

Behind the scenes, Quickr has somewhat of a ‘double identity' that can be addressed using known Domino structures, such as Databases, views, agents, or using the qptool commands, Quickr Java API, servlets, WEB Services an others. The diagram shown in Figure 3 below provides an overview of Quickr Architecture.

Figure 3 – Overview of the Quickr D Architecture

Because Lotus Quickr-D objects are based on Domino objects, you can use the Notes client and Domino Designer to view, customize, and create new objects in a Quickr place. All the data for objects in a Quickr place are contained in database notes. Its possible interact with Quickr-D server using Quickr-D Java API, there are three ways to do this :

• Creating an XML input file and run it against the Quickr-D command line or Domino server console;
• Write a Java program that creates the XML and passes it to the Quickr-D processor programmatically using QPAPI class;
• Using the QPTool execute command used on administrative tasks.

Examining Quickr from a ‘Domino-centric' technology perspective, it is possible to find some elements common to typical Domino application, such as a subset of Domino security and authentication model, the utilization of Notes databases, views, documents in conjunction with Ajax approach to render the web interface.

Table 1 below shows the correlation between Lotus Quickr objects and Domino objects. 

Table 1. Relationship between Lotus Quickr-D and Lotus Domino objects

When the directory tree of the Domino server is inspected, it reveals the following information shown in Table 2:

Table 2. Quickr services for Domino file directory structure

Building a scene

In most cases, the first user contact with Quickr is through a web browser. In order to render that scene, several elements are invoked in sequence from a collection of code pieces read from the template files, application of a skin, and place data. Rendered together, these produce the final result as a scene. A scene can be considered as a browser-visible and usable version of a state of content.

How a scene is rendered by Quickr Server

As mentioned earlier, Quickr uses the web page generation capabilities provided by core Domino. For example, the URL http://www.itsomillenia.ibm.com /LotusQuickr/itsomillenia/Main.nsf will be used as base URL. When a URL command is received by the Domino web server the following steps occurs:

• Browser (HTTP) request is submitted: …/?OpenDocument&Form=h_PageUI;
• Domino HTTP server task receive the request and inspects the URL searching for /LotusQuickr/ token;
• If URL contains token, request is passed to Quickr that inspect searching for a know command like ?OpenDocument
• Quick processor opens form named in URL: &Form=h_PageUI from HaikuCommonForms.ntf;
• Quickr processes the form by resolving Quickr tags within the form amd all subforms, requesting all files involved with the current scene (gifs, html, JavaScript, stylesheets, etc) ;
• When all tags are resolved, Quickr processor delivers this information to Http server that renders the webpage.

The HaikuCommonForms.ntf template is a central repository for forms used by all templates. Using a centralized database reduces the overhead in a Lotus Quickr service, allowing for smaller databases, faster creation of a place, and better performance resulting from more efficient server caching.

Basically, this is the mechanism to render every scene on Quickr. When other types of documents or folders are requested, for example tasks, security control documents, a slightly different scene composition will occur. One very helpful tool to observe the files dependencies and relationship is Paros Proxy. (You can research this tool further at http://www.parosproxy.org/index.shtml ) This tool allows you to follow the entire request of a URL, showing the post and get commands, JavaScript, CSS and graphical files. The picture below ( Figure 4) illustrates how this can be helpful - in the left picture, you the Quickr-D initial screen, while in the right picture we have the elements used to render the initial screen scene.

Figure 4 – Elements used to render the initial screen

Quickr data notes

When you create a place, you are actually creating several Notes databases (NSF files). Databases are created from Notes templates (NTF files). When a new place is created the following databases are created:

• Main.nsf - stores main settings like user documents, folder design element, form design, field design, pages and elements used as containers of code. All other databases in the place's folder are child rooms of the place database;
• Contacts1.nsf - stores list of who has access to place and sub rooms creating one document per place member;
• Search.nsf – contains the default search forms.

The database PageLibraryxxxxxxx.nsf is created on-demand and has a similar structure that Main.nsf. PageLibrary has security and authentication features so that access to a room can be limited to a subset of team members. The picture bellow shows the databases and some of the elements that are used to compose our sample Millennia Place .

Figure 5 – Overview of Millennia Place structures and scene elements

If you simultaneously open the Main.nsf database using the Notes client, while also opening the Millennia place from a web Browser, it is possible to see the documents that represents the Quickr structures (Home, Discussion, Library, Calendar, Tasks, Index, Members, etc). The Domino forms are not used in the same way as a normal Domino Web Application. The System views are used as a mechanism of indexing files or to present the elements in the right order. For example, in the two illustrations below, we can see the Table of content view from web perspective and from a Notes client perspective.

Figure 6a - The place viewed from a web browser

Figure 6b - main.nsf database of Millennia Place

Now let's compare the left menu of Millennia place with the TOC view on client side.

Figure 7 - Menu of the Millenia Place - vs. View of the Documents which comprise the TOC

Upon opening the Home document it is also possible to see some of the fields used to build the entire scene. It is possible build an entire place just creating the documents using LotusScript for example. Keep in mind that when you work with scripts which modify these documents directly, you must be careful about what values are inserted into the fields. A wrong parameter inserted in a field such as h_Type can break the relationship between all elements of scene, causing your Quickr place to become unavailable to the end user.

Figure 8 – Field parameters

Quickr data notes characteristically have the actual data presented on the page (within the PageBody item), as well as several system items ( h_* items ) which identify things such as:

• which scenes to use to present these data,
• the folder where this note appears in,
• the abstract version of this note,
• whether it is in the Table Of Contents (TOC), and if so, the position within the TOC.

Figure 9 – details of field parameters

Some data notes are just references to a folder or another database. These notes also contain various system items ( h_* items ) identifying additional Quickr related details about the folder or room allowing a creation of a fake relationship similar to relational databases. To create or modify a document it's recommended do the same action, then manually comparing the fields that changed. To verify these changes, open the View named QDK from within Lotus Notes Designer and verify the field names. Note that a good tool to compare the different states of a document is the Compare Documents database founded on openNTF web Site. This can be found at http://www.openntf.org/internal/home.nsf . It is also possible to construct a script that compares the documents item by item. All screenshots shown below were taken from the sample Quickr Place used in this wiki - ITSO Millennia place. Note – the details about how to customize a place are covered in other sections and articles within this Wiki. For the sake of the example, the same document will be shown in draft status and published status.

Figure 10 - First Page – draft

Opening the Database on Notes Client it's possible to locate the document on QDK view.

Figure 11 – Looking at the document in QDK view

After the document is checked in, it is possible to compare the two states of the same document.

Figure 12 – comparing the states of the same document

Pasting the documents in the Compare database it is possible see what is different.

Figure 13 – once pasted in the comparing the states of the same document

The document 1 is the document in draft mode , while in document 2 , this represents the document in its published state.

Figure 14 – comparing document results

Figure 15 – Changed fields

Analysis of the changed fields

In this case, the fields h_lastTimePutAway and h_PageCmd were changed. These changes are indications to the Quickr engine which elements must be picked to render the scene.

Conclusion

IBM Lotus Quickr for Domino servers presents a huge set of tools to maximize collaboration between persons, teams and organizations. The end users, with different skill levels, can work, customize and expand Quickr, extracting the best to their daily activities. The fusion of the best of Domino technology and WEB patters gave to Quickr-D the capacity to interact with other products through Rest, Java API, Lotus Script, SOAP and other where the imagination is the limit.

References Used

The following references were used in writing this article

• “Architectural Styles and the Design of Network-based Software Architectures” : Roy Fielding's doctoral dissertation
• Rest http://en.wikipedia.org/wiki/Representational_State_Transfer
• “Inside Notes” - http://www-12.lotus.com/ldd/doc/uafiles.nsf/docs/inside-notes
• IBM Lotus Quickr Infocenter - http://publib.boulder.ibm.com/infocenter/lqkrhelp/v8r0/index.jsp