Domino Data Access Builder

Domino Data Access Builder

In this topic ...

Quick Tips
Specifying Inputs
Domino Server Setup
Using this Builder
Specifying User Names and Passwords
Objects This Builder Creates
Helper Methods Available

Related Topics ...

Using a Data View
Paging Assistant Techniques

Use this Builder to connect to and access information stored on a Lotus Domino server. Using this Builder we can access Domino data and display Domino views within a portlet.
In addition to displaying a view, this Builder allows you to specify a single view category to display. The Builder also supports full text search against the view (this defaults to a lower-performance search if the database is not full-text indexed) and returns the result set in the display format of the selected view. This Builder also allows you to access values from a Domino document via a helper method.
To connect to the Domino server provide a valid Domino server host name and a valid Domino Web user name and password. Once the Builder has these parameters, it can retrieve a list of all the databases on the server. From this list you select a database and retrieve a list of all the available views. We can then choose a Domino view to display in the portlet.
Notes:

If you do not have access to browse the list of databases on the server, we can still enter the name of a database to which you have access directly into the Database Name input.
To access a Domino database through this Builder, the connecting user must have IIOP (Internet Inter-Orb Protocol) access to the Domino server and ACL access permissions to the target database. In addition, the Domino server must be configured to allow HTTP browsing of databases so the Builder can populate various select lists.

Quick Tips

Hide columns -- There are two columns created by this Builder in every Domino view that you will generally want to hide. Use a Data Field Modifier Builder to hide:
URL - The column displaying the URL used to open the document in Domino.
UNID - The column displaying the unique ID of the Domino Document. (This unique ID can be used as an argument for the getDocumentData method).
Hide Category Columns - The generated view schema and view data provide an IsDocumentRow attribute for row data. You can use this attribute to hide category columns for rows that are document rows

Specifying Inputs

This builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see Using the Builder Call Editor.

Input name Description
Name Enter a name for this builder call. The designer tool displays this name in the builder call list.
Properties File Select the name of the property file that contains basic Domino connection information. This file is located normally in the project's WEB-INF/config/domino_config directory.
Example: domino.properties
Note that We can override settings established in this file by using the Connection Override settings in this Builder.
Get databases and views Press this button to access the Domino server and return an alphabetically sorted list of available databases on the server
Database Name Open this list and select the Domino database containing the views and information you want to display in your portlet. This list contains the relative file names of the available databases. For example: catalog.nsf or help\readme.nsf
Once you select a database, the views associated with it are displayed in the View Name list below.
Enable Schema Caching Use this check box to enable the caching of the schema for the specified Domino View. When selected this will cause the Builder s regeneration phase to use a cached version of the View s document and form schema. If a different Database/View or Form is selected a new version of the schema will be cached.
Selecting this option provides two benefits:

Enhanced Performance - This helps during editing models containing this builder.
Enhanced Security - A cached schema avoids exposing model generation time credentials once an initial regen has been performed. To leverage this specify to use separate runtime credentials (see the "Runtime Credentials" input).

Note that If the schema for the data changes on the Domino server, disable this input, regenerate the model, and enable this input again.
Runtime Credentials Select Domino credentials for use during execution. These credentials will be used when the portlet containing the Domino view is run. We can select:

Use credentials specified above - To use at runtime the same credentials specified for regeneration
Specify credentials - Specify a user name and password for use at runtime.
Use LTPA Token - To use WebSphere/Domino LTPA-based SSO (servers must be configured appropriately). A link is added to the page for editing user-specific credentials.

See Credentials for more about user names and passwords.
Note that When this box is enabled, two additional Builder inputs are displayed (see below)
View Support
Enable View Support This option is checked by default to enable your application to render views from a Domino database. Unchecking this option is intended for applications that only need to render elements from a document or form in a database. If unchecked, the other fields in this section are hidden.
View Name Open this list and select the Domino view you want to display in your portlet. This input is hidden when Enable View Support is not checked.
Note that Hidden views are not included in the list of available views. To access a hidden view enter the name of the view.
Rows to Include This input allows you to specify which rows in the View will be included on the page. We can select:

Document rows only
All rows
Category rows only

