Given a class design, you can easily create an object reference to implement a relationship with another object. There are two types of references: REFERENCE, which is for relationships whose cardinality is 0..1, and REFERENCE_LIST, for cardinality of 0..n.

For either type of field, you must provide information that specifies the record type to which the field refers. You can fill this in by using the property dialog for the field in the record (Figure 8-2) and then using the Reference To choice list to select the record type to reference.

Figure 8-2. Changing field properties

The given field can refer to either a state-based or stateless record type. (Note that you need to create the record type before it will appear in the choice list.) Typically, you’ll want to create all of your records first and then come back to define your relationship-based fields.

If the relationship has the ability to navigate in both directions, you can specify a back-reference value (Figure 8-3).

Figure 8-3. Specifying a back-reference value

ClearQuest will create a new field with the specified name (Figure 8-4).

Figure 8-4. Creating a new field

Sometimes you want to restrict the user to multiple choices for a field value. You can do this by selecting the field and then selecting the type of choice list you wish to use. You have the following options.

Select NONE if you don’t want the user to have a choice list.

You can also specify a script that will return a list of choices for the user. When you select a script, a dialog will appear and ask you to choose one of these options.

[S.8.1, S.8.2] Your script can be written in BASIC or Perl. The following script is written in VBScript. Note that the name of the sub is the <fieldName>_ChoiceList, where <fieldName> is the name of the field for which the choice list script is written.

Sub fieldName_ChoiceList(fieldname, choices)
    ' fieldname As String
    ' choices As Object
    choices.AddItem("Blue")
    choices.AddItem("Red")
    choices.AddItem("Yellow")
    choices.AddItem("Green")
End Sub

The following is the Perl equivalent.

sub fieldName_ChoiceList {
     my($pFieldName) = @_;
     my @returnChoices;
     push @returnChoices, "Blue";
     push @returnChoices, "Red";
     push @returnChoices, "Yellow";
     push @returnChoices, "Green";
     return @returnChoices;
}

[A.8.3] Dynamic list field hooks are convenient for lists that you want to change frequently because they enable you to update the list values without changing the schema.

Before you can use a dynamic list choice for a field, you must first create a dynamic list in the database schema.

First, right-click on Dynamic List Names within your database schema workspace, and then select Add from the popup menu that appears (Figure 8-5).

Figure 8-5. Adding a dynamic list

Then type the name of the list in the new list item. Now you can use this dynamic list in connection with any field’s choice list, as shown in Figure 8-6.

Figure 8-6. Using a dynamic list

Simply go to the list for any field, and then select Dynamic List. A dialog box opens (Figure 8-7). Select which dynamic list you wish to use.

Figure 8-7. Dynamic List Name window

Now, you’re probably asking yourself, “What about the values in the list?” You actually use a dynamic list in the ClearQuest client application without changing the schema. Please note, though, that you must have schema designer, dynamic list administrator, or superuser privileges to edit a dynamic list. To change or add values to a dynamic list in the ClearQuest client, select Edit → Named Lists and select the list you want to edit.

Setting up states, actions, and transitions for your classes (records) is typically a two-step process: Add the states, and then add the transitions. Note that you shouldn’t add a single state and then its transitions because the tool wasn’t designed to work in this fashion, and you will quickly become frustrated. It’s best to add all of the states first, then put in the transitions, and specify the actions last.

The first step is to open the record to which you want to add states, and then open States and Actions → State Transition Matrix (Figure 8-8).

Figure 8-8. State Transition Matrix item

To add a state, click on the empty box to the left-hand side of the spreadsheet, and then type a name for the state (Figure 8-9).

Figure 8-9. Adding a state to the matrix

Go ahead and do this for each of the states in your state net.

Now we’re ready to add the transitions for each state. (ClearQuest Designer allows the addition of transitions only between states that already exist.)

To add a transition, go to the Actions item (Figure 8-10).

Figure 8-10. Actions item

Now, right-click on the left column, or on the Actions item itself, and then select Add Action (Figure 8-11).

Figure 8-11. Selecting Add Action

You will need to give your transition a name, which can come from your design. Figure 8-12 shows the dialog box.

Figure 8-12. Naming your transition

If you have an unnamed transition, now is a good time to name it. This name should be a verb phrase. You also need to set the type to Change_state.

Now select the State tab. You should see a list of source states and destination states. Look in your design to see if there is more than one state that this transition can come from, and select all of the associated source states (Figure 8-13).

Figure 8-13. Selecting a source state

This is how you would map the given state net to the state source and destination values.

Now the transition should be defined. To check this, click on the State Transition Matrix icon; you should see your action show up as a transition between the given states, as shown in Figure 8-14.

Figure 8-14. Checking your transition

You should be able to define the rest of your transitions the same way. When you’re done, make sure that everything matches your state net diagrams.

Actions can be used for more than just transitions. For example, if an action is performed on a given record, that action doesn’t change the record’s state. Actions generally map to the operations on the classes within your design.

ClearQuest Designer allows for several different types of actions. The list in Table 8-2, which was taken directly from the ClearQuest Designer’s Guide, shows the various types and what they can be used for.

