Difference between revisions of "ClearQuest Dynamic List Editor"

From cqwiki
Jump to navigationJump to search
m
m
Line 4: Line 4:
  
 
= Dynamic List Editor =
 
= Dynamic List Editor =
It is NOT a solution that is provided and supported by IBM-Rational.  
+
This is NOT a solution that is provided and supported by IBM-Rational.  
Dynamic list editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most important) Web client. In addition, it adds basic audit capabilities that can be enhanced using Audit Trail package.
+
The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package.
 
The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required.
 
The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required.
  
Line 12: Line 12:
 
[[File:Dynamic_List_Editor.png|center]]  
 
[[File:Dynamic_List_Editor.png|center]]  
  
Dynamic List administrators are working with the stateless records, and when update is completed and records are submitted to the database, correspondent dynamic lists are updated automatically.
+
Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically.
  
 
== Installation Instruction ==
 
== Installation Instruction ==
The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When configuration is completed, users with "Dynamic List Admin" privilege or super users can modify content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients.
+
The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients.
  
 
=== Installing ClearQuest Schema Update ===
 
=== Installing ClearQuest Schema Update ===
Line 21: Line 21:
  
 
==== Download and Unpack Schema Integration ====
 
==== Download and Unpack Schema Integration ====
Save downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected.
+
Save the downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected.
  
 
====  Apply Integration to ClearQuest Schema ====
 
====  Apply Integration to ClearQuest Schema ====
* Verify that ClearQuest schema is checked in, and there are no pending schema changes that have not been applied to the user database.
+
* Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database.
* Open command line tool, (Start->Run "cmd") and change directory to the location where the integration package was extracted.
+
* Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted.
* Import integration using "cqload importintegration" command. For example:
+
* Import integration using the "cqload importintegration" command. For example:
 
  cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt ""
 
  cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt ""
 
* Verify that the schema update was imported and no issues were detected.
 
* Verify that the schema update was imported and no issues were detected.
Line 33: Line 33:
  
 
==== Upgrade User Database ====
 
==== Upgrade User Database ====
Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to. and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select "Upgrade Database..." option from the database menu and select your user database).
+
Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database).
  
 
[[File:upgrade_db.png|center]]
 
[[File:upgrade_db.png|center]]
  
Apply the change that you imported on the previous step by clicking "OK" button. Verify that user database was upgraded successfully.
+
Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully.
  
 
[[File:upgrade_db_completed.png|center]]
 
[[File:upgrade_db_completed.png|center]]
  
 
==== Import First Dynamic List ====
 
==== Import First Dynamic List ====
The rest of the configuration can be done from a ClearQuest client. You can use any client of your choice. In the instructions are based on ClearQuest Web client, version 8.0.
+
The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0.
Login as an administrator (super user), and submit new record of the "Dynamic_List" type:
+
Login as an administrator (super user), and submit a new record of the "Dynamic_List" type:
  
 
[[File:Submit_Dynamic_List_1.png|center]]
 
[[File:Submit_Dynamic_List_1.png|center]]
Line 55: Line 55:
 
[[File:Submit_Dynamic_List_3.png|center]]
 
[[File:Submit_Dynamic_List_3.png|center]]
  
click "Save" to commit record to the database
+
click "Save" to commit the record to the database
  
 
==== Creating Dynamic List Administration Query ====
 
==== Creating Dynamic List Administration Query ====
Now, you need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder were you are going to save the query and select "New Query" from the context menu.
+
Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu.
  
 
[[File:Dynamic_List_Query _1.png|center]]  
 
[[File:Dynamic_List_Query _1.png|center]]  
Line 66: Line 66:
 
[[File:Dynamic_List_Query _2.png|center]]
 
[[File:Dynamic_List_Query _2.png|center]]
  
Provide query name, for instance, "Dynamic Lists", add "Name" field to the presentation/display section, and specify "Ascending" (A-Z) sort order. Save the query.
+
Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query.
  
 
[[File:Dynamic_List_Query _3.png|center]]
 
[[File:Dynamic_List_Query _3.png|center]]
  
 
==== Importing Dynamic Lists ====
 
==== Importing Dynamic Lists ====
Run "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in "Utilities" section, chose "SyncAllLists" action.
+
Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action.
  
 
[[File:Dynamic_List_Sync_1.png|center]]
 
