Domino Keyword Lookup Builder

Domino Keyword Lookup Builder

In this topic ...

Quick Tips
Specifying Inputs

Use the Domino Keyword Lookup Builder when we need to display or handle Domino data that is structured as value / label pairs.
The Domino Keyword Lookup Builder integrates Domino data with the Factory's Lookup Table Builder. That means that you can use a Domino View, Profile Document, or Formula to generate a set of data and feed that data into the Lookup Table builder at runtime to support value/label mappings and the creation of HTML select controls on a page.

How Keyword Lookup Works

The Domino Keyword Lookup Builder either works stand-alone or in conjunction with a supporting Domino View Builder or Domino View & Form builder. The Keyword Lookup builder uses the Domino artifacts created by itself or the other builder to communicate with the back-end Domino server and extract data for use by the Lookup Table builder.
Most of the integration of Domino with the Lookup Builder is accomplished at model regeneration time. At regeneration time the Domino Keyword Lookup builder adds a Lookup Table builder to the model and then connects it to the Domino artifacts responsible for providing the actual data to drive the Lookup Table functionality at runtime.
This data is then used by any of serveral builders that consume Lookup Table builder calls. A Select builder or a Radio Button Group builder, for example, each have an input that refers to a Lookup Table builder call in the same model. Since the Domino Keyword Lookup builder includes a Lookup Table builder, any builder that can consume a Lookup Table builder can consume the one created by the Domino Keyword Lookup builder. As a result, HTML UI elements such as select lists and radio buttons can have lists with name-value pairs where the name-value pairs are stored in views in Domino databases. Other builders that can make use of a Lookup Table builder created by a Domino Keyword Lookup builder include but are not limited to Text, Data Field Modifier, and Query Filter.
Control flow in this builder depends on how the builder is configured. For example:

Domino View -- When the builder is configured to obtain data from a Domino View, and a client calls one of the Lookup Table methods, the Keyword Lookup builder performs the following high-level actions at runtime:

The builder uses the Domino artifacts created by itself or another other Domino builder to obtain an XML representation of the Domino View contents.

The XML data flows directly into the Lookup Table methods due to the connections created at regeneration time by the builder.

Profile Document -- When the builder is configured to obtain its data from a Domino Profile Document, the Keyword Lookup builder performs the following high-level actions at runtime:

The builder first obtains the name of the Domino Profile document that contains the data to be fed into the Lookup Table builder. This name is contained in the "Domino Profile Document" builder input.

The builder obtains the name of the Domino Profile document field that contains the data. This field name is contained in the "Field Name" builder input.

The builder extracts the value of the field and converts it into an XML representation suitable for consumption by the Lookup Table builder.

The XML data flows into the Lookup Table methods due to the connections created at regeneration time by the builder.

Formula -- When the builder is configured to obtain its data from a Domino Formula, the Keyword Lookup builder performs the following high-level actions at runtime:

The builder first obtains the unique ID for the Domino document, if any, associated with the formula. The ID is contained in the "Document UNID" builder input.

The builder obtains the formula to be evaluated.

The builder then uses the Domino artifacts created by itself or another other Domino builder to evaluate the formula. The result of the formula is converted it into an XML representation suitable for consumption by the Lookup Table builder.

The XML data flows into the Lookup Table methods due to the connections created at regeneration time by the builder.

Quick Tips

Strings and Separator Characters -- The builder assumes that the result of evaluating a formula is a Vector of strings where each string is a value/label pair containing a separator character. If a string from the Vector does not contain the separator character, the builder treats the whole string as both the value and label. If a string from the Vector contains more than one separator character, then the builder treats the sub-string before the first separator as the value and the rest of the strings as the label.
Value/label Order -- The data obtained from a Domino Profile document or Formula must be formatted so that the value appears before the label in a value/label pair.

Specifying Inputs

The Domino View 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 displays this name in the Builder Call List.
Data Provider Select the Domino entity you will use to provide value/label data. We can choose:

View - To extract data from an existing Domino View or a view you will create
Domino Profile Document - To extract data from a Domino document
Formula - To extract data from a Domino formula

See tables below for input information specific to each Data Provider.
Use Existing View Enable to use an existing Domino View builder to access the Domino system. The Data Provider selected above will access Domino through the WebApp artifact generated by this builder.
Disable to create a Domino view specifically for use by this builder. Click here for more information about creating a view.
Domino Connection Helper Select a Domino View builder to use for communication with the Domino system.
Value Tag Select the Domino column that represents value entities
Label Tag Select the Domino column that represents label entities that correspond with the values above.
Additional Data Definition
Get Data From Identifies the source of data. We can choose:

Builder Input - To get data from Additional Pairs table.
XML Data - To get data from an XML type variable. This choice is useful if there is a default set of labels/values that should appear in a number of select lists

Add a blank selection Select this option to provide a blank selection for optional fields in a form where the user does not need to provide a specific value provided by the data set.
Additional XML Data This input is available when the Get data From input is XML Data. Use this input to specify an indirect reference to the location where the XML data is located.
Additional Pairs Specify any additional label/value pairs to be included in the lookup table results. (You might want to do this to allow development to proceed while the database is under construction.)

Label - A label to be included in the resultset
Value - A value to be included in the resultset
Collision Resolution - This choice allows you to handle the situation that can occur if a value/label pair you specify is identical to one already contained in the data. When this occurs, select Use Original Value to use the pair contained in the original data. Select Use this Value to use the pair you specified in the table.

