Introduction to the Quickr Domino Architecture

Introduction to the Quickr Domino Architecture

                                  Guilherme Carvalho Velloso Costa

1.1 - 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 Picture 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
   Lotus Quickr           Domino Object                       Description
      Object

Place                File System Directory         Organizes pages in rooms and folders. It’s created
                                                   from a Place Type. Each Place resides in a Notes
                                                   data directory subdirectory and has at least 3 Notes
                                                   Dbs (main.nsf, contacts1.nsf and Search.nsf).
Place Type           Database template (.ntf)      The structure and design used to create a particular
                                                   type of place. For example, the default place is
                                                   Main.nsf, which is created from the
                                                   MeetingRoom.ntf template. MeetingRoom.ntf is a
                                                   PlaceType
Room                 Domino Database               A room contains folders and forms and can contain
                                                   other rooms (actually called as page libraries). The
                                                   access control can be inherited from the place or
                                                   defined at room level
Folder               Domino Folder or View         An organizing structure for collecting and displaying
                                                   related pages or pages properties in a site.
Page                 Domino Form + Subform +       The basic vehicle for content. You can create content
                     Data Note (metadata)          using Web clients, connectors, services.
Member               Domino Data Note              A member note contains information about a team
                                                   member of a place. In addition to this data, the
                                                   member must be listed in the ACL of main.nsf and in
                                                   a group in names.nsf to pass authentication.
Form                 Data note of type             Manages the display of data notes. A form can
                     ″h_Form″                      contain fields for containing data and employ scripts
                                                   to process and compute data.
Field                Data note of type ″h_Field″   Allow for user input of data into data notes.
PlaceBot             Domino agent                  Can be written I Java or LotusScript. Run on
                                                   schedule basis or on form events
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:

Subdirectory                                               Content
domino_data_root\LotusQuickr\AreaTypes                     Contains the templates used to create places and
                                                           rooms.
domino_data_root\LotusQuickr\lotusquickr                   The home place for the server where the user
                                                           sees their places and can create new places.
                                                           Also contains the administrator place . .
domino_data_root\LotusQuickr\PlaceName                     Contains the files of a particular place, main.nsf,
                                                           contacts1.nsf, search.nsf and room files.
domino_data_root\domino\html\                              Directory that contains all static domino html
                                                           files and also the Quickr connector install kit.
domino_data_root\domino\html\qphtml\                       The directory where most Quickr-D files are
                                                           found including Dojo, Java Scripts common to
                                                           all places and files to format the exhibition of
                                                           Quickr-D Admin Console.
domino_data_root\domino\html\qphtml\skins                  The directory where CSS, gif, html and
                                                           JavaScript files.
domino_data_root\data\domino\html\qphtml\skins\quickr81    Default Quickr-D theme.

Table 2. Quickr services for Domino file directory structure

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

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

    1. Browser (HTTP) request is submitted: …/?OpenDocument&Form=h_PageUI;
    2. Domino HTTP server task receive the request and inspects the URL searching for
       /LotusQuickr/ token;
    3. If URL contains token, request is passed to Quickr that inspect searching for a
       know command like ?OpenDocument
    4. Quick processor opens form named in URL: &Form=h_PageUI from
       HaikuCommonForms.ntf;
    5. 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) ;
    6. 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

1.1.3 - 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
References

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