AccuRev 4.7 Beta-1 with AccuWorkflow
Usage Notes
This note describes the configuration and use of AccuWorkflow, using the AccuRev 4.7 graphical user interface. It contains the following sections:
Defining an Issue Database's AccuWorkflow Configuration
Validation Actions for a Workflow
Specifying the Actions to be Performed by a Workflow Transition Button
Defining and Configuring Workflow Transitions
Attaching Workflow Transitions to Workflow Stages
Adjusting the Workflow Diagram
Configuring AccuWorkflow Queries
AccuWorkflow and the Stream Browser
Drag-and-Drop Operations in Workflow
Connecting Workflow Transitions to Promote Operations
AccuWorkflow and the Edit Form
Stage Transition Toolbar Buttons
AccuWorkflow and the Queries Tab
Working with the Results of a Workflow Query
Issue Record Fields Used in a Workflow Query
Configuring the Users/Groups and Streams Panes
The process of setting up AccuWorkflow for an AccuWork issue database involves working with the AccuWork Schema Editor. This process is described in section Defining an Issue Database’s AccuWorkflow Configuration. Read this section first, because it also provides an introduction to AccuWorkflow concepts.
AccuWorkflow user-level features are described in sections for the relevant parts of the GUI:
the Stream Browser tab
the AccuWork Edit Form tab
the AccuWork Queries tab
Each AccuWork issue database has its own workflow, a directed graph whose nodes are called workflow stages and whose arrows are called workflow transitions. Here's an example, which will be used throughout this section.
Each issue record progresses, step by step, through the workflow specified in the issue database schema -- in this example, from stage New to stage Closed. AccuRev users can perform these workflow-related operations:
Determine which issue records are in a given workflow stage, using the Stream Browser or a Queries tab.
Send an individual issue record to another workflow stage by clicking a toolbar button on the AccuWork edit form.
Send a set of issue records to another workflow stage through a drag-and-drop operation. This can have the "side-effect" of promoting the versions in the change package(s) of the issue record(s).
Conversely, promoting the versions in the change package(s) of certain issue record(s) can cause those issue records to transition to another workflow stage.
The components of a workflow are initially defined on the Validation subtab:
Some validation conditions define workflow stages. Each workflow stage can specify a set of workflow transition buttons to be displayed in the AccuWork edit form of issue records that are "in" that stage.
Other validation conditions define "custom actions". Each custom action serves as the name of a workflow transition. Its definition also includes actions to be performed when the workflow transition takes place -- for example, changing field values in the issue record and setting required fields.
On the Workflow subtab, you assemble these components into a complete workflow:
A workflow transition is defined to be a custom action (such as "Schedule", "Finish Dvt", or "Pass QA") and a destination stage (such as "Scheduled", "Implemented", or "Closed"). That is, a workflow transition is not just an arrow -- it's an arrow that points to a particular stage:
You can attach any number of workflow transitions to each workflow stage:
On the Validation subtab, certain validations define workflow stages: if an issue record satisfies the validation condition, AccuWorkflow considers the issue record to be "in" that workflow stage:
After creating a condition containing one or more clauses,
you can declare that the condition defines a workflow stage. Invoke the
command Use as Workflow Stage from the condition's
context menu. Enter a name for the workflow stage in the dialog box that
appears. The name is then displayed above the condition, with a special
"stage" icon.
If a condition has already been declared to define a workflow stage:
You can return
it to being a non-AccuWorkflow condition with the command Use
as Workflow Stage. (The command is actually a toggle switch; a green
checkmark indicates that the condition currently defines a workflow stage.)
You can rename the workflow stage with the command Edit Workflow Stage.
The user initiates a workflow transition by clicking a button in the toolbar of the issue record's edit form:
The set of validation actions for a workflow stage must explicitly enable the toolbar buttons, using validation actions of type enableAction:
As this example shows, you can define any number of workflow transition buttons for each workflow stage. And you can add actions that set field values, establish field requirements, etc. -- just as with non-workflow-related validations.
Creating a validation action of type enableAction requires several steps:
Declare the "custom action"
name (workflow transition name), using the Edit Custom
Actions command on the Validation subtab.
Note: the order of the custom actions is significant. It controls the order in which workflow transition buttons will appear in the edit form toolbar (if multiple enableAction validation actions are defined for a workflow stage).
On the Workflow
subtab, make sure that a workflow transition has been defined that couples
this custom action with a destination stage. See Defining
and Configuring Workflow Transitions.
Use the Add Action command to create the enableAction action, specifying the "custom action" name.
The enableAction validation
action instantiates a workflow transition button in the edit form toolbar,
but it doesn't specify what happens when the user clicks the button. You
must make this specification with a separate validation whose condition
is the keyword CUSTOM_ACTION.
Continuing the example above, you might configure the "PostPone" and "Finish Dvt" workflow transitions like this:
At minimum, the actions initiated by clicking a workflow transition button should include setting the value(s) of the database field(s) involved in the definition of the destination workflow stage. (In this example, it's the single field wflowStage.)
On the Workflow subtab, you complete the task of configuring an AccuWorkflow. You also configure the queries that user implicitly invoke when determining which issue records are "in" a workflow stage, using the Stream Browser or on a Queries tab.
To define an issue database's set of workflow
transitions, click the 
Edit Transitions
button on the Workflow subtab toolbar. This brings up a dialog box in
which you define the workflow transitions as a set of pairs:
One member of each pair is a custom action defined on the Validation subtab with a CUSTOM_ACTION is condition.
The other member of a pair is a workflow stage defined on the Validation subtab with the Use as Workflow Stage command. This is the transition's destination: invoking the workflow transition on an issue record will change it to be "in" this stage.
Each cell in the Stage column is a list-box, containing all the workflow stages.
Each workflow stage can be the "from" stage for
any number of workflow transitions. To maintain the set of transitions
attached to a stage, choose 
Select
Transition Links from the stage's context menu. Then set/clear
any number of the workflow transition's checkboxes:
You can use drag-and-drop to adjust the Workflow subtab diagram -- for example, to prevent items from overlapping each other. The connections among the boxes and arrows of the graph are preserved, no matter where you move items.
To adjust a workflow transition arrow, drag-and-drop the orange label.
Using the Stream Browser or a Queries tab, a user can determine the set of issue records that are "in" a particular stage. AccuRev automatically composes and then executes a workflow query to determine this set of issue records; a particular AccuRev user identity and a particular stream in the issue database's depot can be inputs to this query.
For example, the Stream Browser can display the set of issue records that are in the "In Test" stage:
The workflow query that returns this set of issue records filters on the stream that the user has set as the "current project" (in this example, bear_tst).
The 
Setup
Workflow Query Fields toolbar button on the Workflow subtab toolbar
brings up a dialog box which configures how a stream (and, in some cases,
the current AccuRev user identity) in the current context will be used
in a workflow query.
If the dialog box settings are as shown in
this example, the workflow query will include one or both of these clauses:
assignedTo is john
targetRelease is bear_tst
The User listbox in this dialog box contains all the fields of type User in the issue database schema; likewise, the Stream listbox contains all the fields of type Stream.
See the help screens for the Stream Browser and the Queries tab for details on how workflow queries work in those contexts.
The Stream Browser's toolbar now provides access to a new display mode: workflow mode.
In workflow mode, the Stream Browser tab is split into two panes: the top pane contains the graphical display of a depot's stream hierarchy; the bottom pane displays the workflow for the depot's issue database.
Workflow stages are displayed in green. Stage transitions are displayed in orange. Each workflow stage has a special control that works similarly to the graphical pane controls on streams: clicking a stage's control opens or closes a subwindow that displays issue records that are currently in that stage:
At any given time, your organization probably has several (or many) active development efforts. In the upper pane, you must focus the workflow's issue-record display on a particular development effort by designating one stream as the "current project". Its name is displayed as a title in the lower pane, and also in each issue-record subwindow:
So the contents of a workflow-mode subwindow is the set of issue records that are:
in a particular workflow stage
in the context of a particular project
AccuWorkflow selects the issue records by performing a query, in which the "current project" stream is tested against the value of a particular issue-record field -- for example, Target Release. The field used in this workflow query is configurable; see Issue Record Fields Used in a Workflow Query.
You can drag-and-drop the special control for a workflow stage onto any of the workflow transitions defined for that stage.
This performs the transition for all the issue records in that stage. For example, dragging the control to the Finish Dvt transition causes issue records #5 and #9 to transition to the Implemented stage:
Drag-and-drop operations are not defined for individual issue records -- only for a the special control, which represents all the issue records in a stage.
Each transition in a workflow can be linked to a particular
dynamic stream: invoke the command 
Create
Stream Link from the context menu of a workflow transition, then
click on a dynamic stream in the upper pane. This creates a two-way link
between the workflow transition (T)
and the stream (S):
If transition T is invoked on an issue record, AccuRev attempts to promote all the versions in the issue record's change package that are currently active in stream S to S's parent stream.
If all the versions in the issue record's change package are promoted from stream S to its parent, AccuWorkflow attempts to apply transition T to the issue record.
For example, you might use Create Stream Link to specify that promoting versions from the cup_dvt stream to the cup_tst stream can transition one or more issue records from workflow stage Implemented to stage In Test.
In this example, versions were promoted through the change packages of issues #3 and #7. But the link between promotions and stage transitions works no matter how the versions are promoted -- using the Stream Browser, the File Browser, the Active Transactions tab, etc.
When you're working with issue records in an AccuWork edit form, you can click the Workflow View toolbar button to have a pop-up window display the issue database's workflow.
Each workflow stage is defined in terms of the values of one or more issue record fields. But instead of setting field values directly in order to make a transition, you click a button in the edit form toolbar:
For example, clicking the Cancel button would change field value(s) in accordance with the definition of workflow stage Closed (the destination stage of the Cancel transition).
The definition of a workflow stage can involve one or more required fields. For example, the definition of the Scheduled stage might require that the issue record be assigned a target release; similarly, an issue record might need to be assigned to a particular developer and to have an estimated development time in order to be in the In Dvt stage.
When you click a workflow transition toolbar button, AccuWorkflow examines the required fields, if any, for the destination stage. If necessary, it prompts you to provide values for one or more fields before performing the transition to the new stage:
The Queries tab's toolbar now provides access to a new display mode: workflow query mode. This mode provides a very easy way to analyze issue records by the workflow stage they belong to.
In workflow queries mode, the Queries tab is divided into four panes:
The selections you make in the users/groups pane, the streams pane, and/or the workflow pane build a query. In the illustration above, one item is selected (highlighted in blue) in each of these panes, defining a query that returns all issue records for which:
the Assignee is allison
the Target Release is the stream named bear_tst
the issue record is currently in the workflow stage In Dvt
(The query might involve some User-type field other than Assignee, and some Stream-type field other than Target Release. See Issue Record Fields Used in a Workflow Query.)
In the users/groups pane and the streams pane, you can select multiple items, by holding down the Ctrl key while making the additional selections. This defines an OR compound clause, such as:
the Assignee is user allison OR is user derek
You can also leave one or two of these panes with no item selected. (To deselect an item, click it while holding down the Ctrl key.) This removes that "dimension" from the query. For example, if you don't specify a stream, then the query will choose issue records regardless of their Target Release.
By default, selecting a group (say, famgrp) constructs a query clause like this ...
the Assignee is famgrp
... not like this ...
the Assignee is a member of famgrp
This makes it easy to assign issues in two steps. For example, one person can assign an issue to a group, without having to decide who will work on the issue. Later, another person can assign the issue to a particular member of that group.
To make a group assignment have the second meaning, check the is member of checkbox at the bottom of the users/groups pane.
To execute the query according to your current selections,
click the 
toolbar button. The issue records selected by
the query appear as a table in the query results pane. (The design of
this table is specified in the Change Package Results section of the Change
Packages subtab of the AccuWork Schema Editor. See the "AccuWork
Schema Editor" chapter of the AccuRev
Administrator's Guide.)
You can work with the issue records selected by a workflow query in some of the same ways as with a Standard Mode query. In particular, you can invoke Open Issue on a single issue record or Export Table on a selected set of issue records.
In addition, drag-and-drop operations provide a "batch update" capability for the configured User-type field and the Stream-type field:
You can drag a set of issue records onto a user or group name. This sets the value of the User-type field (Assignee in the example above) in each issue record to that user or group. Likewise, you can drag a set of issue records onto a stream name. This sets the value of the Stream-type field (Target Release in the example above) in each issue record to that stream. Example:
The User-type or Stream-type field that you change with a drag-and-drop operation does not need to be among the fields displayed in the query results pane.
You can drag a set of issue records onto a workflow transition that it valid for all the issue records, given the workflow stage they are currently in. This transitions each issue record to the destination stage, changing one or more field values according to the definition of the workflow transition. Example:
In the example above, the selected user/group
was used as the value of the Assignee
field, and the selected stream was used as the value of the Target
Release field. The issue record fields to be used in the query
are configurable, using the Setup Workflow
Query Fields toolbar button on the Workflow subtab of the AccuWork
Schema editor.
The issue record field(s) used by the workflow stage selection (in this example, In Dvt) depend on the definition of that workflow stage, on the Validation subtab of the AccuWork Schema editor. For example, the In Dvt stage might be defined in terms of a single issue record field:
wflowStage is In Dvt
Or it might be defined in terms of multiple issue record fields:
AND
state is WIP
status is Scheduled
See chapter "Designing Issue Databases and Edit Forms: The Schema Editor" in the AccuRev Administrator's Guide for details.
You can choose which user and group names appear in the users/groups pane, and which stream names appear in the streams pane:
Use the 
Setup User/Group List toolbar button
to bring up a dialog box in which you select the items to appear in the
users/groups pane. Example:
In this example, only the group name famgrp
and the name of each member of famgrp
will appear in the users/groups pane.
Use the 
Setup Stream List toolbar button to
bring up a dialog box in which you select the items to appear in the streams
pane. Example:
In this example, only the stream names bear
and bear_tst
will appear in the streams pane.