This input is hidden when Enable View Support is not checked.
Category (Optional) This input exercises Domino's Category functionality and can be used to request a single category of a view.
This is based on the first categorized column in the view. A string match of the category is attempted as though you were doing a quick-search on the selected view.
Example: For a selected view that lists US cities categorized by US state name, specifying "Colorado" returns only view entries under the "Colorado" category.
This input is hidden when Enable View Support is not checked.
Search String (Optional) Provide a text string to use as search criteria. This input exercises Domino search functionality and allows you to do a full text search on the selected view content.
Note that For best performance, the Domino database should have full text search enabled.
The following examples, based on the Films database, illustrate the syntax used in this search function:
field Keywords contains war
field Director contains spielberg
field AFIRank=22
Combine search strings using AND as follows:
field Keywords contains war AND field Director contains altman
This input is hidden when Enable View Support is not checked.
Document support
Enable Document and Form Support (Optional) Enable this check box to create a schema-typed variable for use with getDocumentData method.
Form To Use For Document Schema Enter the name of a Domino form that will be used to generate a document schema. (To provide more control over the document schema generation)
Note that If this input is empty, the document schema is generated by looking at all the items present in the first page of the view.
Optional Schema Settings
View Top Element Name Timeop-level element name for view data. Leave blank to use the default: "ViewData". This input is hidden when Enable View Support is not checked.
View Row Element Name Specifies the row element name for view data. Leave blank to use the default: "Row". This input is hidden when Enable View Support is not checked.
Document Element Name Timeop-level element name for document data. Leave blank to use the default: "DocumentItems".
Include UNID In Document Schema Enable to have a "UNID" element added to the schema for documents. You might want to enable this setting when making a service input for updating a document.
Connection Override
Host Server Enter the host name (and port number if not port 80) of the Domino server.
Example: domino_server.acme.com:8080
User Name for Generation Provide a Domino server user name. This name will be used for all requests to the Domino server.
Note that This user name is used for all requests to the Domino server. Such requests are made at both design time and at regen time.
Password for Generation Provide a Domino server password associated with the user name above. This password will be used for all requests to the Domino server.
Note that This password is used for all requests to the Domino server. Such requests are made at both design time and at regen time.
Advanced
Fetch Subsets of Data If you anticipate returning a large amount of data, and using paging to view a specific number of rows, enable this input. When enabled, this input allows more efficient paging of data from Domino APIs to the Portlet Factory's XML representation. If you plan to use the Data Page or Data View Builders to display paged data, the increased efficiency is desirable.
Note that This input applies to document-only Domino data fetches using IIOP. This input has no effect when:

HTTP Access is used
The Rows to include input is either All Rows or Category Rows Only.

This input is hidden when Enable View Support is not checked.
Use HTTP Access Enable to use the HTTP method of accessing Domino view data.
Note that HTTP access is not available if a search string or category specified, or if Enable View Support is not checked.
Include Untitled Columns Enable to display Domino view columns that have no name or title. By default, this Builder hides untitled and unnamed columns. Such columns are displayed in the portlet when this box is enabled. This input is hidden when Enable View Support is not checked.
Note that The absence of a column title is not a good measure of whether a column should be displayed or not (most categorized columns are not titled). Usually you'll have a mix of untitled columns that should be displayed (categories, columns with icons) and columns that should not be displayed (hidden sort columns). We can always hide unwanted columns with a Data Field Modifier Builder.
Log View Data Enable to cause view data information to be written to the log. The log4j logger DebugTracing is used as the output. The info level for this logger must be at least INFO, which it is the default. This input is hidden when Enable View Support is not checked.
Omit URL Column Enable to suppress the generation of a "URL" column for view data. This column holds the URL for launching Domino in its own window. In many applications this capability is not required. This input is hidden when Enable View Support is not checked.

Domino Server Setup

