After you define the states in a workflow, you must define the actions that are associated with each state. For example, for the Dev-Ready state in the default bug workflow, a developer can take the Fixed action, the Cannot Fix action, and so on.
Each action has a set of properties associated with it. This section describes these properties. You can use the information in this section to help you customize actions in “Customizing Actions, Reason Codes, & Action Dialogs”.
General properties of an action
The properties of an action are varied and cover the following areas:
• Button label that appears on the Issue Details page.
• Description of the action that appears on the History tab.
• New state that results from this action
• Reason code
• Appearance and usage of the action dialog
• Groups permitted to take this action
• Sort order of this action
Action properties are set on the Edit Action of State dialog (Configuration/Workflows).
Cannot be edited. Displays the name of the current state for which you are defining or modifying an action (e.g., Edit Action for State - Unreviewed).
This is the name that appears on the button that executes this action, located on the Issue Details page, up to 30 characters long (e.g., Confirm as a Bug).
Concise statement of the action that was taken, up to 20 characters long. It is recommended that you use uppercase characters (e.g., VERIFIED).
This code appears in the Actions column on the Issue Details page’s History tab.
Tooltip
Optional text that will appear as a tooltip when a user passes their cursor over this action button.
Description
Optional description of this action.
Name of the next state in the workflow when this action is taken on an issue. For example, in the default workflow when an Unreviewed issue is confirmed as a bug, Issue Manager moves the issue to the next state, Dev-Ready. This sequence is illustrated in the following workflow diagram:
Optional keyword that describes why an issue has changed from the current state to the new state when this action is taken. For background information, see “Reason codes”.
Select the appropriate radio button:
• No Change
• Clear
• Set To (enter a keyword)
No Change
No Change indicates that the keyword is retained when the issue moves to the new state. It will appear in the Reason Code field of the Issue Details page. For example, the following workflow shows that when a developer claims to have fixed a bug, the bug moves to the QA-Ready state with a reason code of Fixed. If a QA engineer verifies the claim, then the bug moves to the Closed state while retaining the Fixed reason code. Any user browsing issues can easily see the reason the bug has been closed by looking at the reason code.
Clear indicates that the reason code for the current state will be removed when the issue moves to the new state. Clear is a reasonable choice when an issue returns to a previous state in the workflow (e.g., when a developer claims to have fixed a bug, the bug moves to the QA-Ready state with a reason code of Fixed).
If, however, the “fix” is rejected, the issue is sent back to Development (Dev-Ready) and the Fixed reason code is removed, since this claim is disputed.
When you choose Clear, the Workflows displays ‘CLEAR’ in the Reason Code field; however, the user sees an empty Reason Code field on the Issue Details page.
Set To indicates that you can associate a reason code with this action. Enter a keyword of up to 20 characters. All capital letters is recommended.
Use Set To to specify a reason code when an action moves an issue to a new state that requires a reason code. In general, you should assign reason codes to all actions that developers take.
For example, in the default workflow the Fixed action on the Dev-Ready state sends the issue to the QA-Ready state with a reason code of Fixed. What this means in terms of human behavior is that when a developer claims that a bug has been fixed, he hands it off to a QA engineer, who can now easily scan the Issue Details page to see why the bug is in his or her inbox (the bug could also be there because the developer can’t fix it or the software is working as designed).
If you don’t use reason codes
Reason codes are optional keywords that can help to minimize the number of states in your workflow. For example, rather than defining several closing states—Not a Bug, Not Reproducible, Not Repro, and Duplicate—one terminal state is sufficient where reason codes help explain why the issue is in the Closed state.
If you decide not to use reason codes, you may need to have several terminal states. A state can be made a terminal state by selecting the radio button called No one (Terminal State), which appears as a choice in the State Owner field of the State Properties dialog. See “State properties” for details.
The Standard Action Fields tab on the New Action for State dialog defines the properties relating to the use and appearance of the action dialog, specifically:
• The Action Notes field on action dialogs (described in “Action Notes”)
• Release Information on action dialogs (described in “Release Information”)
• Related Issue Number of a related issue on action dialogs (described in “Related Issue Number”)
The Action Notes field on a action dialog has one of three possible values:
Not Used
If you choose Not Used (the default), the action dialog will not display the Action Notes field when the user takes this action.
Optional
If you choose Optional, the action dialog will display the Action Notes field. Users have the option of entering extra information about the action they are taking.
Required
If you choose Required, the action dialog displays a required Action Notes field. Users must enter extra information about the action in this field.
The Release Information group allows you to have a list box appear on the action dialog from which users can select the release in which this action is taken. The release selected by the user also appears in one of the automatic fields on the Issue Details page. This information is particularly useful for certain kinds of actions (e.g., those related to confirming, fixing, and verifying issues). It is not useful for actions that do not change the current state.
The Release Information field has one of four values: Not Used, Optional, Required, and Cleared.
Not Used
If you choose Not Used (the default), the action dialog will not display the list box. The action dialog for the Add Comment action does not have a list box for release information because release information is not necessary for the Add Comment action.
Optional or Required
If you choose Optional or Required, the action dialog will display an optional or required list box from which the user selects a release. See the action dialog below. The last automatic field on the Issue Details page displays the release in which the action was taken.
You need to specify the list box Label, to make it appropriate for the action. The label can be up to 20 characters long, including a trailing colon. The default field label is Confirmed In: for confirming actions; Fixed In: for fixing actions; and Verified In: for verifying actions. The label appears on both the action dialog and on the Issue Details page.
The list box’s values derive from the list of releases specified in the SilkCentral Administration module.
Cleared
If you choose Cleared, then the previous value in the last automatic field of the Issue Details page will be removed and the field label reverted to the default, Action Release. The Label field in the Release Information group box is grayed out.
Cleared is a good choice when an action causes an issue to return to a previous state in the workflow. Examples from the default workflow are the Reject and Reopen Bug actions.
For example, a developer takes a Fixed action and fills in a specific release number in the Fixed In field. This action sends the issue to the QA-Ready state. The QA engineer responsible for the issue rejects the developer’s claim that the bug has been fixed. The Reject action moves the issue from its current state, QA-Ready, back to a previous state in the workflow, Dev-Ready. The Reject action is illustrated in this diagram.
Since the Fixed action has been rejected, it makes no sense to retain the release specified in the Fixed In field. In this situation, choose the Cleared value for the Reject action.
Tip When an action’s reason code is cleared, as described in “Reason code”, consider choosing Cleared as the value for the Release Information field.
The release selected by the user on the action dialog will appear on the Issue Details page. For example, say that a user takes the Fixed action, selects 4.1:prod as the release from the Fixed In list box, and clicks OK. When the Issue Details page reappears, the Fixed In field displays the selected release.
If you choose Not Used, for example if the user doesn’t supply information in an optional list box on the action dialog, or if an action hasn’t been taken which uses the list box, then the Issue Details page displays an empty Action Release field.
The Related Issue Number field allows you to place a text field on the action dialog in which users can enter the number of a duplicate or related issue. This information is useful when users take the Mark as Duplicate action in the bug workflow or the Already Done action in the enhancement workflow.
The Related Issue Number field has one of three values: Not Used, Optional, or Required.
Not Used
If you choose Not Used, then the text field will not appear on the action dialog.
Optional or Required
If you choose Optional or Required, an optional or required text field appears on the action dialog. You need to specify the text field label. The label can be up to 20 characters long, including a trailing colon. The default field label in the bug workflow is Duplicate of #. The default field label in the enhancement workflow is See Also.
The issue number specified by the user on the action dialog will appear in the Notes field of the Issue Details page’s History tab. For example, say a user takes the Mark as Duplicate action on Issue #8, specifies Issue #6 as the duplicate, and clicks OK. When the Issue Details page reappears, the Notes field will display the phrase (Related to issue number n), where n is the value of the Duplicate of # field. If the Duplicate of # field is optional and the user does not fill it in, then the Notes field will display the contents of the Action Notes field.
User-Defined Action Fields Tab
The User-defined Action Fields tab of the New Action for State dialog allows you to add fields to the action dialog of a given action.
Eight field positions
These fields appear on the action dialog in addition to the standard action fields, described in “Standard Action Fields Tab”. Field 1 through Field 4 appear in the bottom left of the action dialog. Field 5 through Field 8 appear in the bottom right. For example, the Hours to Fix field might be selected from the list box to appear in the first field position (Field 1) on the action dialog for the Fixed action in the Dev-Ready state.
Read-only once referenced
Once a field has been referenced by an issue, it becomes read-only on the User-defined Action Fields tab. To see the information entered in the action dialog, you need to view the issue entry on the Issue Detail page’s History tab.
Sources
The fields that appear in the list boxes on the User-defined Action Fields tab are there for one of two reasons:
• You may define new fields, as described in the procedure below. These fields are always optional. The mode cannot be changed.
• You may select the fields displayed on the custom tabs of the Issue Details page. For example, the action dialog might contain the Hours to Fix field. You might want this information to appear as well on a custom tab. Fields already defined for the custom tabs automatically appear in the list boxes of the User-defined Action Fields tab.
How to define fields on an action dialog
You can define your own fields to appear on action dialogs.
Prerequisite
You need the Workflow customization security privilege to perform these tasks.
Procedure To define your own fields for an action dialog:
1 Go to Configuration/Custom Field Pool.
2 Click the Add Custom Field button to display the Edit Field Properties dialog.
3 Configure the field properties as explained in “GUI Customization Properties”.
4 The custom fields you create can then be selected from the list boxes on the User-defined Actions Field tab.
On the Permissions tab you can set security for individual actions, thus restricting actions to selected groups of users.
By default, Apply Security has a value of No (i.e., all groups have permission to take all actions). This setting appears on the Workflows page as (all groups). You set security by selecting the Yes radio button and then selecting one or more groups to have permission to take the action.
Consider this example of defining security for an action: When a developer opens an Issue Details page for a bug in the Dev-Ready state, the Cannot Fix action is available. However when a user who is not a developer opens the Issue Details page for the same bug, the action is hidden.
