Question & Answer
How can I avoid the overhead of loading reference list fields in ClearQuest records?
Loading a record can take a long time when the form has many reference list fields or those fields contain many items.
In IBM Rational ClearQuest, a List View form control displays the records associated with a field whose type is Reference List. One of the primary uses of this control is to display the children in a parent/child relationship.
The Parent/Child control consists of a List View control along with buttons that can be used to add, create new, or remove items from the list. The feature described in this technote applies to the List View control by itself or when part of a Parent/Child control.
The List View control displays the associated reference list in a multi-column format, with selected fields from the referenced records shown in tabular form. The ClearQuest Web client must run a query to load those fields from the referenced fields in order to show them in the List View control. This can take a while, especially when many fields are being shown or when a reference list has many values.
Individual reference list fields can now be configured to be loaded only when the user needs to see the values. When enabled for a field, the web client does not need to run the extra query when loading the record, which results in less time to load the record. The user will see a button in the space where the List View control content would normally be shown. The localized button name is "Load" followed by the name of the reference list field, such as "Load Customers" or "Load Related_Defects". This is similar to how the History field is deferred in a Feature Level 9 database (see technote #1959953).
Enabling this feature for reference list fields requires two steps: setting a master property, and specifying which fields are to be enabled by creating a set of folders in the Public Queries workspace.
1. Set the LISTVIEW_QUERY_FOLDER master property to the pathname of a folder in the public workspace. You must create the named folder. This folder is where you will create subfolders that correspond to the names of record types and reference list fields.
2. Determine which reference list fields of what record types you want to be loaded on demand.
2A. For each record type, create a subfolder in the list view folder identified in step 1, and name it the same as the record type. This name must have the same spelling, but is not case sensitive.
2B. Within the record type subfolder created in step 3, create another folder and name it the same as the reference list field of that record type. Create one folder for each reference list field.
The result will be a three-level folder structure, like this:
For example, consider a schema with Defect and Escalation record types. Defect has reference list fields Related and Tasks. Escalation has reference list fields Customers and Defects. The following folder structure will enable deferred loading for those fields if the LISTVIEW_QUERY_FOLDER master property is set to "Public Queries/List-Views".
All of these folders are normal workspace folders and may contain queries or other workspace items, although this is not recommended. Any non-folder item will be ignored, and a subfolder will be ignored if it does not correspond to a record type or a field name within that record type. If the folder identified by the LISTVIEW_QUERY_FOLDER does not exist or cannot be read by the user (due to Access Control Lists--workspace ACLs), the feature is effectively disabled for all record types. The Change Management (CM) Server SystemOut.log will contain informational messages if the folder does not exist or cannot be read, or if any of the subfolders do not correspond to record types or fields.
Here is another example where the Customer list of the Defect record type from the DefectTracking schema has been enabled for deferred loading. The master property has been set to "
Public Queries/ListView Folder". Here is that folder in the workspace:
Here is the Customer tab of a Defect record showing the "
Load customer" button:
The content of the List View Query folder is read as needed within any session that needs to load a record of a particular type. An existing session may need to log out and back in to see any changes within the List View Query folder.
Setting the LISTVIEW_QUERY_FOLDER master property
The LISTVIEW_QUERY_FOLDER master property can be set to apply to all ClearQuest User Databases associated with a Schema Repository or to a specific User Database. A setting for a specific User Database will override the general setting that applies to all User Databases.
Enable the List View query feature for all User Databases:
installutil setmasterproperty <dbset_name> <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER "Public Queries/List Views"
Enable the List View query feature using a different folder in just the SAMPL database:
installutil setmasterproperty <dbset_name> -user_db_name SAMPL <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER "Public Queries/Admin/List Views"
Disable master property
To remove the setting for all databases and the one for the SAMPL database (as set in the previous examples), set the property to an empty string:
installutil setmasterproperty <dbset_name> <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER ""
installutil setmasterproperty <dbset_name> -user_db_name SAMPL <cq_login> <cq_password> LISTVIEW_QUERY_FOLDER ""
Internal Use Only
There are a few things about this feature that may seem unusual. One is the name of the master property itself, which includes the word "query", but the feature does not use queries, at least not user defined queries. The other is the use of folders in a user database that correlate to schema elements, which are normally handled in the CQ Designer or with schema properties.
These things may lead to questions from customers. The explanation is that this feature is really the first part of a more elaborate feature for List View controls. This first part is for RFE Story 60549, "[CQPAR00157381] - BOSCH RFE: Lazy loading on reference lists in the CQ-Web API".
The second part will be the ability to provide a user defined query that will be run to populate the content of the List View control. The second part is for RFE Story 59974, "[CQPAR00148497] - BOSCH RFE: New ListView control for references based on a user definable query".
It will add the ability to change the columns that are displayed, the sort order, and even limit the content to something less than the full field value. It will do that by recognizing user-defined queries stored in the subfolder for each reference list field. Since user-defined queries live only in a user database, it is necessary to have this information be associated with a specific user database. It would not be reasonable (in terms of the effort required) to extend the designer in some way to allow creating queries and associating them with form controls.
When the second part is implemented, it will use the same folder structure. If the folders for a reference field are empty, the behavior will be unchanged from what is described in this tech note, specifically that the List View control will have a "Load <fieldname>" button. If any suitable queries are in that folder, then there will be additional buttons, one for each of those queries, which allows the user to select different views of the reference list value.
Note: RFEs are always subject to change or cancellation and do not constitute a guarantee of features to customers.
17 June 2018