IBM Support

Run user-defined queries on the List View control for ClearQuest Web

Question & Answer


Question

How can I enable List View Query feature to run user-defined queries on the List View control?

Cause

The default content of the List View control could contain many items and complex columns, which leads to long loading time and cannot be customized.

Answer

The purpose of this new feature is to transform the existing List View control based on user-defined queries, thus the user is able to configure the List View control to show different results with customized columns.

The prerequisite is to enable the deferred loading of reference list fields (technote #1976572).

Configuring the folder and queries

Here is an 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:



There are 4 queries inside the path "ListView Folder/Defect/customer". They must be created based on the Customer type, otherwise they will be ignored. The administrator can check the WAS logs for warnings about ignored queries and other issues related to this feature.

The List View root folder can only be set inside the "Public Queries" folder. Only the administrator can define the queries and end-users cannot define their own. It recommends making the List View root folder be read-only for everyone, but only writeable by administrators.

Default view choices

Here is the Customer tab of a Defect record showing the "Load customer" button and all the valid user-defined queries as buttons:



The limit is 4 buttons. If there are 5 or more valid queries, the last button will instead be a More drop-down button showing the others. The yellow border and hovering message indicate the List View Query feature is enabled on this control.

Clicking the button

Clicking "Load customer" button will display the default content of the List View control. Clicking another button will run the query that will automatically be filtered to limit the result to only show the references in the field itself. The display is then changed to show the columns defined by that query.

Here is the result of clicking the "Bank Company" button.



The context menu will display with some new menu items when right clicking anywhere in the control.
"Restore view choices" provides the ability to return to the default view with all the buttons displayed.
"Showing N of M" (Here is Showing 1 of 5) is a non-clickable item. It indicates the current view is not showing all the field values. In this example, the field actually has 5 items but the user defined query result set contains only 1 of those 5 items after being automatically filtered.
All the queries are listed on the context menu, including those shown on the buttons. The user can switch between different views by clicking any of these query items. A check mark will display in front of the currently selected query item.

The default query

The administrator can also specify a default query for the List View control so that a default view will automatically display instead of the view button choices when the record is first opened.
To identify the default query, add " [@tag]", as a suffix to the query name in the workspace. Note that the space before the left square bracket is required. The "tag" part is optional and can be any or no text, which allows it to be any word in any language suitable for users. The query name must end with a closing square bracket. The minimum required suffix is " [@]".

Here is an example that the query "Owned by me" inside the path "ListView Folder/Defect/relatedDefects" is specified as the default query with the suffix " [@default]". On the context menu of the List View control, the default query item is marked as bold.




Warnings appear in WAS logs

The ListView Query feature looks for the appropriate folder structure in the workspace and for properly defined queries within those folders. Items that are not suitable are ignored and will not cause any problems.

If the ignored items were intended to be used for the feature, the administrator needs to know why they are being ignored. For this reason, warnings related to the feature are written to the WebSphere Application Server SystemOut.log file. These warnings may identify items that are not defined properly and will help diagnose issues if the feature is not working as expected. The warnings include identifying folders that do not correspond to list fields within a record type, or queries that are not using the proper record type. Here are some examples.

Take the above screen shot for instance.
If you find the feature is not working at all after enabling, please check:
I SessionCacheManagerImpl : CQWeb : setListViewProperty : ListView is not enabled because the list view folder, "Personal Queries/ListView Folder", is empty or not inside the "Public Queries" folder

You can check the number of items created inside the List View root folder:
I SessionCacheManagerImpl : CQWeb : parseListViewRootFolder : There are 4 sub-items inside "Public Queries/ListView Folder" where ListView Query will look for folders matching record types.

You can check the non-folder item inside the List View root folder:
I SessionCacheManagerImpl : CQWeb : parseListViewRootFolder : ListView Query is ignoring "All Defects" inside "Public Queries/ListView Folder" because it is not a folder.

You can check the number of items created inside the "ListView Folder/Defect" folder:
I SessionCacheManagerImpl : CQWeb : parseListViewFields : There are 7 sub-items inside "Public Queries/ListView Folder/Defect" where ListView Query will look for folders matching list fields for the "Defect" record type.

You can check the invalid fields for the record type:
I SessionCacheManagerImpl : CQWeb : parseListViewFields : "relatedDefects_void" is an invalid field for the "Defect" record type.
I SessionCacheManagerImpl : CQWeb : parseListViewFields : "b" is an invalid field for the "Defect" record type.
I SessionCacheManagerImpl : CQWeb : parseListViewFields : ListView Query is ignoring "All Defects" inside "Public Queries/ListView Folder/Defect" because it is not a folder.


You can check the number of items created inside the "ListView Folder/Defect/relatedDefects" folder:
I SessionCacheManagerImpl : CQWeb : parseListViewQueries : There are 7 sub-items inside "Public Queries/ListView Folder/Defect/relatedDefects" where ListView Query will look for queries.

You can check the invalid queries created inside the "ListView Folder/Defect/relatedDefects" folder:
I SessionCacheManagerImpl : CQWeb : parseListViewQueries : ListView Query is ignoring the "All Customers" query because it is not defined for the record type "Defect"

You can identify the fields on the record form that are enabled for deferred loading and ListView Query:
I SessionCacheManagerImpl : CQWeb : updateFormJSONForLazyLoad : Deferred Loading is enabled for the field "projects" of the record type "Defect"
I SessionCacheManagerImpl : CQWeb : updateFormJSONForLazyLoad : ListView Query is enabled for the field "customer" of the record type "Defect"
I SessionCacheManagerImpl : CQWeb : updateFormJSONForLazyLoad : ListView Query is enabled for the field "relatedDefects" of the record type "Defect"

Internal Use Only

This feature is the second 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 is for RFE Story 59974, "[CQPAR00148497] - BOSCH RFE: New ListView control for references based on a user definable query".

[{"Product":{"code":"SSSH5A","label":"Rational ClearQuest"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Component":"General Information","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.0.1.12;8.0.1.13;9.0.0.2;9.0.0.3","Edition":""}]

Document Information

Modified date:
14 March 2019

UID

swg21990415