[[File:Dynamic_List_Sync_1.png|center]]
  
 
The action syncs ClearQuest records with the correspondent dynamic lists:
 
The action syncs ClearQuest records with the correspondent dynamic lists:
* when ClearQuest record already exists, its content is updated from the dynamic list
+
* when the ClearQuest record already exists, its content is updated from the dynamic list
* when ClearQuest record does not exist, new record is created
+
* when the ClearQuest record does not exist, a new record is created
* when dynamic list for existing ClearQuest record does not exist, the record is deleted.
+
* when a dynamic list for the existing ClearQuest record does not exist, the record is deleted.
  
 
[[File:Dynamic_List_Sync_2.png|center]]
 
[[File:Dynamic_List_Sync_2.png|center]]
  
If no errors occur, a confirmation is displayed. Otherwise, you would see an error message.
+
If no error occurred, a confirmation is displayed. Otherwise, you would see an error message.
Refresh the query to verify that all dynamic lists with proper content are loaded.
+
Refresh the query to verify that all dynamic lists with their proper content are loaded.
  
 
[[File:Dynamic_List_Sync_3.png|center]]
 
[[File:Dynamic_List_Sync_3.png|center]]
Line 89: Line 89:
  
 
== Administering Dynamic Lists ==
 
== Administering Dynamic Lists ==
When all Dynamic_List records are populated, List administrators can start using the query you created and Dynamic_Lists records to modify content of the linked dynamic lists. Most of the time, "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration:
+
When all the Dynamic_List records are populated, List Administrators can start using the query you created and Dynamic_Lists records to modify the content of the linked dynamic lists. Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Action Name
 
! Action Name
Line 99: Line 99:
 
| Submit
 
| Submit
 
| Super User
 
| Super User
| Submit allows to create new records when new Dynamic List added to the ClearQuest schema. Instead, you can use "SyncAllLists" utility action to synchronize all records at once.
+
| Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once.
 
|-
 
|-
 
| Update
 
| Update
 
| Modify
 
| Modify
 
| Super User, Dynamic List Admins
 
| Super User, Dynamic List Admins
| Update is the primary action for administering Dynamic Lists content. When action is initialized the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When updated record is saved, its content is saved in the correspondent dynamic list as well.
+
| Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well.
 
|-
 
|-
 
| Delete
 
| Delete
 
| Utilities / Delete
 
| Utilities / Delete
 
| Super User
 
| Super User
| This action allows to delete existing Dynamic_List records. For instance, when correspondent dynamic list was removed from the schema. Alternatively, you can use "SyncAllLists" utility action to synchronize all records at once after database upgrade.
+
| This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade.
 
|-
 
|-
 
| LoadList
 
| LoadList
 
| Utilities / Script
 
| Utilities / Script
 
| Super User, Dynamic List Admins
 
| Super User, Dynamic List Admins
| Load List action updates current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh ClearQuest query or even close and re-run it.
+
| Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it.
 
|-
 
|-
 
| SaveList
 
| SaveList
 
| Utilities / Script
 
| Utilities / Script
 
| Super User, Dynamic List Admins
 
| Super User, Dynamic List Admins
| Save List action saves content of the current ClearQuest records into correspondent dynamic list.
+
| Save List action saves the content of the current ClearQuest records into a correspondent dynamic list.
 
|-
 
|-
 
| SaveAllLists
 
| SaveAllLists
 
| Utilities / Script
 
| Utilities / Script
 
| Super User, Dynamic List Admins
 
| Super User, Dynamic List Admins
| Save all lists saves content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from the external source.
+
| Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source.
 
|-
 
|-
 
| SyncAllLists
 
| SyncAllLists
 
| Utilities / Script
 
| Utilities / Script
 
| Super User
 
| Super User
| The action syncs ClearQuest records with the correspondent dynamic lists:
+
| This action syncs ClearQuest records with their correspondent dynamic lists:
* when ClearQuest record already exists, its content is updated from the dynamic list
+
* when the ClearQuest record already exists, its content is updated from the dynamic list
* when ClearQuest record does not exist, new record is created
+
* when the ClearQuest record does not exist, a new record is created
* when dynamic list for existing ClearQuest record does not exist, the record is deleted.
+
* when a dynamic list for the existing ClearQuest record does not exist, the record is deleted.
 
|}
 
