Working with fields

You use fields to control the type of data that users can add to a user database. You can do the following with fields:

Add and remove fields
Define the behavior of a field
Add Help text to a field
Use fields to link records
Customize a field by adding hooks

Each record type has a Fields grid that shows the fields associated with that record type. You can use the Fields grid to add new fields to the record type and to modify the properties of existing fields.

Each Rational® ClearQuest® record type includes system fields. These fields are required for every record of that type. System fields appear dimmed in the Fields grid.

Keep in mind a few key points about adding and modifying fields:

To make a new field available to your users, or to hide a deleted field from your users, you must also modify any forms that refer to that field.
After adding or modifying a field, you must check in the schema and apply that version of the schema to the user database.
After you check in your schema, you cannot change the type, size, or DB Name properties of the field. However, you can change the name that you use to refer to the field.

Adding help text to a field

You can provide field-level help for Rational ClearQuest Client users by adding Help text to a field. Help text can describe the field or provide special instructions about how to use the field. Rational ClearQuest Client users can view the help text by right-clicking the field on the record form and clicking Help.

Defining field behavior

Each field has one or more behaviors associated with it. Fields in a state-based record type can have a different behavior in each state. For example, a field can be optional in the Opened state, but mandatory in the Resolved state. Fields in a stateless record type need only one behavior for each field.

Rational ClearQuest software supports the following field behaviors:

Behavior: Description
Mandatory: The user is required to enter a value in this field before applying the changes to a record. Failure to do so results in a runtime validation error. Names of mandatory fields are in red on the record form.
Optional: The user can enter data into this field but is not required to do so. Optional is the default setting for new fields.
Read only: The user can view the contents of the field but cannot modify it. Hooks can modify read-only fields.
Use_hook: Use the field's permission hook to determine the level of user access.

Defining default field behavior

The default behavior of a field applies to the field in every state where you have not explicitly set another behavior. Also, the default behavior is applied when you add a new state to the record type.

To define the default behavior for a field, in the Behaviors grid, click the Default Behavior column of the desired field (the last column on the right) and select a behavior to use as the default.

You can also set the behavior of a field by using a hook. Hooks operate by using the super user privilege and, therefore, can modify any field, even if the field behavior is set to read only.

Modifying a field

You can modify some field properties the Properties window. However, other properties must be modified directly from the Fields grid.

You cannot modify the field data type or DB Column Name after you check in the schema. For fields whose type is SHORT_STRING, you cannot modify the Maximum Length property. To change any of these properties, you must delete the field and create a new field with similar properties.

Changing the name of a field

You can change the name of a field, however, if you explicitly refer to the field by its name in a script, be sure to update your script to use the new name.

When naming fields, be sure not to use any keywords reserved by the database vendor. See your vendor documentation for a list of reserved keywords.

Deleting a field

The following restrictions apply to deleting fields:

You cannot delete, rename, or modify a system field. System fields appear dimmed in the Fields grid.
When you delete a field, the DB Column Name generated for the field (by default, the same as the field name) is retained. If you later reuse the same name to create a new field, a unique DB Column Name is generated.
If you explicitly refer to the name of a field in script code and then delete that field, you must also remove references to the deleted field from the script code.
In the Rational ClearQuest Client, any queries that use a deleted field become not valid.

Using fields to link records

You can use fields to link records of the same type or records of different types. You can link records for these purposes:

To share common data.
To create a parent/child hierarchy.
To link records to share common data.

You can use REFERENCE or REFERENCE_LIST type fields to link records in order to share common data. To link two records, use a REFERENCE field. To link multiple records, use a REFERENCE_LIST field.

For example, you might have the same customer data that must be entered for multiple records (Figure 1).

Figure 1. Sharing common data with REFERENCE_LIST fields The image illustrates the use of reference list fields.

Linking records to create a parent/child hierarchy

You can use REFERENCE or REFERENCE_LIST type fields to link records of the same type to create a parent/child hierarchy. For example, you can relate a parent record that requests the addition of a new feature to one or more child records that describe related tasks, such as documenting the new feature and adding a new tab to the interface (Figure 2).

Figure 2. Example of parent/child hierarchy The image illustrates the relationship between parent and child records.

For more information, see Customizing actions by adding hooks.

Reference lists can affect performance, so you should not overuse them. Each time a form is displayed, or its contents are refreshed from the database (for example, when selecting another row in the results grid of a query), the entire contents of that record are requested from the database. Then for each reference list field, a subsequent query retrieves all the fields of the referenced records that are displayed on the form. If form controls display nested attributes several levels deep, this process can repeat itself until all the display data is retrieved.

Customizing fields by adding hooks

Hooks allow you to customize how fields work. For example, you can customize the schema so that field default values are assigned whenever someone submits a new record. See Validating user input in fields

Rational ClearQuest software provides several field hooks:

Default Value
Permission
Value Changed
Validation
Choice List

To define a field hook, use the Fields grid.

You can customize Rational ClearQuest hooks by incorporating scripts that use the Rational ClearQuest API. When you finish editing a scripted hook, click Hooks > Compile to check the syntax of your code.

For more information, see Field hooks.