This Builder uses Java IIOP (Internet Inter-Orb Protocol) to access the Domino server: There are several steps required to enable Java IIOP access to the Domino server. Refer to the Domino Designer documentation, under Java/CORBA" Classes, Java Classes Coding Guidelines, Running a Java Program, for information about enabling IIOP.
To support this Builder's ability to browse a Domino database, you must establish the following Domino server setting: In the Current Server Document in Domino, under Internet Protocols, HTTP, be sure the choice for "Allow HTTP clients to browse databases" setting is "yes".
If you are running Domino R5, the Domino Web Server must be running in order to retrieve the IOR. If you are running Domino R6 or later, running the Domino Web Server is not required; instead, the IOR is retrieved directly from the Domino DIIOP port. This is configured in the properties file specifed in the Properties File field, or in the Host Server field in the Connections Override section. See the field help for more information. Although the Domino Web Server is not required in R6, still set "Allow HTTP clients to browse databases" to "Yes" in the Domino Server document.
A test JSP is provided to verify connectivity to the Domino server. Look in your project's WebContent/factory/util folder for the file, domino_test.jsp. To test connectivity, deploy your project WAR file and point your browser to the server with /factory/util/domino_test.jsp appended to the project path name.

Using this Builder

Follow these general steps to create a Domino View in a portlet:

Specify the first four Builder inputs (Name, Host server, User name for generation, Password for generation).

Press the Get Database List button.
This should populate the list of databases. If it does not, confirm that you have correctly enabled remote (IIOP) access to your server.

Select a Domino database and View, and press OK.

Add a call to the Builder helper's getViewData method, for example, from your "main" action or from an OnWebAppLoad event handler.
This will fetch the view data and populate the <buildername>_results variable.

Display the <buildername>_results variable using a data page builder or Data View Builder.

Optional. Depending on the application, you might need to hide the URL and UNID columns. Use the Omit URL column input to hide the URL column and a Data Field Modifier builder to hide the UNID.

Use a Link Builder to provide access to URLs that open View row data. (Be sure to open in a new window.)

Specifying User Name and Password Credentials

This Builder provides several credential options. These credentials are used in the following ways:

Regen Credentials

There are two credentials available for use during regen ("User name for generation" and "Password for generation"). These credentials are used by the Designer and by the Domino server, and they apply to all users. At regeneration time the Domino server is called to obtain information about the view. Information returned includes column names and types. (The actual view data is not retrieved at regen time.) Any valid Domino user name/password can be used as regen credentials.

Runtime Credentials

Runtime credentials are used once a portlet is deployed and operational. The Builder offers several options for runtime credentials, some of which leverage WebSphere security mechanisms. The option you choose will depend on the Domino and WebSphere security environment the portlet will operate in. We can choose the following Runtime Credential options:

Use regen credentials - Select this to employ the same credentials at runtime and regen. This choice is appropriate when the developer knows of an umbrella credential that will apply and be valid in both development and deployment settings.
Prompt user for credentials - Select this to allow a user to enter their user name /password directly. A link will be placed on the page that allows a user to access a login dialog.
Use LTPA token - Select this to use WebSphere/Domino LTPA based SSO (single sign on). This Builder supports the use of IBM's Lightweight Third-Party Authentication (LTPA). This provides a way for you to use an LDAP server common to both Domino and WebSphere to authenticate a user. Both the WebSphere and the Domino server must be configured to use an LTPA token. A link will be placed on the page that allows a user to access an edit-credentials dialog.

Objects this builder creates

This Builder creates the following objects in the Webapp:

Linked Java objects

<builder name> - A linked Java object that includes a getViewData method. This method is called to retrieve Domino data. There is also a getViewDataInternal method that should not be called directly, but which can be specified as an action to cache with the Cache Control Builder.

Schemas

<builder name>_schema - An XSD schema representing the view data. This schema supports the following column types: String, dateTime, and double. (The dateTime columns can be used in conjunction with the Data Page Formatter Builder)

Variables

<builder name>_results - The schema-typed variable. This variable is populated whenever the getViewData method is called and it can be used as input to other Builders such as the Data Paging Assistant and Data View Builders to display paged data.

Data Services

<builder_name> - This service supports the following operations:

readTable - Reads Domino View. Has a results parameter containing the view data

readDocument - Reads a single document. Has inputs parameter containing just a UNID element. Results parameter is the document data.

updateDocument - Updates a document. "inputs" parameter is document XML, including UNID element to identify the document to update. No output.

