Rational ClearQuest is a defect and change tracking system that allows you to submit a change request, track the file changes corresponding to the change request, and manage the change request. There are different Rational ClearQuest clients available: a Windows client, a Web client, etc. The Rational ClearQuest Client for Eclipse allows you to perform the ClearQuest tasks (activities) in an Eclipse environment. This article highlights the important features of the Rational ClearQuest Client for Eclipse and ways to perform ClearQuest tasks in the ClearQuest Client for Eclipse. The tips and sidebars provide more information on some of Eclipse's features and compare the difference between the Eclipse client and the native client. You can download the eGA version of Rational ClearQuest Client for Eclipse at
Once you have downloaded and installed the Rational ClearQuest Client for Eclipse, the first thing you will do in your Eclipse environment is open the ClearQuest perspective. The ClearQuest perspective contains a set of Eclipse views to perform various Rational ClearQuest actions (Fig 1). To open the Rational ClearQuest perspective, select Window > Open Perspective > Other > ClearQuest from the main menu bar.
Fig 1: Rational ClearQuest Perspective
The ClearQuest perspective consists of the following views:
- ClearQuest Navigator View
- ClearQuest Query Results View
- ClearQuest Record Details View
- Console View
- Tasks and Problems Views
Perspectives and Views
Eclipse views are used to present the domain objects. Views support editors and provide alternative presentations as well as ways to navigate the information in your Eclipse environment. For example, the Eclipse Navigator view displays projects and other resources you are working with. Views have their own set of menus and toolbars. The actions represented by the menu items and the toolbar buttons affect only the items within the view.
A perspective defines the initial set and layout of views in the Eclipse workspace. You can change the layout of a perspective by opening and closing views and by docking them in different positions in the Eclipse window. To open a view that is not included in the current perspective, select Window > Show View from the main menu bar. You can customize the perspective using Window > Customize Perspective menu item. To save the customized perspective, use Window > Save Perspective As... menu item.
The ClearQuest Navigator view displays queries, charts, reports and report formats (Fig 2). The navigator view is analogous to the Workspace view in the Windows client. You can create, modify, rename, delete and execute queries, reports and charts.
Fig 2: Rational ClearQuest Navigator View
ClearQuest Navigator view compared to Workspace view in Rational ClearQuest native client
The results of a query are displayed in the ClearQuest Query Results view (Fig 3). The results are displayed in a table tree format. You can browse to an associated child record from the parent record. For example, you can expand a defect node to view attachments, history information and duplicates(). You can perform actions directly on the records displayed on the query results() Selecting multiple records will allow you to perform batch actions on those records.
Fig 3: Rational ClearQuest Query Results View
You can view the details of a record using the ClearQuest Record Details view (Fig 4). The form is shown exactly as defined by the ClearQuest schema. You can perform actions on the record displayed in the view.
Fig 4: Rational ClearQuest Record Details View
The Console view is an integral Eclipse view thatRational ClearQuest uses to display success and failure messages(Fig 5). You can filter the messages shown in the console view using Rational ClearQuest preference settings.
Fig 5: Console View
The Tasks view is an integral Eclipse view that displays the tasks(Fig 6). If you are doing Java development inside the Eclipse environment, the TODO and FIXME tasks present in your code are automatically added to the tasks view. The tasks added are governed by the Window > Preferences > Java > Task Tags preference. You can also create a new task using the Add Task toolbar button and associate a task with a resource.
The Problems view is an integral Eclipse view that shows the compilation errors present in the code developed inside the Eclipse environment (Fig 6). The integration section provides more information on how Rational ClearQuest Client for Eclipse integrates with the different Eclipse views.
Fig 6: Tasks and Problems View
Now that we have been introduced to the different Rational ClearQuest Eclipse views and their respective functionality, we will look at how to perform different Rational ClearQuest activities using the Eclipse client. The Rational ClearQuest Tasks section is organized into two subsections: Basic Rational ClearQuest Tasks and Advanced Rational ClearQuest Tasks. The Basic section concentrates on performing a core set of Rational ClearQuest tasks. The Advancedsection discusses various Eclipse enhancements aimed at improving your workflow. If you want to approach the tasks based on scenarios, you can start at the Typical User Scenariossection.
In the Basic Activities section, we will look at ways to perform some of your day-to-day activities using the Rational ClearQuest Client for Eclipse. This will help you get used to the Eclipse environment as you perform familiar ClearQuest activities. The section starts of with logging on to a Rational ClearQuest database connection, proceeds on to different query actions (creating a new query, editing a query, etc.), continues with actions on the different records (defects, UCM Activities, etc.), and concludes with logging out of the database connection
To connect (login) to a database, use the Login Wizard (Fig 7). The Login Wizard walks through the process of logging into a connection. It can be invoked from the ClearQuest Navigator view (), Eclipse main toolbar () or the ClearQuest menu ().
Fig 7: Different ways to login to a ClearQuest Database
Click on the drop-down on the login toolbar item to view the login menu. Select Login to open the Login Wizard (Fig 8). Select the schema repository () from the Schema Repository page. The Schema Repository combo box shows all the available schema repositories.
Fig 8: Schema Repository wizard page
Fig 9: Additional LoginInformation Wizard Page
Type in the password () in the Authentication Dialog (Fig 10). The Remember the password () option allows you to save the password for subsequent logins. If you choose to remember the password by selecting the Remember the password checkbox, the password is encrypted and stored. The stored password is used for logging in to the database() on subsequent logins.
Fig 10: Authentication Dialog
Once you have successfully logged in, you will notice changes to the ClearQuest Navigator view and the ClearQuest Query Results view. As shown in Fig 11, a new ClearQuest tab () is added to the ClearQuest Navigator view. The connection information () is also shown in the ClearQuest Navigator view. You can expand the connection information node to view the public and personal queries. The ClearQuest Query Results view title () is changed to reflect the connection information based on the last successful login. The connection created using the Login Wizard is persisted for future use. The Subsequent Connections section provides more information on how you can use the persisted connection information to login in to the database.
Fig 11: Navigator and Query Results View After Sucessful Login
The ClearQuest Navigator view can display workspace information from multiple database connections. The Multiple Connections section provides more details on multiple logins and how the workspace information from multiple logins is presented to the user.
Login Wizard in the Rational ClearQuest Client for Eclipse compared with Login dialog available in the Windows client
As shown in Fig 11, the connection information from the most recent successful login location is shown as the top level node in the Rational ClearQuest Navigator view, with personal and public queries folders represented as child nodes. You might have noticed that the ClearQuest Navigator view shows the structure of the query in addition to the query information. You can expand the query by clicking on the plus sign next to the query name to view the filter and the display field information of the query. You can rename, delete, and drag and drop the filters and the display fields. In this section, we will look at the different query actions:
- Create a New Query
- Edit an Existing Query
- Save a Query
- Delete or Rename a query
- View the SQL Version of a Query
- Execute a Query at Startup
- Execute a Query
To create a new query, open the Query Wizard (Fig 12). Select a folder in the ClearQuest Navigator view where you want to create the query. Use the context menu (right-click on a folder to view the context menu). Select New Query () to invoke the Query Wizard. You can also invoke the Query Wizard from New Query () toolbar item.
Fig 12: New Query Context Menu
Select the record type and the query name in the Query Name and Record Type page (Fig 13). the query Name field() is pre-filled with a unique query name. The Next button is disabled if you don't choose a Record Type() or if you provide an invalid query name.
Fig 13: Query Name and Record Type Page
The next page of the wizard depends on whether you select the Create Query from an existing query () check box. If you wish to create the query from an existing query, enable the Create Query from an existing query checkbox and click on the Next button. You can select an existing query on which you want to base your new query using the Start with an existing query wizard page (Fig14).
Fig 14: Create Query from an Existing Query
On the next page, you choose the query filters (Fig 15). The valid filter fields for a record type are shown in the left side of the Select fields to use as query filters page (). You can add a filter by double clicking on the filters present. You can group the filters added to the right side using the group context menu action (). The context menu actions also allow you to delete () filters and groups, and change the grouping between "And" and "Or" (). You can set the default filters using the current settings by checking the Set as Default Filters checkbox. By setting this, every new query created for that record type has those filters initially set.
Fig 15: Filter Wizard Page
|XML error: The image is not displayed because the width is greater than the maximum of 580 pixels. Please decrease the image width.|
The Define Query Filters wizard page is not shown if you didn't select a filter in the previous page. You can define the filter values using the Define Query Filters wizard page (Fig 16, ). The filter values persist when you change the selection in the Define Query Filters wizard page.
Fig 16: Define Filter wizard page
Choose the display fields in the Define Display Fields wizard page (Fig 17). Add display fields by dragging and dropping the fields () or double clicking on the fields. You can change the title (), sort type (), sort order () and show () information of a display field by clicking on the appropriate table cell. To run the newly created query, select the run checkbox () in the Define Display Fields wizard page. You can set the default display fields using the current settings by checking the Set as Default Display Fields checkbox. By setting this, every new query created for that record type has those display fields initially set.
Fig 17: Display Field wizard page
The new query created is selected and shown in the ClearQuest Navigator view (Fig 18). The query is decorated with an *(asterisk) decoration () to indicate that the query needs to be created or saved in the database. The filters () and the display fields () contained in a query are also shown in the ClearQuest Navigator view.
Fig 18: New Query Shown in the ClearQuest Navigator view
You can also create queries from the ClearQuest main toolbar or the ClearQuest menu. Select the "New -> <connection> -> New Query..". The first page of this query wizard is slightly different (Fig). In order to create a query using this wizard, you need to specify the location where the query will be created ().
New Query Wizard in Rational ClearQuest Client for Eclipse compared to New Query Wizard in theWindows client
Now that we have created a new query, we will edit an existing query. You can edit a query using the Edit Query wizard (Fig 19). To invoke the Edit Query wizard, highlight the query and choose Edit () from the context menu.
Fig 19: Edit QueryMenu
The Edit Query wizard allows users to edit the structure of the query. The Edit Query wizard shows the Select fields to use as query filters page, Define query filters page and the Define Display Fields wizard pages. The * decoration on a query indicates that changes to a query need to be saved to the Rational ClearQuest database. The ClearQuest Navigator view shows the structure of the query i.e. filters and the display fields contained under the query are displayed in the ClearQuest Navigator view. If you want to edit only the filters, you can invoke the Edit Filter wizard by selecting the context menu action Editon a filter node. The Select fields to use as query filters page and the Define Query Filters page are the two pages contained in a Edit Filter wizard. Similarly, to edit the display field, you can invoke the Edit Display Field wizard by selecting the Edit menu action on a display field. The Edit Display Field wizard shows only the Define Display Fields page.
As discussed in the earlier sections, unsaved queries are displayed with an * decoration (Fig 20, ). To save an unsaved query to the database, highlight the query and select the Save Context Menu () action. After the save operation, the *decoration is removed () indicating the unsaved changes are committed to the Rational ClearQuest database. You can also save all the unsaved queries belonging to a connection by highlighting the connection node and using the Save All context menu action.
Fig 20: Save Query
You can also save a query using the Save toolbar item().
You can delete or rename a query using the Delete (Fig 21, ) or Rename () query context menu action (highlight the query; right click to view the context menu actions). A confirmation dialog is shown to confirm the delete operation.
Fig 21: Delete or Rename a query
To view the SQL version of a query (Fig 22), highlight the query and select the View SQL menu action (). The SQL of the query is shown in the SQL Query view ().
Fig 22: SQL Query View
SQL queries can only be edited inside the SQL Query view. To convert a query to an SQL query, highlight the query and select Utilities > Convert to SQL Query. A query cannot be converted to an SQL query if you don't have permission to create a new SQL query. The SQL query created by the conversion process is not automatically saved to the server. You can save the query using the Save Query action. To edit an SQL query, view the SQL of the query using the View SQL menu action and select the Edit toolbar button in the SQL Query view. To save the changed SQL statement, use the Save toolbar button in SQL Query View.
The SQL Query view is not part of the default ClearQuest perspective. You can open the SQL Query view using Window > Show View > Other > ClearQuest > SQL Query View.
If you want to execute a query when you connect to a Rational ClearQuest database, you need to set the query as a startup query (Fig 23). To set the query as a startup query, highlight the query and select Utilities > Run at Startup. A startup query is indicated by the checkmark () decoration.
Fig 23: Startup Query
To unset a query as a startup query, use Utilities > Run at Startup(). The checkmark is removed when you unset the startup nature of the query. The Beta version of the Rational ClearQuest Client for Eclipse does not allow users to run a chart or a report at startup.
You can execute a query by right-clicking on a query and selecting the Run action from the context menu. After execution, the query results are displayed in the ClearQuest Query Results view (Fig 24). The columns and the order of the records are formatted according to the query's display field settings. After executing the query, you will notice additional changes in the ClearQuest Query Results view. the database information is displayed in the title of the view (). The name of the query executed (), the type of record (), number of records returned (), and the number of selected records () are shown in the status bar of the Query Results view.
Fig 24: Query Results Shown in the ClearQuest Query Results View
You can expand the records to view the record types referenced by the parent. Expanding the record types further will show the referenced records. For example, expanding a defect record will show three nodes: Attachments, Duplicates, and History. Expanding these nodes will show the attachments, duplicates, and the history records associated with the defect.
If the selected query contains dynamic filters, a dynamic query window is shown to set the criteria (see Fig 25). The tabs in the dynamic filter dialog correspond to the different dynamic filters present in the query (). Click OK () to execute the query based on the criteria set in the dynamic query dialog. You can cancel the execution of the query by using the cancel button ().
Fig 25: Dynamic Query Dialog
There are several ways to execute a query. You can execute a query by double-clicking on a selected query or use the Run menu on the selected query.
The Query Results view displays the Query Results retrieved from executing the query. To navigate back to the query from the Query Results view, use the Show Query in Navigator menu action.
If the number of results exceeds the maximum result count in the Preferences, then a message appears confirming whether or not you want to execute the query. This measure is implemented because executing queries with a large number of results affects the performance adversely. To change the maximum results count, go to the Preferences.
The dynamic query window can only show a certain number of dynamic filters in the viewing area (Fig 26). If a query contains dynamic filters that can't be accommodated in the viewing area of the dynamic filter dialog window, the excess filters are displayed off-screen ().
Fig 26: Excess Dynamic Filters Shown Off-screen
As we saw in the Execute a Query section, the results of an executed query are displayed in the ClearQuest Query Results view. Each query executed uses a different ClearQuest Query Results views to display the results (Fig 27). This means that when multiple queries are executed, multiple ClearQuest Query Results views will appear in the ClearQuest perspective. For each ClearQuest Query Results view, the location information () and the query path name () are shown in the title of the view and the status bar. When you execute a query, the results are shown in a new ClearQuest Query Results view if there is no ClearQuest Query Results view that is associated with the query. The different ClearQuest Query Results views are stacked on top of each other.
Fig 27: Multiple Query Results views
If a previous query is executed again, the results will be displayed in the ClearQuest Query Results view already assigned to that query. When you log out of a database, all the views assigned to queries from that database are closed automatically.
Designating a Rational ClearQuest Query Results view for every executed query is the default behavior of the Rational ClearQuest Client for Eclipse. You can choose to change the behavior in the Preferences.
In this section we will look at the actions that can be performed on records using the Rational ClearQuest Client for Eclipse. These actions include:
- Viewing a Record's Information
- Performing Actions on a Record
- Refreshing Records in the ClearQuest Query Results View
- Creating Records
- Finding Records
The ClearQuest Record Details view displays the complete information set of a record (Fig 28). To display a record in the ClearQuest Record Details view, select the Details action from the record's context menu.
After the Details view is displayed, whenever a new record is selected, the view will automatically display the information of the selected record. The record form is displayed exactly as designed in the schema (see Fig 28). Selecting different tabs displays the appropriate information. The selected record's database information is shown in the view title ()
Fig 28: ClearQuest Details View with Selected Record
You can change when and how the ClearQuest Record Details view is shown by changing the Preference settings.
You can perform actions on the records from either the ClearQuest Query Results view or the ClearQuest Record Details view.
The ability to perform record actions directly from the ClearQuest Query Results view means that it is very useful to add this view to your development perspective. you can then perform most ClearQuest activities without changing to the ClearQuest perspective.
In the ClearQuest Query Results view, the possible actions for a Record are displayed in the record's context menu (Fig 29). The context menu actions are organized into three categories:
- Change State- The change state actions () allow you to transition a record from one state to another.
- Modify- Actions through which you modify () the record information.
- Utilities- Utility actions () like Delete and Add Attachment.
Fig 29: Record Actions
When you initiate an action from the menu, a window is shown to perform the action (Fig 30). Fill in the required information and complete the action. The action determines what kind of window appears. For example, a modify form is shown when you select the modify action while a duplicate action form is shown when you initiate a duplicate action.
Fig 30: Modify Action displays a Modify Record window
You can also perform actions on referenced records (child nodes) (Fig 31, ) from the ClearQuest Query Results view. The available actions depend on the selected record.
Fig 31: Action depends on the selected record
The same action performed on a Record can be applied to multiple records. Highlight the records you want to perform the action on and initiate a common action. The usual window will appear, except instead of an Apply button, there is an Apply All button. Clicking the Apply All button will perform the action on all the selected records.
Performing actions in the ClearQuest Record Details view is done within the view rather than from a context menu (Fig 32). The actions are located in the top right corner () of the view, and are organized similarly to the ClearQuest Query Results view. Actions that are contained in a control (such as attachment actions) are initiated from within the form. Other actions, such as Modify, use the record form in the ClearQuest Record Details view to perform the action.
Fig 32: Actions can be performed on the details view
Take a look at the Edit () icon in Fig 32. You will notice this button next to all multi-line text controls. Clicking the Edit icon brings up an edit text dialog, which provides you with a larger, resizable area to edit the text.
A record in the ClearQuest Query Results view is refreshed when an action is performed on the record. You can refresh a record manually by right-clicking a Record and selecting the Refresh action from the Context Menu. Multiple records can be refreshed by using the Refresh action on multiple highlighted records.
The entire result set can be refreshed by re-running the query. you can quickly re-run the query by using the Re-run Query action (Fig 33, ) in the Rational ClearQuest Query Results View toolbar.
Fig 33: Refresh Query Results
You can change how the ClearQuest Query Results view is refreshed by modifying the Preferences.
Queries are worthless if there are no records to query upon. If you have create authority in one or more ClearQuest databases, you can perform a submit record action (Fig 34) using the Eclipse toolbar Submit button () or the New menu item () under the ClearQuest main menu. Click on the drop down to display a context menu with active databases. the database you select will determine where the record is created. Expanding the database entry will show the different records you are allowed to create. The stateful record names are displayed as a top level menu actions while the stateless entries can be accessed via the Other submenu.
Fig 34: Submit NewRecord
Selecting the desired record type displays a Create Record window. Fill in the required fields and submit the record.
You can also create records from the ClearQuest Query Results view (Fig 35). The submit record action () is located in the ClearQuest Query Results view toolbar.
Fig 35: Submit New Records from Query Results View
The create action allows you to submit records to the database linked to the particular ClearQuest Query Results view. Since you can only create records in the linked database, the context menu displays only record types for that database. In addition, clicking on the main submit record action will invoke the submit dialog for the Default record type of the current schema.
The find record action allows you to retreive a specific record and view or perform actions on it. This prevents you from having to execute a query just to view or perform actions on a record. The action is initiated from either the Eclipse toolbar Find Record or the Find Record menu item under the ClearQuest main menu (Fig. 36).
Fig 36: Find Records
The find dialog (Fig 37) consists of a record type (), a search all record type option (), id search text box () and a check button ().
Fig 37: Find Record Dialog
You can enter partial identifying strings in the ID text box.Clicking find tells you what record will be shown based on your id search string. The record found is displayed in the ClearQuest Record Details view.
You can open, add, delete and edit an attachment using The Rational ClearQuest Client for Eclipse. You can perform actions on an attachment either from the ClearQuest Query Results view or the ClearQuest Record Details view. The ClearQuest Query Results view shows the attachments as a child node if the particular record type supports attachments. In this section, we will look at the different attachment actions:
To create an attachment (Fig 38), highlight the record and select the Utilities > Add Attachment () context menu action. An Add Attachment window appears, allowing you to select the file that needs to be uploaded as an attachment.
Fig 38: Add Attachment
To delete an attachment (Fig 39), highlight the attachment and select the Delete () menu action.
Fig 39: Delete Attachment
To open an attachment, highlight the attachment and select Open from the context menu. The attachment file is temporarily stored under the "ClearQuestAttachment" project. The file is either opened in an Eclipse editor or in an external editor outside of Eclipse. The Window > Preferences > Workbench > File Associations preference determines whether the file is opened inside or outside the Eclipse shell. You can modify The file opened in an Eclipse or an external editor. When you save The file, the attachment is automatically saved to the Rational ClearQuest database. The temporary attachment file is automatically deleted when you close the corresponding editor.
If you prefer to perform attachment actions from the ClearQuest Record Details view, just initiate the actions from the attachment control in the form.
Charts, reports and report formats are shown in the ClearQuest Navigator view (Fig 40, ). These objects are manipulated in the same fashion is Query objects. The following actions are discussed:
- Execute a Chart
- Create a copy of a Chart, Report and Report Format
- Delete or Rename a Chart, Report and Report Format
Fig 40: Charts and Reports in Navigator View
Chart execution is performed similar to query execution. After the chart is finished executing, it is displayed in the ClearQuest Chart View (Fig 41). If more than one chart is executed, a ClearQuest Chart view will be shown to display the chart. Similar to multiple query execution, you can change whether or not each chart executed is designated its own view. You can change the behavior in the Preferences.
Fig 41: ClearQuest Chart view
If more than one chart is executed, a ClearQuest Chart view will be shown to display each chart. Similar to multiple query execution, you can change whether or not each chart executed is designated its own view. You can change the behavior in the Preferences.
Charts, Reports, and Report Formats can be copied and pasted in a folder. The copied objects must be saved in order to persist in the database.
The delete and rename action is done exactly the same as for a query.
Logging off (disconnect) from the ClearQuest database (Fig 42) is handled similarly to logging in, except the ClearQuest Navigator view () and toolbar () buttons act differently. The ClearQuest Navigator view logout action is context sensitive: The Logout action is performed on the connection selected, whereas the Logout toolbar menu action or the ClearQuest logout menu() action can be performed on any logged in location.
Fig 42: Logoff Menu
The ClearQuest Navigator view logout button is enabled only when a connection node is selected. Click on the ClearQuest Navigator view logout button to disconnect the selected connection node. You will be presented with a logoff confirmation dialog to confirm the logoff operation. The logoff operation removes the connection node information from the ClearQuest Navigator view and closes all the associated ClearQuest Query Results views.
The logoff toolbar button (or the logout ClearQuest menu) in the main Eclipse toolbar functions similarly (Fig 43) to the ClearQuest Navigator view login action. All the logged in locations are shown in the logout toolbar drop down menu. The connection you most recently logged into is marked with a checkmark (). Selecting a location from the drop down menu will disconnect you from that location. Clicking on the main toolbar button will disconnect you from the connection marked with the check mark.
Fig 43: Logout Drop Down menu displays All Logged in Connections
The Rational ClearQuest Client for Eclipse saves the connection information for every successful login (Fig 44). The saved connection information allows you to login to a database connection without going through the login wizard. The saved connection information can be accessed from any Loginbutton. A login menu appears when you click on the drop-down arrow on the Login button. The Login Wizard is the first entry on the login menu. The remaining entries () in the login drop down menu represent all other stored connection information. There is a maximum of five connections stored at one time. When a new connection is saved to the list, the oldest connection is removed.
Fig 44: Subsequent Connections
Click on the connection information to login in to a database connection. If the password was not saved, you will be prompted for the authentication information. You might have noticed a check mark () next to one of the entries in the login menu. The check mark indicates the most recently accessed connection. The checked connection is the default connection. Click on the Login toolbar button to automatically connect to the default connection. This enables you to connect to a previous connection with one click.
In the Basic Rational ClearQuest Tasks section, we looked at how to perform day-to-day ClearQuest activities using the Rational ClearQuest Client for Eclipse. In this section we will look at some of the advanced features available in Rational ClearQuest Client for Eclipse and how they improve your overall workflow. The section also explains in detail how The Rational ClearQuest Client for Eclipse seamlessly integrates with Eclipse to help us perform various ClearQuest tasks. The Advanced Rational ClearQuest Activities include:
- Multiple Connections
- Background, Concurrent Actions
- Integration with Eclipse Views and Editors
- Manage User Profile
- Preference Settings
Using the Rational ClearQuest Client for Eclipse, you can login to multiple Rational ClearQuest databases (Fig 45). The connection information of the different databases ( ) with the appropriate workspace objects are shown in the ClearQuest Navigator view.
Fig 45: Workspace Information of Multiple Connection Nodes
You can perform operations on the workspace objects corresponding to the different database connections in exactly the same way as a single database connection. The ClearQuest Query Results view displays the connection information to distinguish which connection produced the results (Fig 24, ).
Some Rational ClearQuest tasks such as login and query execution can be time consuming. The ClearQuest Client for Eclipse identifies all the time consuming ClearQuest tasks and performs these tasks in the background. This allows you to work on other Eclipse or ClearQuest tasks while time consuming ClearQuest tasks are performed in the background. Some of the time consuming actions are even executed concurrently to provide the maximum time efficiency. In this section, we will look at the different ClearQuest tasks that are executed in the background. The different background actions we are going to discuss include:
The login process involves authenticating the user, retrieving the schema information and then executing the startup queries, charts and reports. To improve productivity, the login is performed in the background. If the authentication information is valid, a new connection node is added to the ClearQuest Navigator view. If the authentication information is not valid, an error message dialog is shown to the user.
The Eclipse status bar displays information regarding the background action executed and percentage of completion. You can view information on all the scheduled background actions using the Eclipse Progress view. You can open the progress view using Window > Show View > Others > Basic > Progress from the main menu bar (Fig. 46).
Fig 46: Background Actions in the Progress view
As you might expect, query execution is the most time consuming ClearQuest task. The Rational ClearQuest Client for Eclipse performs query execution in the background. This allows you to work on other Eclipse tasks while a large query is performed in the background. Once the query is executed, the results are displayed in the ClearQuest Query Results view. When you execute multiple queries at the same time, the execute query operations are performed concurrently.
The record creation action is also performed in the background. Once the record submission is finished, a message is displayed in the Console view to report the results.
The Tasks and Problems views display the tasks and the compilation errors present in your development code. The Rational ClearQuest Client for Eclipse provides an integration with the Eclipse Tasks and the Problem views by allowing you to create a Rational ClearQuest record corresponding to the task or problem. To create a Rational ClearQuest record based on a task (Fig 47), highlight the task present in the tasks view and select ClearQuest > New ClearQuest record () from the context menu.
Fig 47: Create Rational ClearQuest Record
The record selection dialog displays the list of logged in ClearQuest connections on the left side and record types of the selected connection on the right (Fig 48). You can either choose to use a logged in location () or create a new location using the New Connection () button. Clicking on the new connection button opens the Login Wizard Choose the record type() and click OK to invoke the new record dialog. The integration automatically populates the Headline and Description fields of the record with Task information, provided that the record type has those fields.
Fig 48: Record Selection Dialog
The problems or tasks are shown in a Java editor using markers. The Rational ClearQuest Client for Eclipse allows you to create a ClearQuest record based on a problem or a task marker from a Java editor (Fig 49). To create a ClearQuest Record, right click on the marker and select ClearQuest > New ClearQuest Record..(, ).
Fig 49: ClearQuest Records Created From a Java Editor
The connection and record type selection made in the record selection dialog persists across sessions (Fig 50). The record type and the connection information persisted can be used to create a new ClearQuest record from the Tasks view or Problems view with a single click. ()
Fig 50: ClearQuest record selection Persists Across Sessions
Setting the Email options enables notifications when actions are performed. The Email Options wizard is initiated from the main menu (Fig 51), select ClearQuest -> Admin -> EmailOptions... ().
Fig 51: Email Options menu
The first page requests Email Provider information and the second page allows you to configure the email provider. Click finish to apply the changes.
You can edit user information using the the Rational ClearQuest Client for Eclipse. To access the user profile and make changes (Fig 52), select ClearQuest -> Admin -> Change User Profile... from the main menu () from the ClearQuest Query Results view.
Fig 52: Change User ProfileToolbar Item
The User Profile dialog allows you to modify the password, full name, email, and phone number of the logged in user (Fig 53).
Fig 53: Manage User Profile
Changes made to the User Profile are immediately applied to the User database.
ClearQuest Multisite is supported in the ClearQuest Client for Eclipse. Basic actions are performed the same way as a non-multisite environment, except available actions are restricted depending on mastership. Workspace objects in the ClearQuest Navigator view (Fig 54) displays mastership information with the addition of a lock icon (). The presence of a lock indicates the workspace object is mastered remotely.
Fig 54: Multisite Support in the ClearQuest Navigator view
The ClearQuest Query Results view (Fig 55) displays mastership information in an additional display column (). Once again, the presence of a lock indicates the record is mastered remotely.
Fig 55: Multisite Support in the ClearQuest Query Results view
Mastership for records shown in the ClearQuest Record Details view (Fig 56) is not initially apparent. Only trying to perform a Record action displays Mastership required (), indicating the record is mastered remotely.
Fig 56: Multisite Support in the ClearQuest Record Details view
You can customize the behavior of the Rational ClearQuest Client for Eclipse to your liking by modifying the preferences (Fig 57). To access the preferences, select Window > Preferences from the Eclipse menu bar. Navigate to the Team > ClearQuest () node and expand it. An additional Rational ClearQuest preference page is shown ().
Fig 57: Preference Settings
|Bring console to the front automatically when there is message coming through||Enabling this option shows the console view when a new message is displayed. Not enabling this option silently displays a new message in the Console view.||Not enabled|
|Show successful messages in an informational dialog||Enabling this option displays successful messages in a dialog. Not enabling this option will not display successful message in a dialog.||Not enabled|
|Show successful messages in the Console||Enabling this option displays successful messages as an entry in the Console view. Not enabling this option does not display successful messages in the Console view.||Enabled|
|Enable verbose messages||Enabling this option produces messages after every action. Not enabling this option produces messages for only certain actions.||Not enabled|
|Enable Multiple Query Results Views||Enabling this option designates a ClearQuest Query Results view for every query executed. Not enabling this option designates only one ClearQuest Query Results view for all executed queries.||Enabled|
|Automatic refresh (user initiated actions)||
||Refresh highlighted view items(s) after each action|
Fig 58: ClearQuest Advanced Preferences
|Open ClearQuest Details view automatically whenever there is item(s) selected in the ClearQuest Query Results view||Enabling this option automatically opens the ClearQuest Record Details view when a record is selected in the ClearQuest Query Results view. Not enabling this option does not automatically open the ClearQuest Record Details view when a record is selected in the ClearQuest Query Results view.||Not Enabled|
|Maximum number of records in the ClearQuest Query Results view||This value determines the largest query results size allowed in the ClearQuest Query Results view.||1000|
|Chart Height||This value determines the height resolution of charts displayed in the ClearQuest Chart view.||500|
|Chart Width||This value determines the width resolution of charts displayed in the ClearQuest Chart view.||800|
|Allow multiple chart views||Enabling this option designates a ClearQuest Chart view for every chart executed. Not enabling this option designates only one ClearQuest Chart view for all executed charts.||Not enabled|
|Set chart JPEG compression strength||This value determines the amount of compression used for charts displayed in the ClearQuest Chart view. Increasing this value produces lower quality images, but requires less time to execute and display the chart.||0%|
|ClearQuest attachments project name||This value determines the Java project name used to store viewed attachments.||ClearQuest Attachments|
In this section, we will walk through the typical scenarios performed by users of varying roles. The intent is to show how different users take advantage of the Rational ClearQuest Client for Eclipse. The roles covered are: manager, project lead, developer and quality engineer.
Sue, the manager, wants to check the status of a particular iteration. Sue clicks on the login button to logon to the default connection. She decides to run a defect trendchart showing the number of defects opened by week. After noticing an undesirable trend, she runs a defect trend chart showing the number of defects owned by developers each week. She sees that the developer, John, has a large number of defects. To see what areas John is getting defects in, she runs a query that returns the defects owned by John, sorted by component. Sue then determines the component that needs additional help and discusses the issue with the project lead, Glen.
Glen, the project lead, just finished a discussion with his manager about John's large defect count. Glen runs a query to verify John's defects. Seeing that John's defects are grouped into two different components, Glen decides to lighten John's load by getting Barney, another developer, to take care of one of the components. After talking to John and Barney, Glen is ready to assign the defects. Glen highlights all the defects he wants to assign, and performs the assign action on them. Completing the batch record action, Glen decides to talk to the quality engineer Nathan, who is responsible for the component John is working on.
Barney, a developer, runs a query for all his active defects. He sees the 10 defects just transferred from John. Locating a high severity defect, he starts to solve it. He checks out two files to fix the defect. He notices a TODO task marker in oneof the files. Seeing that this TODO might get overlooked, he submits a defect from the Task view. After solving the defect, he checks in the two files and changes the defect to the resolved state. As it is a high severity defect, he calls Nathan, the quality engineer who submitted the defect, to discuss the tests that need to be performed to verify the defect.
Nathan, a quality engineer, finishes talking to Glen about John's component. Nathan decides to re-validate all the active defects since they have been back-logged for a few weeks. He runs a query for all active defects and validates the highest severity ones first. Soon, he gets a call from Barney regarding one of his high severity defects. He agrees with Barney the defect was solved differently than expected, but will prevent further problems in the area. Nathan proceeds to validate the defect, adding a note specifying how the defect changed the component. In the process of validating the defect, he notices that Barney misspelled some text. He takes a screen shot of the text and submits a low severity defect, attaching the screenshot as an Attachment.
Hopefully now you know what the Rational ClearQuest Client for Eclipse offers. Rational ClearQuest client for Eclipse provides most of the ClearQuest functionality inside the Eclipse environment. It also provides a seemless integration with many of the Eclipse views and editors. Now you can perform change management as part of your Eclipse workflow, rather than making it a task of its own.
The authors would like to thank Nacia Owens, Stefan Schurman, Brian Gillan, Steve Speicher and Jeanette Deupree (all IBM) for providing constructive comments on the article.
Balaji is a software developer at IBM. He is currently involved in the development of Eclipse plug-ins for internal IBM products. Balaji got his Masters in Computer Science at Virginia Tech. You can contact him at firstname.lastname@example.org.