Defining an AccuWorkflow Configuration

Each AccuWork issue database has its own workflow, a directed graph whose nodes (green rectangles) are called workflow stages and whose arrows (with orange labels) 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:

Workflow Components

The components of a workflow are initially defined on the Validation subtab:

On the Workflow subtab, you assemble these components into a complete workflow:

Defining Workflow Stages

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:

 

Validation Actions for a 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:

  1. Declare the "custom action" name (workflow transition name), using the Edit Custom Actions command on the Validation subtab.

  2. 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).

  3. 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.

  4.  

     

  5. Use the Add Action command to create the enableAction action, specifying the "custom action" name.

Specifying the Actions to be Performed by a Workflow Transition Button

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.)

Defining and Configuring Workflow Transitions

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:

Each cell in the Stage column is a list-box, containing all the workflow stages.

Attaching Workflow Transitions to 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:

Adjusting the Workflow Diagram

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.

Configuring AccuWorkflow Queries

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.

Quick Start for Defining a Simple Workflow

At this point you may be thinking to yourself,  "All of the above information is well and good, but how in the world do I get started?"

The best way is to examine and customize the sample workflow that comes with the default AccuRev schema. When you are comfortable working with this default workflow, you can start designing your own.

Confirm That You Have Access to AccuWorkflow and the Schema Editor

First, make sure that you have an AccuWorkflow license AND that you have access to the Schema Editor. If your site doesn't have a license, you won't be able to use or view AccuWorkflow functionality. And even if your site has a license, you won't be able to define any workflows if you don't have administrator privileges sufficient to use the Schema Editor. Try one or both of the following tests:

Try bringing up the Schema Editor. If you can, check to see if the Workflow tab is grayed out. If it is, you don't have AccuWorkflow enabled.

If you can't bring up the Schema Editor at all, it doesn't matter whether AccuWorkflow is  licensed or not. Speak to your management about getting administrator privileges.

You can also try looking at the AccuRev license file, keys.txt, in the storage/site_slice directory on the AccuRev server. If there isn't a line in this file labeled "accuworkflow", you do not have an AccuWorkflow license. (Don't confuse this with an "accuwork" license, which is completely different.)

Using the Example Workflow in the Default Schema

Assuming that you have an AccuWorkflow license, as well as administrator privileges to use the Schema Editor, and assuming that your schema has not been modified or replaced, you can examine the example workflow that comes with AccuRev.

Planning your workflow

If you were starting from scratch, the first step might be to get pencil and paper and map out a workflow that reflects your working environment. This might include evaluating and modifying any existing AccuWork issue conditions and actions to better map your new AccuWorkflow stages and transitions. In this example, though, we are going to take a look at the sample workflow that comes with the default AccuRev schema, and plan a minor addition to it.

1. Click Schema Editor on the Admin menu.

2. If prompted, select a depot.

3. Click the Workflow tab.

Note: If you cannot open the Workflow tab, your site is not licensed for AccuWorkflow. If the tab opens, but comes up blank, your schema has been modified and the example workflow has been removed. Unless you have access to a test server with the original schema, you will need to read through the following examples and try to map the concepts to your current schema.

You should see a display similar to the following:

 

 

4. Look at the far right side of the workflow and note the Cancelled stage and the Cancel transition. You are going to add a new "Reopen" transition to the Cancelled stage, which will lead to a new "Review" stage. From Review, the existing Cancel transition and a new "Approve" transition will be available. In other words, this addition to the workflow will permit a cancelled issue to be re-opened, reviewed, and either cancelled again or returned to an active path.

 

Define the new stage(s) and transitions

1. To define the new Review stage, go to the Schema tab, and select the State row. In the Field Values pane, enter "Review" (do not include the quotes), then click Add.

 

2. Return to the Validation tab and at the bottom of the Conditions column, right-click Add Condition and set conditions to:

 

state is review
status is Closed

 

Click Ok when done, then right-click in the new row to set Use as Workflow stage. Name the stage "Review".

 

3. Define the new transitions (Reopen and Approve):

Still in the Validation tab, click the Edit Custom Actions icon ( ) at the top of the tab.  In the resulting Edit Custom Actions dialog, enter "Reopen" (don't include the quotes) then click Add. Then do the same for "Approve". When done, click Ok.

 

4. In the Actions column for this new Review stage, right-click and select Add Action.  In the resulting Action dialog, select enableAction as the "Action type:", and Approve as the "Custom Action". Click Ok, then repeat this process to set::


enableAction(Cancel)

 

5. Add the Reopen transition to the Cancelled stage: navigate to the row labeled "Cancelled" with the small green stage icon (), and in the Actions column, right-click and select Add Action. In the resulting Action dialog, select enableAction as the "Action type:", and Reopen as the "Custom Action:" Click Ok when done.

 

6. Define the behavior for the Reopen transition:  In the Validation tab, go to the bottom of the Conditions column and right-click and select Add Condition. In the resulting Edit Logical Expression dialog, use "Click here to add..." to define "CUSTOM_ACTION is Reopen" and click Ok when done. In the Actions column of the new row, right-click for Add Action, and in the resulting Action dialog, set "Action type:" to setValue, "Field:" to state, and "Value:" to Review. Click Ok when done.

Define the enableAction behavior

 

Since the behavior of the Cancel action was already defined in the default schema, you only need to define the behavior of the new Approve custom action, which will be to return the reopened issue to the "New" state.

At the bottom of the Conditions column in the Validation tab, right-click and use Add Action to set "CUSTOM_ACTION is Approve".  In the Actions column, right-click and use Add Action to set "Action type:" to setValue, "Field:" to status, and "Value:" to New. Click Ok when done.

Note: As of Release 4.9, it is now possible to easily associate an existing transition with an existing stage for new logical branches: Add a new row in the Validation tab, and in the Add Condition dialogbox, select Stage, is, and the existing stage name from the drop-down menus.  In the Actions column, add an action, and in the Action dialogbox, select enableAction from the Action Type: drop down, and the desired transition from the Custom Action: drop down.

 

 

Associate Actions Destination Stages

That's it for the Validation tab; now pull things together in the Workflow tab.

1. Click on the Workflow tab. So far none of your additions are visible, so click the Edit Transitions icon ()  at the top of the tab, and in the Edit Transitions dialog, change the Reopen action from <none selected> to Review. Then change the Approve action from <none selected> to New.

2.  Now right-click the Cancelled box and use Select Transition Links to enable the Reopen action.  Click Ok, and you should see a Reopen transition box appear on the workflow diagram, with arrows connecting it to the Review box. These will probably be positioned poorly, so drag and drop the Reopen and Review boxes somewhere underneath the Cancelled box.

 

3. Finally, right-click the Review box, and use Select Transition Links to enable the Approve and Cancel options. Click Ok and then drag and drop the new elements so that they are readable. The end result should be similar to below:

 

Send an Issue Through the Workflow

To try out this workflow, create a new issue and cancel it using the Cancel button ():

 

The next stage will now display the new Reopen button ().

 

 

Click this to move to the new Review stage, which now displays both the existing Cancel button and the new Approve button:

Clicking Cancel returns the issue to its Cancelled state. Clicking Approve sets the issue status to New, the same as if it were a newly-entered issue.