createDocument - Creates a new document, using the form name specified for "Document schema form". "inputs" parameter is the XML document to create. "results" contains the UNID of the created document.

Linked Java object helper methods available

The following Domino View helper linked Java object methods are available for use (other methods are not intended to be called):

void cleanup - Closes connections to the Domino server
String createDocument(IXml documentData, String formName) - Returns the UNID of the created document
Boolean deleteDocument(String unid) - Deletes specified document in the current database, given the Universal ID of the document
String evaluateFormula(String formulaText, String UNID) - Evaluates a Notes formula and returns a String of the result. The "unid" argument is optional and is used only if the specified formula accesses a document. For example, we can use this method to get the Common Name format of the current user name. This can be used to automatically select a category for a view which is categorized by User. The formula for this is: @Name([CN]; @UserName). The UNID argument is not needed in this case.
List getCategoryNames - Returns a List of the available categories in the view
String getDatabaseName - Returns Database name
IXml getDocumentData(String unid) - Returns Domino Document object with the specified UNID. Obtain the UNID for any row in a view by looking at the UNID column.
Database getDominoDatabase - Returns the Domino Database Java object
Session getDominoSession - Returns the Domino Session Java object
View getDominoView - Returns the Domino View Java object
Object getViewData - Fetches view data and stores it in the <buildername>_results variable
IXml getViewDataInternal - (Cannot be called directly.) Can be used with the Cache Control Builder to cache results across users
String getViewName - Returns view name
Void runAgent(String agentName,String UNID) - Invokes named agent on document defined by UNID
String setItemValueSeparator(String separator) - Changes default value separator character
void setDatabaseName(String databaseName) - Changes the database at runtime. (Note: This can only be done if all the items used within the database (such as view and form) have the exact same name and structure as in the original database. )
void setItemValueSeparator(String) - Changes separator used for multi-valued document items
boolean updateDocument(IXml documentData, String unid) - Updates an existing Domino document from XML data, given documents UNID
public String sendDocument - Sends a document as an e-mail
public void setComputeWithFormEnabled(boolean set) - Allows you to control whether or not Domino's computeWithForm is called when a document is created or updated. By default it is enabled (computeWithForm called).
void setViewName(String viewName) - Changes the view name at runtime. In general, this should be used only with views that have a schema compatible with the view specified in the builder call.
String getUserName() - Retrieves the user name used for logging in to Domino server.

