Untitled Document
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.
Lotus Quickr Object
|
Domino Object
|
Description
|
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 + Data Note
(metadata) |
The basic vehicle for content. You can
create content 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 ″h_Form″ |
Manages the display of data notes. A form
can 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\P laceName
|
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
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