Execution order of field and action hooks

Hooks that run when an action begins

Before committing changes to the database, or when a validation is requested from a HCL Compass Web client Web or RCP client, the HCL Compass Web client software validates the record by running hooks in the following order:

1. The Action Access Control hook checks user access and stops the processing of the action if the user is not allowed to initiate it. In this case, the remaining hooks do not run.

   You can modify the access control to actions, including actions that might be added to your schema by applying packages. However, any access control restrictions placed in base actions apply to all other actions. For nested actions, an access control hook is not run.

2. The Field Permission hook determines whether each field is mandatory, optional, or read-only.
3. The Action Initialization hook performs initialization tasks such as setting up field values before the action begins.
4. The Field Default Value hook sets the value for each field (for Submit actions only).
5. The Field Validation hook validates the contents of each field, except for an import action in which no validation occurs. Field validation hooks cannot validate nonexistent values, such as a mandatory field in which the value has not been set.
6. The Field Choice List hook runs for each field that uses the Recalculate Choice List option. If there are dependent fields and you selected Recalculate Choice List when you created the fields, the Field Validation hook is run and then the Field Choice List hook for each field is run, until all changed fields have been set and validated.

   If a Field Value Changed hook calls the SetFieldValue method of the Entity object, the VALUE_CHANGED hook for that field runs at the time of the SetFieldValue call.

Nested actions

Certain hooks do not run while a nested action is in progress, including the execution of access control hooks and all notification hooks. For more information, see Actions and access control and Hooks in nested actions in the Compass API Reference.

Hooks that run when a field value is set

When a user edits a record, the hooks run in the following order:

1. The Field Value Changed hook runs for each field that changes.

   If the Limit to list option is set and the user enters a value that is not allowed, the field is marked as not valid. The next hook runs only when the user enters a valid value.

   If a Field Value Changed hook calls the SetFieldValue method to change the value of another field, the Field Value Changed hook for the other field runs immediately.

2. The Field Validation hook runs for each field.
3. The Field Choice List hook runs for each field that uses the Recalculate Choice list option.

   If you use dependent fields with the Recalculate Choice list option, the Field Validation hook runs first and then the Field Choice List hook for each field runs, until all changed fields are set and validated.

Field hooks run only when the user starts the Submit action, unless the field is marked as having dependent fields. See Using hooks to detect a Web session.

Hooks that run when the record is validated

Before committing changes to the database, HCL Compass software validates the record by running hooks in the following order:

1. The Field Validation hook runs for each field in the record.
2. The Action Validation hook runs for the action that was performed.

Hooks that run when the record is committed

The Commit hook runs after the database is updated with changes to the current record, but before the update transaction has been committed to the database. You cannot use a Commit hook to modify the current record (for example, you cannot make changes to a field from a Commit hook).

Work in a Commit hook is completed while locks exist in the database, and those locks might prevent other users from running queries, creating new records, or modifying existing records. For performance reasons, it is best to minimize the work performed in a Commit hook.

Use a Commit hook only for actions against other records that you want to be part of the same database transaction as the main action (for example, resolving a duplicate defect when the parent defect is resolved). You must ensure that you are placing the appropriate calls in the correct context. For example, you do not call Revert from a Commit hook, nor do you call Commit from any action other than a Commit hook.

After a record is validated, it is committed to the database by hooks that run in the following order:

1. The Action Commit hook runs.
2. The transaction is committed to the database.
3. The Action Notification hook runs. For example, an e-mail notification might be sent to various users.

For more information, see Editing an existing record in the Compass API Reference.