The AccuWork Schema Editor
(Schema subtab)
Adding and Removing Fields from the Database Schema
Removing a Field / Restoring a Field
Integrating Configuration Management and Issue Management
Defining Multiple-Choice Lists
Defining Issue Record Relationships
Defining the Issue Database's AccuWorkflow Configuration
Validation Actions for a Workflow Stage
Specifying the Actions to be Performed by a Workflow Transition Button
Defining and Configuring Workflow Transitions
Attaching Workflow Transitions to Workflow Stages
The Schema tab of the Schema Editor contains a table that details all the data fields in the current depot's AccuWork issue database (AccuWork) A set of issue records, each of which implements a bug report, feature description, etc. Each depot can have its own issue database. Each issue database has its own schema..
If you are not using the repository's default schema, AccuWork initializes the Schema Fields table with two fields.
issueNum: An integer-valued field that records the position of the issue record (AccuWork) A data record, consisting of values of data fields, stored in an issue database. in the depot's issue database (AccuWork) A set of issue records, each of which implements a bug report, feature description, etc. Each depot can have its own issue database. Each issue database has its own schema.. This number is assigned when a user creates the record (i.e. at the first Save on the edit form), and it never changes.
transNum: An integer-valued field that records the transaction A record in the AccuRev repository database that indicates a particular change: promoting of a set of versions, changing the name of a stream, modification to an issue record, etc. Each transaction has an integer transaction number, which is unique within the depot. number of the most recent update to the issue record. The transaction appears in the depot's transaction log -- the same log that records AccuRev transactions, such as keep and promote. The type of the issue-record-update transaction is dispatch.
Notes (click to view):
A record's issueNum value never changes, but its transNum value changes each time a user Save's the record. issueNum and transNum are indexes into two different databases.
The change-package-level and transaction-level integrations between AccuRev and AccuWork also update issue records, and so changes the value of the transNum field.
See Also:
You can define any number of additional fields in the issue database schema. Follow these steps for each new field:
Click the Add button at the bottom of the Schema subtab.
Fill in the Create New Field window that appears:
Click Ok to close the Create New Field window.
In the Field Values box to the right of the Schema Fields table, specify additional information about the field. The kind of information required varies with the data type.
Repeat the steps above as often as required to create new fields in the AccuWork database. Your field definitions are not saved until you click the Save button in the lower-right corner of the Schema Editor tab. You cannot save your work until you place at least one field in the database's edit form (Layout subtab).
To remove an existing field (except for issueNum and transNum), select it and click the Remove button. The field disappears from the Schema tab and can no longer be used in the edit form. But any data stored in existing issue records is preserved.
When you remove a field from the schema, AccuWork checks whether the field is used in the issue database's edit form. If so, it removes the field from the edit form
You can restore a removed field to the database schema:
Check the Show Including Hidden checkbox. All removed fields appear in the list, with a gray background.
Select the field to be restored, and click the Reactivate button.
The
Issues > Look Up command prompts the user to enter a value, then uses that value to locate an issue record. By default, this lookup operation uses the issueNum field (whose user-visible label is Issue).
You can configure another field to be used for issue-record lookups, using the 3pty ITS Key listbox. (This feature is designed to facilitate AccuBridge integrations with third-party issue-tracking systems.)
Select another field from the listbox, and save the schema.
Thereafter, the Issues > Look Up command will prompt for a value to be matched against the specified field.
Notes (click to view):
The Issues > Look Up command requires an exact match between the user's entry and the value in the issue-record field. Exception: upper-case/lowercase differences are ignored. This can cause problems if the lookup field is a Text field.
AccuRev guarantees uniqueness of the issueNum field value only. It allows duplicate values in all other fields. Be sure to specify an alternative lookup field whose values are rendered unique by some other mechanism. If a user performs a lookup on a non-unique value, an error occurs:
If you wish to enable the integration of a depot's version-controlled files and its AccuWork issue records, define a database field whose name is affectedFiles. The field's data type must be Text. You can choose any label for the field. (Such a definition is included in the default AccuWork database schema.)
The integration also depends on the enabling of a built-in AccuRev trigger procedure:
accurev mktrig -p <depot-name> pre-promote-trig client_dispatch_promote
The integration routine writes the transaction number of each promote command to the affectedFiles field of a particular issue record. Alternatively, in the AccuRev Enterprise version of AccuWork, the integration routine records each promoted version in the issue record, in a special section named Changes . This section is maintained automatically by AccuWork -- you don't need to define any database fields to enable this additional aspect of the integration.
See Also:
Change-Package-Level Integration
Each field you define in the Create New Field window must have one of the AccuWork data types listed in the table below.
Field Type |
Possible Values |
Required Additional Information in "Field Values" Box |
---|---|---|
Text |
Any character string. For multiple-line fields, the string can include line-terminators. |
Height: number of lines displayed for the field in the edit form (default: 1). For multiple-line fields (height > 1), the edit form includes an expand/contract button to increase/decrease the number of lines displayed. Width: relative width of field in the edit form. |
Choose |
One of the strings specified in the Field Values box for this field. |
A set of strings. In the edit form, a list-box containing this set of strings is offered to the user. |
Timestamp |
An AccuRev timestamp. |
Granularity (year, month, day, hour, minute, or second). In the edit form, the user fills in fields that indicate a time, to the granularity you specify here. |
User |
One of the principal-names in the user registry maintained by the AccuRev server. |
None. In the edit form, a list-box is offered to the user, containing the names of all registered AccuRev users A person who uses an AccuRev client program to access (read and/or change) the data in the AccuRev repository. Access is granted only to those who login with a "username" that was previously registered in the AccuRev repository. See login.. |
Stream |
One of the stream, snapshot, or workspace names in the depot where the AccuWork issue database resides |
None. In the edit form, a list-box containing all stream, snapshot, and workspace names is offered to the user. |
Timespan |
A numeric value, indicating a number of hours. Decimal values (e.g. 4.5) are allowed. |
None. |
List |
One of the strings specified in the definition of a particular named list. |
The name of an existing list, defined on the Lists subtab. In the edit form, a list-box containing the set of strings defined in the named list is offered to the user. |
Log |
Any character string (variant of text field type) |
In the edit form, an Add Text control appears above the input field. The user can type directly into the input field, or can click the Add Text control and create a "log entry" in the popup window that appears. |
Attachments |
A set of attachment definitions. |
Height, Width: the height (number of lines) and width (approximate number of characters) of the edit-form field that lists the attachment definitions. |
Relationship |
A set of issue records |
|
Internal |
A positive integer. |
None. You cannot create a field with this data type; it is used only by the built-in fields issueNum and transNum . |
The choose and list data types are similar:
For a choose field, the set of possible values -- an ordered list of strings -- is part of the individual field definition. You enter the possible-values list in the Field Values box for that field.
For a list field, the set of possible values is also an ordered list, but it is not part of the individual field definition. In the Field Values box, you specify the name of one of the lists created on the Lists subtab. Any number of list fields in an AccuWork database can use the same named list.
The mechanics of defining the ordered list is similar in the "local" case (for an individual choose field) and in the "global" case (on the Lists subtab, for use by any number of list fields). On the Lists subtab, you must supply a ListName for the list; for an individual choose field, the possible-values list doesn't need or have a name.
When you create a field of type Relationship, you must select the Duplicate, Subtask, or Dependency relationship type for the field. On an edit form, the field's edit-widget is a pair of tables. The upper table displays "inward" or "child" relationship links -- that is, links from other issue records to the current record. The lower table displays "outward" or "parent" relationship links -- that is, links to other issue records from the current record. (Multiple-link chains are not allowed -- each issue record can be related to others by child links or parent links, but not both.)
The figure below show how a Duplicate relationship field appears in an edit form. A relationship field of type Subtask or Dependency appears similarly.
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.
You can drag-and-drop the orange labels representing workflow transitions and/or the blue boxes representing workflow stages.
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 topics for the Stream Browser and the Queries tab for details on how workflow queries work in those contexts.