Table Position Specifies where additional pairs are in the XML output of this Builder. The choices are:

In Front - The default. Additional data pairs placed in front of existing pairs in the XML stream.
In Back - Additional data pairs placed in back of existing pairs in the XML stream.

Parent Tag Specified the name of an XML element used to contain additional pairs in the table. Default element name is: <UserAddition>

Inputs Specific to a Profile Document Data Provider

Input Name Description
Domino Profile Document Enter the name of the Domino Profile Document that will be used as the source of the data.
Field Name Enter the name of the field in the document specified above that contains the value/label data.
Key (Optional) Enter the unique key, if any, used to identify the Profile Document.

Inputs Specific to a Formula Data Provider

Input Name Description
Formula Enter the syntax of the Domino formula used to calculate data
Separator Enter the string used to separate values and labels in the formula result strings.
For example: | ( a pipe character)

Inputs for Creating a Domino View

Most of the inputs in this table duplicate those available in either the Domino View builder or the Domino View and Form builder. Refer to help for those builders for additional information related to these inputs.

Input Name Description
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.
The generation credentials are used to access the Domino server from the WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be 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.
The generation credentials are used to access the Domino server from the WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at generation time.
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 generation credentials specified above - To use at runtime the same credentials specified for generation
Prompt user for credentials - To allow user to specify a user name and password for use at runtime. Credentials are taken from a WebSphere Portal Credential Vault slot called "DominoUserCredentials". A link is added to the page for editing user-specific credentials.
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.

Execution user name This input is available when "Prompt user for credentials" is selected above.
Provide a Domino user name.
The name entered here will be used for all requests to the Domino server made at execution time.
Execution password This input is available when "Prompt user for credentials" is selected above.
Provide a Domino password associated with the user name above.
The password entered here will be used for all requests to the Domino server made at execution time.
Get Databases and Views Button 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 data you want to access. 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.
View name Open this list and select the Domino view containing the data you want to retrieve.
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

Input Name	Description
Name	Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Data Provider	Select the Domino entity you will use to provide value/label data. We can choose: View - To extract data from an existing Domino View or a view you will create Domino Profile Document - To extract data from a Domino document Formula - To extract data from a Domino formula See tables below for input information specific to each Data Provider.
Use Existing View	Enable to use an existing Domino View builder to access the Domino system. The Data Provider selected above will access Domino through the WebApp artifact generated by this builder. Disable to create a Domino view specifically for use by this builder. Click here for more information about creating a view.
Domino Connection Helper	Select a Domino View builder to use for communication with the Domino system.
Value Tag	Select the Domino column that represents value entities
Label Tag	Select the Domino column that represents label entities that correspond with the values above.
Additional Data Definition
Get Data From	Identifies the source of data. We can choose: Builder Input - To get data from Additional Pairs table. XML Data - To get data from an XML type variable. This choice is useful if there is a default set of labels/values that should appear in a number of select lists
Add a blank selection	Select this option to provide a blank selection for optional fields in a form where the user does not need to provide a specific value provided by the data set.
Additional XML Data	This input is available when the Get data From input is XML Data. Use this input to specify an indirect reference to the location where the XML data is located.
Additional Pairs	Specify any additional label/value pairs to be included in the lookup table results. (You might want to do this to allow development to proceed while the database is under construction.) Label - A label to be included in the resultset Value - A value to be included in the resultset Collision Resolution - This choice allows you to handle the situation that can occur if a value/label pair you specify is identical to one already contained in the data. When this occurs, select Use Original Value to use the pair contained in the original data. Select Use this Value to use the pair you specified in the table.
Table Position	Specifies where additional pairs are in the XML output of this Builder. The choices are: In Front - The default. Additional data pairs placed in front of existing pairs in the XML stream. In Back - Additional data pairs placed in back of existing pairs in the XML stream.
Parent Tag	Specified the name of an XML element used to contain additional pairs in the table. Default element name is: <UserAddition>

Input Name	Description
Domino Profile Document	Enter the name of the Domino Profile Document that will be used as the source of the data.
Field Name	Enter the name of the field in the document specified above that contains the value/label data.
Key	(Optional) Enter the unique key, if any, used to identify the Profile Document.

Input Name	Description
Formula	Enter the syntax of the Domino formula used to calculate data
Separator	Enter the string used to separate values and labels in the formula result strings. For example: \| ( a pipe character)

Input Name	Description
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. The generation credentials are used to access the Domino server from the WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be 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. The generation credentials are used to access the Domino server from the WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at generation time.
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 generation credentials specified above - To use at runtime the same credentials specified for generation Prompt user for credentials - To allow user to specify a user name and password for use at runtime. Credentials are taken from a WebSphere Portal Credential Vault slot called "DominoUserCredentials". A link is added to the page for editing user-specific credentials. 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.
Execution user name	This input is available when "Prompt user for credentials" is selected above. Provide a Domino user name. The name entered here will be used for all requests to the Domino server made at execution time.
Execution password	This input is available when "Prompt user for credentials" is selected above. Provide a Domino password associated with the user name above. The password entered here will be used for all requests to the Domino server made at execution time.
Get Databases and Views Button	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 data you want to access. 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.
View name	Open this list and select the Domino view containing the data you want to retrieve. 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