Issue Manager manages an issue through its entire lifecycle—from the time it is reported until the time it is closed—through an action-driven workflow mechanism. Action-driven workflow means that an issue is driven from one state (i.e., condition) to another by user actions until the issue reaches a terminal, or ending state.
How states and actions work together
Here’s an example of how an action taken on an issue in a given state moves an issue through its lifecycle. In the default workflow, a just-entered software bug reported by a technical support person is considered to be in an Unreviewed state, a condition that means that no one has confirmed that the “issue” is truly a bug. Assessing the situation, a QA engineer confirms that the issue is a bug and is ready to send it on to a developer to be fixed. In this example, think of the initial state as Unreviewed, the action to be taken as Confirm, and the next state as Dev-Ready (short for Development-Ready). This abbreviated workflow diagram illustrates these states and action.
If, on the other hand, an identical issue has already been entered into Issue Manager, then the action to be taken upon this unreviewed issue is Mark as Duplicate and the next state will probably be Closed. Therefore a different action upon this unreviewed issue sends the issue to a different state, in this case, Closed. The following diagram illustrates these examples.
A workflow must have at least one terminal state, which is the last state in the workflow. In the preceding diagram, Closed is the terminal state.
Some actions don’t affect issue state
Occasionally, issues retain their current state even after an action has been taken on them. This is true, for example, for Add Comment, which allows a user to add a comment to the description of an existing issue. In the following diagram, a developer adds a comment to an issue in the Dev-Ready state, but takes no action that moves the issue toward the Closed state. Therefore the issue remains in Dev-Ready.
Issue Manager has two predefined actions for each state in each workflow:
• Reassign, which allows users to route an issue to another inbox
• Edit, which allows users to modify fields on the Issue Details page
These actions do not change an issue’s current state, because they do not move the issue through the workflow. For example, if Fred leaves on vacation and reassigns his unreviewed bugs to Diane’s inbox. The bugs remain unreviewed until David takes an action that changes their state.
A workflow defines a valid set of actions that can be performed on a state. These actions can be viewed on the Workflows page. The available actions vary based on the Issue Type and Current State selected from the drop-down list boxes.
Actions are available on the Issue Details page in the form of buttons. The available buttons (i.e., actions) vary based on an issue’s type and current state.
In this chapter, you will learn how to define the button labels for each state that appear on the Issue Details page.
State information appears throughout Issue Manager. For example, each group and user account is assigned three initial issue states, one for each issue type—bug, enhancement, and documentation issue.
Initial issue state affects issue lifecycle
The initial state of an issue depends on how knowledgeable the user reporting the issue is with respect to this type of the issue. For example, when a member of the Technical Support group reports a documentation issue, it is assumed to be correctly assessed and ready for fixing, and is assigned an initial state of Open-Doc. However, when the same person submits a software bug, it is not necessarily assumed to be accurate, so its first state in the workflow is Unreviewed. Different groups can have different initial states for the same type of issue. For more information on initial issue states, see “Initial Issue State”.
When a user saves an issue, Issue Manager automatically assigns the issue an initial state based on the initial issue state assigned to the user. When a technical writer logs a documentation issue the value of the State field on the Issue Details page is Open-Doc. The State field is an automatic field, meaning that Issue Manager, not the user, fills it in based on the workflow and other information.
Each non-terminal state in a workflow has exactly one owner. The owner is the role in a organization that is responsible for acting on an issue in a given state. Consider an unreviewed bug: the user who confirms or denies an unreviewed software issue is most likely to be someone who performs the QA role. Therefore, the state owner of an unreviewed bug is the QA role.
A terminal state in a workflow does not have an owner because an issue in this state does not need someone to be responsible for taking an action on it.
In Issue Manager you choose one of four possible owners for a non-terminal state:
• QA
• Development
• Documentation
• Enhancements
Note that a state owner is not a specific QA engineer or a specific inbox; nor is it related to a specific product, component, release, or platform. A state owner is a general designation of functional responsibility with respect to a state.
Why does a state need an owner? The owner is an important property of a state because the state owner and the routing rules together determine the specific inbox that will receive the issue (routing rules are described in “Setting Up Routing Rules”). Here is an example of how Issue Manager uses routing rules, states, and state owners to move an issue to a specific inbox.
Say that you decide that the owner of the Unreviewed state of all software bugs, regardless of specific product, component, and so on, should be the QA role. Individuals who fulfill this role will confirm that a reported issue is actually a bug. So, on the State Properties dialog for the Unreviewed state, you select the QA Owns This State radio button. To access this State Properties dialog, go to Configuration/Workflows; then click the Edit State button.
Now consider routing rules for specific products. When you set up routing rules (Configuration/Routing Rules), you specify four specific inboxes for each combination of product, component, release, and platform. Each of the four state owner radio buttons corresponds to one of the four inboxes on the Routing Rules page: QA, Development, Enhancement, and Documentation.
Example: A routing rule states that when a bug pertains to the Email component in any release of Product C on any platform, then route the bug to one of these inboxes: Mike - QA, Sonja - Dev, Dan - Dev (Product C), or Judy - Doc.
One of the four inboxes is selected based on two factors: the current state of the issue and the owner of that state. Assuming that the current state of the bug is Unreviewed and that you specified that the QA role owns unreviewed issues, then the issue will be automatically routed to Mike’s inbox, Mike - QA.
When Mike acts on the issue, he will, in effect, move it along its lifecycle to another state, which has another owner. Issue Manager will again determine the appropriate inbox based on the issue’s current state, the owner of the state, and the applicable routing rule for the specific product, component, release, and platform.
In this chapter you will learn how to define state owners for each state in your workflow.
Issue Manager supports reason codes, which are optional, customizable keywords that describe why an issue has changed its state when a given action is taken.
Reason codes are informative. As presented in previous examples, a number of actions can cause an issue to move to the same state. For example, an issue can be closed for a variety of reasons—it’s not reproducible, it’s a duplicate, it’s not a bug. Without the extra information supplied by the reason code, users will have an incomplete picture of an issue’s lifecycle.
Reason codes can also help you minimize the number of states in your workflow. For example, instead of defining several terminal states—Not a Bug, Not Reproducible, Duplicate—it is sufficient to have one terminal state called Closed with a variety of reason codes that indicate why an action closed an issue with, for example, Closed/Not a Bug.
The user sees reason codes on the Issue Details page and the action dialogs. For example, Judy, a technical writer, receives a documentation issue in her inbox. Reading the description, she recalls that the issue has already been reported. She marks the issue as a duplicate. When the Mark as Duplicate action dialog opens, she can see that Issue Manager has moved the issue from Open-Doc to Closed/Duplicate. Closed is the new state; Duplicate is the reason code.
The next time the Issue dialog is opened for this issue, Issue Manager will fill in the state and reason code.
Assigning, clearing, or retaining a reason code
When certain actions are taken, Issue Manager assigns a reason code to the action and passes it on to the new state. Subsequent actions might clear the reason code or simply retain the reason code. In general, once you set a reason code, it travels with the issue until it reaches the terminal state in the workflow.
Consider the case of a developer who fixes a bug and then takes the Fixed action to claim that the bug has been fixed. This action moves the bug from Dev-Ready to QA-Ready, and sets the reason code to Fixed. The QA engineer who is verifying the developer’s claim accepts the bug fix by taking the Verified action. This action retains the Fixed reason code and moves the bug along to the Closed state. The following diagram shows this workflow.
However, you might want to clear the reason code, for example, when an issue returns to an earlier state in the workflow, instead of progressing toward a terminal state. Say that a QA engineer disputes a developer’s claim and takes the Reject action, which sends the issue back to the Dev-Ready state. The Fixed reason code no longer makes sense, so you might want to clear the reason code for the Reject action. The following partial workflow illustrates this point.
Whether reason codes are assigned, cleared, or retained is determined by the setting in the New Action for State dialog, which is described in “Reason code”. To view the New Action for State dialog, go to Configuration/Workflows and click the Add Action button.
Which states need reason codes
In general, you should assign a reason code to any state that a developer acts on. You should not assign a reason code to a terminal state, because reason codes should be assigned in earlier states.
Later in this chapter you will learn how to set up reason codes when you define the workflow states and actions that can be taken on a given state.