Example: Implementing a Workflow

This section describes the process of using workflow to create and implement a workflow for the fictional Rapid Velo company. The example scenario walks you through the design and development stages of the workflow implementation process to illustrate how you can use AccuRev to build a workflow of your own. Some techniques are described in detail, but for complete details on the procedures mentioned in this section, refer to the preceding sections in this guide.

Overview

The Rapid Velo company currently uses the AccuWork issue tracking system and AccuRev to manage their SCM processes. They want to implement a workflow for its Phoenix product line to integrate their issue tracking and SCM systems, automate issue processing, and enforce their SCM policies.

The workflow created in this example scenario is basic, but it demonstrates all of the workflow features you can use to model, implement, and enforce your organization’s SCM policies, no matter how complex.

Step 1: Design the Workflow

The Rapid Velo company’s AccuRev administrator meets with her organization’s development and release engineering managers and the Phoenix product owner (PO) to discuss and diagram the workflow they want to implement. They identify the workflow stages summarized in the following table:

Workflow Stage	Description
New	Rapid Velo customer support, QA, and the PO create issues in AccuWork to describe a defect in or a requested enhancement to the Phoenix product line. They must specify an issue type before the issue can be saved.
Scheduled	The product owner reviews the issue. If it is considered important, it is scheduled for an upcoming iteration; otherwise it is closed.
WIP	Work on a scheduled issue begins only after it is assigned to (or chosen by) an software engineer. Once work begins, the issue’s status is considered to be Work in Progress (or WIP).
Done	When development is finished, the engineer changes the issue’s status to Done, where it awaits QA.
Closed	When an issue passes QA, it is closed; otherwise, it is returned to the WIP stage until an engineer picks it up again.

Not coincidentally, each of these workflow stages has already been defined in the AccuWork schema associated with the phoenix depot and is currently being used for issue tracking in AccuWork. This is a good start, but the workflow as described by Rapid Velo’s engineering staff has some areas that they want to enhance before exposing workflow to the AccuRev end users:

There is no representation for the process of managing issues in QA:
- Issues that pass QA can be successfully closed.
- Issues that fail QA must be returned to the Scheduled state.
The workflow does not provide a mechanism for an engineer to request additional details on an issue before starting work on that issue. When an issue is returned to the product owner for more information, that issue’s owner should automatically be changed to the product owner.

The pass/fail QA processes can be modeled using workflow transitions—the AccuRev Stage Generator will automatically create these transitions, as you will see in Step 3: Create Workflow Stages and Transitions. The process that allows the engineer to request more information, however, requires changes to the AccuWork schema. How the AccuRev administrator addresses this requirement is described in the following section, Step 2: Modify the AccuWork Schema.

Step 2: Modify the AccuWork Schema

After further discussion, the product owner, development and release managers, and the AccuRev administrator agree that a Review stage is needed for the workflow. The first step in creating such a workflow stage is to add a Review value to the status field in the AccuWork schema, as described here:

In the AccuRev Java GUI, navigate to the Schema tab in the Schema Editor.
Select status from the Schema Fields table.

Currently defined values appear in the Field Values list adjacent to the Schema Fields table.

Tip: The order of values in the Field Values list is the order in which these values will appear in the Status field in the AccuRev Issue Edit form.
Type Review in the entry field and click the Add button.
Use the Down button to move the Review value to a more appropriate place in the Field Values list (after WIP, for example).
Next, add a new field of type Stream. Consider giving the stream field a label such as Project or Workflow Project to help convey the conceptual connection between a depot stream and a workflow project.
Click the Save button to save your changes to the AccuWork schema.

Now that the status field has values for all of the stages that the Rapid Velo engineering staff wants to represent in its workflow, they are ready to create workflow stages and transitions.

Step 3: Create Workflow Stages and Transitions

After the AccuRev administrator has modified the AccuWork schema as described in Step 2: Modify the AccuWork Schema, she starts the AccuRev Web UI. From there, she opens the phoenix depot, clicks the Admin menu, and chooses Create Workflow:

In the Create Workflow dialog box, she selects the phoenix depot and enters the name defect for the workflow:
When she clicks Ok, the Workflow Editor appears, along with the Set Workflow Conditions dialog box. She uses this dialog box to specify that issues must have a type of defect in order to be subject to this workflow:
When she clicks Ok to save the condition settings, the workflow is activated, but the workflow stages and transitions still need to be defined.
She clicks the Stage Generator button () and uses it to generate workflow stages based on the values for the Status field in the AccuWork schema:

After choosing Status from the Schema fields with type of Choose field, she selects all of the values and then clicks the Add Stages button. AccuRev automatically creates workflow stages and default transitions for every value in the AccuWork schema’s status field:

When the AccuRev administrator examines the Scheduled workflow stage (she selects the stage in the workflow diagram and clicks the Edit button () in the Workflow Editor toolbar), she finds that its logic—its conditions and entry actions—is fully defined, with a condition that describes when an issue can be in that stage, an entry action that describes the changes AccuRev makes to the issue record when it enters that stage by transition, and a validation action that sets the Status field to read-only, so that AccuRev users cannot manually remove an issue from the workflow:

Each of the stages created by the Stage Generator is created with the same conditions, entry actions, and validation actions. All that is left to do now is to configure the workflow by linking one workflow stage to another.

Step 4: Link Workflow Stages

To link workflow stages, the AccuRev Administrator selects a source stage, clicks the Link Stages button (), and then chooses the destination stage. In this example, she has chosen the New stage as the source and the Scheduled stage as the destination:

Once the destination stage is selected, AccuRev displays the transitions associated with that stage. She selects to Scheduled and clicks Ok:

AccuRev updates the workflow diagram with the newly created link between the New and Scheduled stages.

The AccuRev administrator links the remaining workflow stages, this time using the stage context menu Add Link, which displays a list of the transitions to other workflow stages.

Step 5: Refine the Workflow

Now that all the workflow stages have been linked, some finishing touches can be applied to the defects workflow.

Change the Default Layout

The first thing the AccuRev admin does is to use the workflow diagram’s drag-and-drop feature to rearrange the workflow to suit her purposes. The workflow for the phoenix depot now looks something like this:

The workflow diagram supports group-select for layout and other operations (like delete, for example).

Remove Unnecessary Transitions

As described elsewhere, the Stage Generator creates a default transition for every stage; most of these transitions are used to link one stage to another, but a transition on the first stage in a workflow is generally not needed. The AccuRev administrator therefore deletes the to New transition on the New workflow stage. To do this, she simply selected the transition on the workflow diagram and clicked the Delete button (); she could have also selected the Delete choice on the transition context menu.

Rename Transitions

The engineering and release managers mention that they would like to change the default transition names to make the workflow process nomenclature more intuitive for AccuRev users. For example, they would like a QA engineer to click a button that says passed QA instead of to Closed when an issue passes QA testing and can be closed.

To rename the to Closed transition, the AccuRev administrator:

Right-clicks the to Closed transition and chooses Edit from the context menu.

The Edit dialog box for that transition appears.
In the Transition Name field she types passed QA and then clicks Ok to save the change.

She then renames the remaining transitions, as summarized in the following table:

Default Transition Name	Default Transition Name
to Scheduled	schedule
to WIP	assign
to Done	complete
to Review	need more info

When she has finished, she clicks the Save button () to save her changes to the workflow, which now looks like this:

Specify a Transition Action

When an engineer returns an issue to the product owner for more information, the Assigned To field should change from the engineer’s user name to that of the product owner. To accomplish this, the AccuRev administrator creates a setValue action for the need more info transition:

To specify a transition action, the AccuRev administrator:

Right-clicks the need more info transition and chooses Edit from the context menu.

The Edit dialog box for that transition appears.
She clicks the Edit Logic button to display the Validation Actions tab, and sets the setValue action to hrondo, the product owner’s user name.

Now, when the user clicks the need more info transition button for an issue record, the value of the
Assigned To field is automatically changed to hrondo.

Create a Transition from Scratch

While reviewing the current workflow, the team notices that there is no way for QA to indicate that an issue has failed testing and to return the issue to engineering for more work—that is, to move the issue from Done back to WIP. To handle this case, the AccuRev administrator creates a new transition, failed QA, and uses it to link the Done and WIP stages:

She selects the Done stage from the workflow diagram and clicks the Link Stages button ().

The Link Stages dialog box appears. Done is already specified as the source stage, and she selects WIP for the Destination Stage field.
The assign transition is already being used to move issues from Scheduled to WIP, so the AccuRev administrator clicks the Create New Transition button ().
In the Transition Name field of the Create New Transition dialog box, she types failed QA and then clicks Ok to create the new transition.
When the Create New Transition dialog box closes, the AccuRev Administrator clicks Ok on the Link Stages dialog box.

The new failed QA transition appears on the workflow diagram:

After a final review, the team agrees that the workflow is now ready to be integrated with the phoenix depot.

Step 6: Review Issue Processing Automation

Before using the defects workflow to enforce Rapid Velo’s SCM policies, the AccuRev administrator wants to quickly review the issue processing features that are already available to her AccuRev users. By simply creating and activating the defects workflow, Rapid Velo’s AccuRev users can:

Quickly determine which workflow stage an issue is in
Display a read-only view of the workflow to gain a sense of where the issue sits relative to the overall workflow
Automatically move the issue to the next stage of the workflow by clicking a transition button

All of these features are accessible on the Issue Edit form, shown here:

Here, for example, because issue 2113 is type defect, its processing is automated and enforced by the defects workflow (whose condition, you might recall, was specified as Type = defect). In this example, clicking the assign transition button moves the issue to the WIP stage, changing the value of the Status field from Scheduled to WIP in the process. Any logic defined for the WIP stage—an entry action or a validation action, for example—is executed at this time.

Tip: These workflow tools are also available in the Issue Edit form in the AccuRev Java GUI once the workflow has been created and activated.

Using a Workflow as a Query Filter

AccuRev users can now also use the workflow to filter query results, and to quickly view and manage the issues in any workflow stage. As shown here, the defects workflow has been used to filter results from the My Stuff query to display only those issues that are defects (and not, say, enhancements).

And by clicking a stage in the workflow diagram, users can further filter query results to see which issues returned by the query are in that stage. Multiple stages can be selected, and buttons for applicable transitions are displayed in the query results pane.

Step 7: Use Workflow to Enforce SCM Policies

Satisfied that the defects workflow provides the required support for Rapid Velo’s issue processing automation and rules enforcement, the AccuRev administrator is ready to use that workflow to enforce Rapid Velo’s SCM development and release policies. In particular, Rapid Velo’s engineering organization wants to ensure that:

Only defects that are marked Closed can be promoted into the phoenix_Client build stream
Any type of issue can be in the phoenix_Client_QA stream, but if it is a defect, it must be marked Done

Restrict Entry Based Exclusively on Workflow Stage

The AccuRev administrator starts by setting workflow rules for the phoenix_Client stream:

She right-clicks the phoenix_Client stream and chooses Workflow Rules from the context menu.

The Workflow Rules for Stream dialog box appears.

Since she wants to restrict entry to defects, she selects the defects workflow from the Choose Workflow field and clicks the Add button.

The Workflow Rules for Stream dialog box expands, displaying a new tab for the defects workflow.
To allow only defects in the phoenix_Client stream, she selects the Allow issues from specified workflows only check box.
Next, she changes the default stream entry rule to Restrict entry to issues in specified workflow stages, and then specifies Closed for the workflow stage:

(Because Closed is the last stage in the workflow, it is not currently defined with a transition to another workflow stage.)

When the AccuRev administrator is done, the phoenix_Client stream in the StreamBrowser displays an icon that indicates that a workflow rule has been specified for this stream.

Tip: The workflow rules icon also appears in the StreamBrowser in the AccuRev Java GUI.

Enforce Rules for Specific Issue Types Only

The rules for the phoenix_Client_QA stream are slightly more relaxed: issues of any type—defects, enhancements, and so on—can be in the stream, but if the issue is a defect, it must be marked Done. The procedure for setting this rule on the phoenix_Client_QA stream is the same as that for the phoenix_Client stream with one simple difference: when specifying the rule, the AccuRev administrator leaves the Allow issues from specified workflows only check box in its default state (not selected).

Note that the transitions specified as part of the stream entry or exit rule are performed on the issue when it is promoted into the stream. In this case, however, the AccuRev administrator did not select a transition for issues promoted into the phoenix_Client_QA stream because there is no way to determine whether or not the issue will pass QA.

Summing Up

Once the Rapid Velo team identified the stages in the software development and release management processes they wanted to model, creating and activating a fully functional workflow took just a few minutes. The AccuRev administrator used the Stage Generator to create all workflow stages based on values from the status field in the AccuWork schema; refining the workflow as new requirements were identified—adding a new transition and changing the value of the Assigned To field, for example—was quick and easy. Integrating the finished workflow with the depot to enforce the company’s SCM policies was also accomplished in a few simple steps.

Now that the Rapid Velo team has a workflow in place:

Issue processing is automated—important fields are write-protected, issues can move only through well-defined paths in the workflow.
AccuRev users can use workflow to help manage their issues—users can tell at a glance which workflow stage an issue is in and use transition buttons to move the issue through the workflow; the workflow can be used as a query filter; users can quickly see—and work on—issues in a specific workflow stage by clicking on a diagram.
SCM development and release policies are enforced—with just a few clicks, entry restrictions were placed on issues being promoted into the phoenix_Client and phoenix_Client_QA streams.

All of this was accomplished in just a few minutes using the intuitive Workflow Editor and familiar tools like the StreamBrowser and Schema Editor.