Input name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list.
Properties File	Select the name of the property file that contains basic Domino connection information. This file is located normally in the project's WEB-INF/config/domino_config directory. Example: domino.properties Note that We can override settings established in this file by using the Connection Override settings in this Builder.
Get databases and views	Press this button to access the Domino server and return an alphabetically sorted list of available databases on the server
Database Name	Open this list and select the Domino database containing the views and information you want to display in your portlet. This list contains the relative file names of the available databases. For example: `catalog.nsf` or `help\readme.nsf` Once you select a database, the views associated with it are displayed in the View Name list below.
Enable Schema Caching	Use this check box to enable the caching of the schema for the specified Domino View. When selected this will cause the Builder s regeneration phase to use a cached version of the View s document and form schema. If a different Database/View or Form is selected a new version of the schema will be cached. Selecting this option provides two benefits: Enhanced Performance - This helps during editing models containing this builder. Enhanced Security - A cached schema avoids exposing model generation time credentials once an initial regen has been performed. To leverage this specify to use separate runtime credentials (see the "Runtime Credentials" input). Note that If the schema for the data changes on the Domino server, disable this input, regenerate the model, and enable this input again.
Runtime Credentials	Select Domino credentials for use during execution. These credentials will be used when the portlet containing the Domino view is run. We can select: Use credentials specified above - To use at runtime the same credentials specified for regeneration Specify credentials - Specify a user name and password for use at runtime. Use LTPA Token - To use WebSphere/Domino LTPA-based SSO (servers must be configured appropriately). A link is added to the page for editing user-specific credentials. See Credentials for more about user names and passwords. Note that When this box is enabled, two additional Builder inputs are displayed (see below)
View Support
Enable View Support	This option is checked by default to enable your application to render views from a Domino database. Unchecking this option is intended for applications that only need to render elements from a document or form in a database. If unchecked, the other fields in this section are hidden.
View Name	Open this list and select the Domino view you want to display in your portlet. This input is hidden when Enable View Support is not checked. Note that Hidden views are not included in the list of available views. To access a hidden view enter the name of the view.
Rows to Include	This input allows you to specify which rows in the View will be included on the page. We can select: Document rows only All rows Category rows only This input is hidden when Enable View Support is not checked.
Category	(Optional) This input exercises Domino's Category functionality and can be used to request a single category of a view. This is based on the first categorized column in the view. A string match of the category is attempted as though you were doing a quick-search on the selected view. Example: For a selected view that lists US cities categorized by US state name, specifying "Colorado" returns only view entries under the "Colorado" category. This input is hidden when Enable View Support is not checked.
Search String	(Optional) Provide a text string to use as search criteria. This input exercises Domino search functionality and allows you to do a full text search on the selected view content. Note that For best performance, the Domino database should have full text search enabled. The following examples, based on the Films database, illustrate the syntax used in this search function: field Keywords contains war field Director contains spielberg field AFIRank=22 Combine search strings using AND as follows: field Keywords contains war AND field Director contains altman This input is hidden when Enable View Support is not checked.
Document support
Enable Document and Form Support	(Optional) Enable this check box to create a schema-typed variable for use with `getDocumentData` method.
Form To Use For Document Schema	Enter the name of a Domino form that will be used to generate a document schema. (To provide more control over the document schema generation) Note that If this input is empty, the document schema is generated by looking at all the items present in the first page of the view.
Optional Schema Settings
View Top Element Name	Timeop-level element name for view data. Leave blank to use the default: "ViewData". This input is hidden when Enable View Support is not checked.
View Row Element Name	Specifies the row element name for view data. Leave blank to use the default: "Row". This input is hidden when Enable View Support is not checked.
Document Element Name	Timeop-level element name for document data. Leave blank to use the default: "DocumentItems".
Include UNID In Document Schema	Enable to have a "UNID" element added to the schema for documents. You might want to enable this setting when making a service input for updating a document.
Connection Override
Host Server	Enter the host name (and port number if not port 80) of the Domino server. Example: domino_server.acme.com:8080
User Name for Generation	Provide a Domino server user name. This name will be used for all requests to the Domino server. Note that This user name is used for all requests to the Domino server. Such requests are made at both design time and at regen time.
Password for Generation	Provide a Domino server password associated with the user name above. This password will be used for all requests to the Domino server. Note that This password is used for all requests to the Domino server. Such requests are made at both design time and at regen time.
Advanced
Fetch Subsets of Data	If you anticipate returning a large amount of data, and using paging to view a specific number of rows, enable this input. When enabled, this input allows more efficient paging of data from Domino APIs to the Portlet Factory's XML representation. If you plan to use the Data Page or Data View Builders to display paged data, the increased efficiency is desirable. Note that This input applies to document-only Domino data fetches using IIOP. This input has no effect when: HTTP Access is used The Rows to include input is either All Rows or Category Rows Only. This input is hidden when Enable View Support is not checked.
Use HTTP Access	Enable to use the HTTP method of accessing Domino view data. Note that HTTP access is not available if a search string or category specified, or if Enable View Support is not checked.
Include Untitled Columns	Enable to display Domino view columns that have no name or title. By default, this Builder hides untitled and unnamed columns. Such columns are displayed in the portlet when this box is enabled. This input is hidden when Enable View Support is not checked. Note that The absence of a column title is not a good measure of whether a column should be displayed or not (most categorized columns are not titled). Usually you'll have a mix of untitled columns that should be displayed (categories, columns with icons) and columns that should not be displayed (hidden sort columns). We can always hide unwanted columns with a Data Field Modifier Builder.
Log View Data	Enable to cause view data information to be written to the log. The log4j logger DebugTracing is used as the output. The info level for this logger must be at least INFO, which it is the default. This input is hidden when Enable View Support is not checked.
Omit URL Column	Enable to suppress the generation of a "URL" column for view data. This column holds the URL for launching Domino in its own window. In many applications this capability is not required. This input is hidden when Enable View Support is not checked.