Actions are the mechanism for submitting new records to
the database, moving records from one state to another, and modifying
or deleting records.
When users click the Actions button on a
form or opening the Actions menu on the tool
bar, a list of valid actions is displayed, and the default action
is highlighted in bold text. You define the default action by using
the Default Action tab in the State Properties
window. See Default actions. You can also
call a default action from a hook.
Only the actions that are available at that moment, based on the
user's permissions and the state of the record, are displayed. To
avoid potential performance problems, access control hooks do not
run when calculating valid actions.
You can define an action to perform these tasks:
- Create a new record and add it to the database.
- Modify information in the record. (The behaviors
associated with each field can also limit access to particular fields
of the record.)
- Move a record from one state to another.
- Mark one record as a duplicate of another.
- Execute a hook. Action hooks can handle access control,
initialization, validation, and notification. See Customizing actions by adding hooks.
- Delete a record from the database.
You can control which users have access to which
actions and when actions can be performed.
A number of predefined action types for commonly
used actions are supported, for example, the Submit action and the
Change State action. See Supported action types.
In the Designer, each record type has an Actions
grid that defines the actions available for records of that type.
You can use the Actions grid to add, modify, and delete actions and
to create state transitions.
Supported action types
Rational® ClearQuest® software
supports the following types of actions:
- Action type
- Description
- Base
- A Base action is a secondary action that runs as a result of every
other action. You can write one action hook for a Base action, but
use that hook with multiple actions. Each time an action fires, the
Base action verifies that the hook criterion is met; if it is, the
base action completes its process. For example, you can add a Notification
action hook to a Base action to have the Base action send e-mail notification
when a Close action (a Change_state action type that moves the record
to the Closed state) occurs. Base actions do not appear in the list
of actions in the Rational ClearQuest client.
Setting
access control on Base actions affects all actions in the schema.
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.
- Change_state
- Change_state actions are available only for state-based record
types. A Change_state action moves a record from a source state to
a destination state. A Change_state action can reference many source
states, but only one destination state. Change_state actions appear
in the list of actions in the Rational ClearQuest client
only if the current record is one of the source states.
- Delete
- The Delete action permits users delete a record from the database.
Delete actions appear in the list of actions in the Rational ClearQuest client.
- Duplicate
- The Duplicate action is available only for state-based record
types. This action links the record to another record that contains
similar information. Duplicate actions appear in the list of actions
in the Rational ClearQuest client
only if the current record is one of the source states.
- Import
- The Import action imports records from another source. The contents
of imported records are validated as part of this action, but field-level
validation is not performed. In addition, when a set of state-based
records is imported, these records are assigned to a state specified
in the data files without any verification of whether they could have
transitioned to that state. Import actions do not appear in the list
of actions in the Rational ClearQuest client.
- Modify
- The Modify action permits users modify field values in a record
without moving the record between states. Modify actions appear in
the list of actions in the Rational ClearQuest client.
- Record_script_alias
- Record_script_alias associates an action with a record script.
Record_script_alias actions appear in the list of actions in the Rational ClearQuest client.
- Submit
- The Submit action enters a new record into the Rational ClearQuest user
database. For state-based records, this action assigns a destination
state, but does not require a source. Each record type can have only
one action whose type is Submit.
- Unduplicate
- The Unduplicate action is available for state-based record types.
This action removes the link between duplicate records.
Creating a state transition
The Rational ClearQuest schema
developer defines the rules for how users move records between states.
State transitions are implemented by actions. To create a state transition,
you define an action of the type CHANGE_STATE and then select the
source states and a destination state for that action.
Customizing actions by adding hooks
You can add action hooks that
implement tasks at key points in the life cycle of an active record.
For example, by default, all users have access to every action. You
can limit the access to an action by using an access-control hook.
Several action hooks are supported: Access Control,
Initialization, Validation, Commit, and Notification.
For
a description of action hooks and information about how they work
with field hooks, see Using hooks to customize your workflow.
To learn how to create an access control action hook, see Action access control hook example.
Also see Scripting languages and Action access control.
Default actions
You can
define default actions for states. A default action for a state appears
in bold on the Actions menu in theRational ClearQuest client.
Default
actions are useful for guiding users through the state model. They
are required for certain schemas and packages, such as the UCM schema
and package. If you use the UCM schema or package, the default actions
of your states must provide a valid path through the state type model.
For more information, see Adding an IBM Rational UCM
integration. Also, default actions can be called from hook
code.
Before you can define the default action
for a state, you must first create a state transition.
Deleting an action
Deleting
an action might require other changes to a schema. For example, if
you delete a CHANGE_STATE action, you might need to modify the State
Transition Matrix to compensate for the lost action. If you have referred
to a deleted action in a script, you must modify your script to delete
any references to the action.