|}
  
 
== Dynamic Lists Caching ==
 
== Dynamic Lists Caching ==
In order to improve performance, ClearQuest caches content of dynamic lists. When you update content of the dynamic lists using native tools, the updates are not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes.
+
In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes.
Similarly, dynamic list editor is using actual dynamic list as a primary trusted source of data for the records. When you initiate record update, the record content is loaded from the dynamic list first. In the environment when dynamic lists are actively updated from many clients simultaneously, it might cause changes overwriting, because cached list values could be used by ClearQuest. In so changing environment, it is recommended to re-login to the database before starting dynamic list modification (the same issue exists when you are using native tools in the legacy ClearQuest Windows Client).  
+
Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client).  
If you rarely use native tools to update dynamic lists (for instance, when ClearQuest full client is not installed on Dynamic List Admins' machines, and they are using Editor's Web Client capability to modify lists only), you can select ClearQuest records as a trusted source of data for the dynamic lists. In order to do it, you need to remove "Update" action initialization hook of the Dynamic_List record type, and upgrade user database to apply changes. It would ensure that most accurate data is used for lists modification.
+
If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification.
  
 
== Support ==
 
== Support ==

Revision as of 00:37, 23 November 2012

ClearQuest Dynamic List Editor

Created by ClearQuest admin for ClearQuest admins.

Dynamic List Editor

This is NOT a solution that is provided and supported by IBM-Rational. The Dynamic List Editor is an add-on to your existing ClearQuest schema, VBScript or Perl based, that provides a unified interface to administer Dynamic Lists for Windows, Eclipse, UNIX clients, and (most importantly) the Web client. Additionally, it adds basic audit capabilities that can be enhanced using the Audit Trail package. The enhancement is distributed as a ClearQuest schema integration, and it can be easily removed from the schema when it is no longer required.

In the Editor, all dynamic lists are represented by correspondent stateless records of the Dynamic_List record type.

Dynamic List Editor.png

Dynamic List administrators work with the stateless records, and when the update is completed and records are submitted to the database, the correspondent dynamic lists are updated automatically.

Installation Instruction

The package is an add-on to your existing ClearQuest schema. In order to install it, you will need ClearQuest administrative access and administrative tools (ClearQuest designer). When the configuration is completed, users with the "Dynamic List Admin" privilege or super users can modify the content of the Dynamic Lists using ClearQuest Web or other ClearQuest clients.

Installing ClearQuest Schema Update

It is highly recommended to test the procedure in your development environment, and backup master and user databases before you start.

Download and Unpack Schema Integration

Save the downloaded archive to your administrative machine hard drive and unpack it. The integration is a text file that can be easily scanned or inspected.

Apply Integration to ClearQuest Schema

  • Verify that the ClearQuest schema is checked in, and that there are no pending schema changes that have not been applied to the user database.
  • Open the command line tool, (Start->Run "cmd") and change the directory to the location where the integration package was extracted.
  • Import integration using the "cqload importintegration" command. For example:
cqload importintegration -dbset <db_connection_name> <admin_user> <admin_password> <ClearQuest_Schema_Name> "" "Dynamic List Editor" 1.0 Dynamic_List_Editor.txt ""
  • Verify that the schema update was imported and no issues were detected.
Cqload completed.png

Upgrade User Database

Now, you can apply changes to the user database using ClearQuest Designer. For Eclipse Designer, in the ClearQuest Database Admin section, right click on the user database that you are going to apply changes to, and select "Upgrade Database" from the context menu. (In legacy Windows Designer, select the "Upgrade Database..." option from the database menu and select your user database).

Upgrade db.png

Apply the change that you imported on the previous step by clicking the "OK" button. Verify that user database was upgraded successfully.

Upgrade db completed.png

Import First Dynamic List

The rest of the configuration can be completed from a ClearQuest client. You can use any client of your choice. The instructions are based on ClearQuest Web client, version 8.0. Login as an administrator (super user), and submit a new record of the "Dynamic_List" type:

Submit Dynamic List 1.png

Select one of the list names from the "Name" drop-down list.

Submit Dynamic List 2.png

Dynamic list values will be populated automatically.

Submit Dynamic List 3.png

click "Save" to commit the record to the database

Creating Dynamic List Administration Query

