Tool Mentor: Viewing the History of a Defect

Purpose

This tool mentor tells how to view the history of a ClearQuest defect. It also tells the ClearQuest administrator how to set up the ClearQuest defect form so it includes a History control that will allow ClearQuest users to view and track the history of defects.

Rational Unified Process Related Steps:     Define Configuration Status Reporting Requirements.

                                                                    Report Defect Data

Overview

This Tool Mentor is applicable when running Windows NT 4.0.

Defects move through a pattern, or life cycle, from submission through resolution. In ClearQuest, each stage in this life cycle is called a state, and each movement from one state to another is called a state-transition.

Each state has specific actions associated with it, as you move a change request from one state to another, you will notice that fields associated with that state become required, and certain business rules apply. For example, within ClearQuest’s default application, the Impacts Doc field is only mandatory when a defect is moved to the Resolved state.

By setting up rules for state-transitions, you can double-check that your change requests are being thoroughly completed and tracked.

Within the ClearQuest Designer, ClearQuest administrators can customize states and the actions associated with them. For example, in the default application, ClearQuest is set up to notify users with e-mail when defects are assigned to them.

Within the ClearQuest client, you can view the history of a defect. This command displays information about the defect including the date actions occurred (such as moving to the next state or making a modification), the user name, the action name, the old state, and the new state, if applicable.

Tool Steps for Viewing the History of a Defect

The View History command displays the changes in the state of a record and the dates on which the changes occurred. The contents of the View History dialog are read-only.

To view the history of a record, you first must run a query whose results include that specific record.

1. Run a query that includes the defect you want to view.
2. In the Result set tab, select the record whose history you want to view.
3. From the menu bar, choose View > History.
4. To close the dialog, click .

Tool Steps for adding a History Control to ClearQuest’s record form

ClearQuest Designer lets you create customized forms for submitting, viewing and modifying records. You can create forms for each record type in your schema.

You can include a history control on a form to display the actions that have been incurred on the given record. The history control displays information about the action including the date the action occurred, the user name, the action name, the old state, and the new state.

1. Check out the schema you want to work with.
2. Add a history control to the form.
3. Check in the schema.
4. Upgrade the database.

Check out the schema you want to work with.

When you want to edit a schema, you must check out the schema from the schema repository. When you check out a schema, ClearQuest creates a new version of the schema for you to edit.

1. Choose File > Open Schema.
2. Choose Check out a new schema to edit or Continue editing previously saved work. In addition to checking out a schema for editing, you can also open the schema for viewing. You can also continue working on a schema that you checked out in a previous session.
3. Select a schema and version to check out and click Next.
4. Enter a comment in the Comments text box and then click Finish.

Add a history control to the form.

You can include a history control on a form to display the actions that have been incurred on the given record. The history control displays information about the action including the date the action occurred, the user name, the action name, the old state, and the new state.

To add a history control to a form:

1. In the Workspace, expand Record Types or Record Types - Stateless until you see the form you want to modify.
2. Double-click the form you want to modify.
3. Choose the tab that you want to place the control on.
4. Choose Form Controls > History to select the type of control you want to add. Alternatively, you can select the History tool from the Control palette.
5. Drag the mouse to place the control on the form.
6. Double-click the History control to open its Properties dialog.
7. Set the properties for the control.

Check in the schema.

When you finish editing a schema, you should check it in to save your changes and make it available for use by your databases. When you check in a schema, ClearQuest increments the version number of the schema in the schema repository. You must check in a schema before you can use it with any of your user databases.

1. Choose File > Check In. ClearQuest runs the validation script on the schema.
2. Review the validation results and make changes to the schema as needed to correct any validation errors. When the schema passes validation, ClearQuest displays the Checkin dialog.
3. Choose File > Check In. ClearQuest runs the validation script on the schema.
4. Review the validation results and make changes to the schema as needed to correct any validation errors. When the schema passes validation, ClearQuest displays the Checkin dialog.
5. The Comment text box displays the original comment you typed in when you checked out the schema. Modify your original comments as needed to reflect the changes you made to the schema and click OK. ClearQuest proceeds to check in the schema.

Notes:

• You must validate your schema changes before ClearQuest lets you check in a new version of the schema. To validate your changes, choose File > Validate. If you cannot validate all of your schema changes, you can save your schema changes and continue editing at a later time. You can also undo your checkout and revert the schema to its previous version.
• To get help about the cause of a validation error, select the validation error message and right-click to display a shortcut menu. Choose What’s This?

Upgrade your database(s).

To apply an updated schema to an existing database, you must upgrade the database.

1. Choose File > Upgrade Database. ClearQuest prompts you to backup the schema repository and the user database before upgrading. If you haven't already backed up your database, do it now. Then, click Yes.
2. Select a database from the Database list. Click Next.
3. Select a schema version from the Versions list. Click Finish.

Notes:

• Before upgrading a database, make sure no users are connected to it. ClearQuest prevents new users from connecting to a database while you are upgrading it, but does not disconnect users who are connected before you begin the upgrade.
• Always upgrade a test database to the latest schema version before changing your production database. You should also check your changes by using the ClearQuest client, especially if you have modified hook code.
• You cannot roll back a database after you have upgraded it with a newer schema version. To protect your database, you should back up the database before upgrading it.
• ClearQuest does not provide a mechanism to back up databases. Check your database vendor documentation for details on how to backup your database.