Using hooks in Rational ClearQuest Web

Rational® ClearQuest® Web software supports a subset of the full hook functionality, which a schema developer can set up.

Hooks created in the Rational ClearQuest schema run on the computers that run the Rational ClearQuest server. Keep in mind the following points when using hooks with Rational ClearQuest Web:
  • You must enable dependent fields for the Rational ClearQuest Web client.
  • You cannot use message boxes.
  • Context-menu hooks are not supported in the Rational ClearQuest Web application.
  • You can use hooks to detect a Web session.
The following types of hooks are supported:
  • Field hooks
    • Value Changed
      Value Changed hooks run when the value of the given field changes in the following form control types with special considerations for setting Web-dependent fields:
      • Drop-down list box
      • Drop-down combo box
      • Combo ox
      For more information, see Special considerations for Value Changed field hooks.
    • Choice List

      Choice List hooks set the choices associated with a field. When a choice list for field the is determined by another field, that other field must list the target field as its Web-dependent field. The control types that can be displayed for Choice List Hook fields are combo box, drop-down combo box, and drop-down list box.

    • Default Value

      Run when a submit form is displayed (and not when a record is submitted by clicking Save).

    • Permission

      Run only when the form is first displayed in edit mode.

    • Validation

      Run only when the form is saved (not when the user changes a field value).

  • Action hooks
    • Access Control
    • Initialization
    • Validation
    • Commit
    • Notification
  • Record scripts
    Record scripts can be associated with the following states and form controls:
    • Record states and appear in a drop-down List on the Utilities button in a record in a specific state.
    • Pre- and post-action hooks on a push button form control. On the form, the action hook must be set to Enabled for Web. The script can run before or after the operation that the push button invokes.
    • Button form controls as the Click Hook specified on the Extended tab of the Properties for the control. On the form, the Click Hook must be set to Enabled for Web.

    Context Menu hooks are not supported on any form control.

  • Global scripts

Special considerations for Value Changed field hooks

When using Value Changed hooks, you must ensure that a Value Changed hook runs at the appropriate time and that the results are visible to users of the Rational ClearQuest Web client.

Value Changed field hooks run when the browser communicates with the Rational ClearQuest Server. Sometimes this communication occurs immediately after a user changes the value in a form field (for example, selecting an item in a drop-down list). In other situations, the communication occurs only after the user saves the new value.

A Value Changed hook runs immediately when both of the following conditions are true:
  • The hook is set on a field whose form control is one of the following types:
    • Drop-down list box
    • Drop-down combo box
    • Combo box
  • The form control properties have at least one Web-dependent field set for the control.

A Value Changed hook runs later when a user changes the value of other types of controls, such as a ListView control or an Attachments control, but not until the user clicks the Save button on the form. It also runs when a drop-down list box, drop-down combo box, or combo box has no Web-dependent fields. Moving between tabs on a form in the browser does not cause the browser to communicate with the Rational ClearQuest Server.

After ensuring that a Value Changed hook is executed at the appropriate time, you must ensure that when a Value Changed hook runs, changes made to the value or choice list of other (target) fields in the record are visible to the user after the hook execution has completed. When such changes are made, they are visible only to the user in the browser if the target field is declared as a Web-dependent field in the Properties of the form control for the field with the Value Changed hook

If a form control is a drop-down list box, drop-down combo box, or combo box whose field includes a Value Changed hook that is run in Rational ClearQuest Web immediately and is written for one of the following purposes, then special considerations apply:

  • Changing the value of, or invalidating the choice list of, target fields

    When a Valued Changed hook changes the value of or invalidates the choice list of one or more target fields, the browser refreshes the display for the new values of the target fields if the those fields are set as Web-dependent fields of the form control. Such fields are updated when a user changes the value of the form control.

    Although you can set a ListView control as a Web-dependent field, this setting does not work for ListView controls with Rational ClearQuest Web.

  • Changing the mandatory target fields

    When a source hook changes only whether one or more target fields is mandatory, you do not need to set all the target fields as Web-dependent fields of the form control. The browser refreshes the display of details of all mandatory fields on the form, not only the fields that are Web dependent.

    The form control must have at least one Web-dependent field to ensure that the Value Changed hook runs immediately. Although you can select any field as the Web-dependent field, for best performance, select a field that does not have a long choice list.

Parent topic: Customizing Rational ClearQuest Web