Now, you will need to create a simple query that will be used by Dynamic Lists administrators. Right click on the folder you are going to save the query to, and select "New Query" from the context menu.

Dynamic List Query 1.png

Select "Dynamic_Query" as a record type

Dynamic List Query 2.png

Provide a query name (for instance, "Dynamic Lists"), add the "Name" field to the presentation/display section, and specify the "Ascending" (A-Z) sort order. Save the query.

Dynamic List Query 3.png

Importing Dynamic Lists

Run the "Dynamic Lists" query that we created on the previous step. You should see one Dynamic List record in the result set. Select the record, and in the "Utilities" section, chose the "SyncAllLists" action.

Dynamic List Sync 1.png

The action syncs ClearQuest records with the correspondent dynamic lists:

  • when the ClearQuest record already exists, its content is updated from the dynamic list
  • when the ClearQuest record does not exist, a new record is created
  • when a dynamic list for the existing ClearQuest record does not exist, the record is deleted.
Dynamic List Sync 2.png

If no error occurred, a confirmation is displayed. Otherwise, you would see an error message. Refresh the query to verify that all dynamic lists with their proper content are loaded.

Dynamic List Sync 3.png


Administering Dynamic Lists

When all the Dynamic_List records are populated, List Administrators can start using the query you created and Dynamic_Lists records to modify the content of the linked dynamic lists. Most of the time, the "Update" action is sufficient. In addition, the Editor offers the following actions to simplify administration:

Action Name Action Type Access Control Description
Submit Submit Super User Submit allows the creation of new records when a new Dynamic List added to the ClearQuest schema. You can also use the "SyncAllLists" utility action to synchronize all the records at once.
Update Modify Super User, Dynamic List Admins Update is the primary action for administering Dynamic Lists content. When an action is initialized, the record is refreshed with the latest content of the dynamic list (please check "Dynamic List Caching" section). When the updated record is saved, its content is saved in the correspondent dynamic list as well.
Delete Utilities / Delete Super User This action allows you to delete existing Dynamic_List records, such as when a correspondent dynamic list is removed from the schema. Alternatively, you can use the "SyncAllLists" utility action to synchronize all records at once after a database upgrade.
LoadList Utilities / Script Super User, Dynamic List Admins Load List action updates the current ClearQuest record with the content of the correspondent dynamic list. Please be aware that in order to see the update you might need to refresh the ClearQuest query or even to close and re-run it.
SaveList Utilities / Script Super User, Dynamic List Admins Save List action saves the content of the current ClearQuest records into a correspondent dynamic list.
SaveAllLists Utilities / Script Super User, Dynamic List Admins Save all lists saves the content of all ClearQuest Dynamic List records into correspondent dynamic lists. It might be useful when records are imported from an external source.
SyncAllLists Utilities / Script Super User This action syncs ClearQuest records with their correspondent dynamic lists:
  • when the ClearQuest record already exists, its content is updated from the dynamic list
  • when the ClearQuest record does not exist, a new record is created
  • when a dynamic list for the existing ClearQuest record does not exist, the record is deleted.

Dynamic Lists Caching

In order to improve performance, ClearQuest caches the content of dynamic lists. When you update the content of dynamic lists using native tools, the update is not available to all existing clients and sessions immediately. Your clients might need to re-login to the database in order to see the changes. Similarly, the dynamic list editor is using an actual dynamic list as a primary trusted source of data for the records. When you initiate a record update, the record content is loaded from the dynamic list first. In an environment where dynamic lists are actively updated from many clients simultaneously, it might cause overwriting, because the cached list values could be used by ClearQuest. In a so changing environment, it is recommended to re-login to the database before starting a dynamic list modification (the same issue exists when you use native tools in the legacy ClearQuest Windows Client). If you rarely use native tools to update dynamic lists (for instance, when a ClearQuest full client is not installed on the Dynamic List Admins' machines, and they use the Editor's Web Client capability to modify lists only), you can select the ClearQuest records as a trusted source of data for the dynamic lists. In order to do so, you need to remove the "Update" action initialization hook from the Dynamic_List record type, and upgrade the user database to apply changes. This would ensure that the most accurate data is used for list modification.

Support

ClearQuest Dynamic List Editor is supported by CQAdmin, inc. Three levels or support agreement are currently offered, starting with free community support at http://forum.cqadmin.org. Consulting services are also available.