Open the record for which you want to add a form from the schema browser on the left side of the workspace editor. Select Forms, and then right-click and select Add (Figure 8-15).

Figure 8-15. Adding new forms

The window shown in Figure 8-16 should appear.

Figure 8-16. Adding New Forms editor

ClearQuest provides a graphical user interface editor that you can use to add controls, fields for input or display, restrictive views, and tabs for categorizing information.

Before you start filling in your user interface design, go back and look at your use cases again. Specifically, determine which users have access to what records. Then look inside the use cases for the classes being used.

Permissions to view and edit the user interface are limited to the tabs of the individual forms that you create. In order to use this feature, you need to create user groups; this will help you set the permissions on the individual tabs. (See Working with Users and Roles in Chapter 7 for information about user groups.)

To set permissions for a tab, click on the tab, then right-click and select Tab Properties (Figure 8-17).

Figure 8-17. Selecting Tab Properties

A window appears showing the properties of the given tab. You can change the permissions for the tab using this window, as shown in Figure 8-18.

Figure 8-18. Tab Properties window

Choose All Users if you want to allow all users to have access to this tab; otherwise, choose only those groups for which you want to provide access.

Tabs are not useful without any associated information or controls. So, you may want to add fields from the given record for this tab. Looking at the use cases again, you can easily find which tabs you need to create and what fields you need to put on each tab. The fields available for the tab are found in the Field List popup, as shown in Figure 8-19.

Figure 8-19. Available tab fields

Basically, you can drag and drop the fields from the Available Tab Fields popup onto the drawing area for the tab. The type of field will dictate what kind of field input control will be used. Each field that you add comes with an input text box and a label. Depending on the type of field, ClearQuest will change different properties of the text input. The best way to see and change the text input field is to double-click on the input box, as shown in Figure 8-20.

Figure 8-20. Double-clicking a field to edit

Double-clicking will cause ClearQuest to display the dialog box shown in Figure 8-21.

Figure 8-21. General tab of the Text Box Property Sheet window

Notice that there are four tabs for the properties of the text box for the given field. The General tab also contains the name of the field and the name of the label for the text box.

Now click on the Extended tab (Figure 8-22). This tab displays information about the text box and allows you to establish different characteristics.

Figure 8-22. Extended tab

Now click on the Date/Time tab (Figure 8-23). If the field is a date/time field, then the Date and Time check boxes should already be checked. You can select what type of date format to use.

Figure 8-23. Date/Time tab

Now click on the Context Menu Hooks tab (Figure 8-24). This tab lets you add shortcuts to hooks (in other words, record hooks to the context menu of a control). This means that at runtime, a user can execute these hooks by right-clicking the control and selecting the hook.

Figure 8-24. Context Menu Hooks tab

You can associate as many hooks as are available with the control. To associate a hook, simply select the hook in the Available list and click Add. To remove a hook, select it from the Selected list and click Remove.

Fields are not the only things that you can add to a tab. You can add several different controls for the sake of user assistance. Table 8-3 presents the controls available in ClearQuest, as listed in the ClearQuest Designer’s Guide.

Each control also has properties specific to it. You can find details about these controls in the ClearQuest Designer’s Guide.

Many times you will want to validate the input the user has given. You want to make sure that the presented value is within a specific range of valid values, is in the correct format, or matches a list of items in the database.

You can perform many kinds of validation on fields on a form. The thing to realize here is that the validation is not done on the actual user interface element but on the field itself. First, in the schema browser, select the Fields item (Figure 8-25).

Figure 8-25. Selecting the Fields item for validation

As you can see in Figure 8-26, to the right, you can select the Validation box for the individual field for which validation should be written.

Figure 8-26. Selecting Validation Box for Field

Next, you need to choose the language in which you would like to write the validation script. When you do this, an editor with the chosen language will appear.

The general rule on the script languages is to return a string when the field value change is not valid and to return an empty string if the input value is valid.

Here is an example written in BASIC:

Function resolution_Validation(fieldname)
   ' fieldname As String
   ' resolution_Validate As String
   Dim value
   Set value = GetFieldValue(fieldname)
   If Len(value.GetValue > 10 Then
      resolution_Validation = "Must be smaller than 10
        characters"
   End If
End Function

And here is one written in Perl:

sub resolution_Validation
{
  my ($pFieldName) = @_;
  my $theRetVal;
  my $theValue = $entity->GetFieldValue($pFieldName)
    ->GetValue();
  if(length($theValue) > 10)
  {

     $theRetVal = "Must be smaller than 10 characters";
  }
  return $theRetVal;
}

[A.8.5] Action hooks are used to initiate actions that occur for transitions, and also for other general actions. There are several areas where hooks can be called as a result of certain actions being called. Table 8-4, culled from the ClearQuest Designer’s Guide, presents a list of hooks for specific actions.

[S.8.12–S.8.16] Field hooks are used to work with fields such as validation, value changes, and pretty much anything else that has to do with fields. Table 8-5, also based on information in the ClearQuest Designer’s Guide, shows just when and how to use these hooks.