Issue Form

This section describes the layout and features of the AccuWork Issue form. To learn how to create, clone, and modify AccuWork issues, see Working with Issues on page 287.

All AccuWork Issue forms have these features in common:

•	The Issue form consists of one or more pages, which appear as subtabs within the overall GUI tab. Typically, there's a header section, which always remains visible as you switch from page to page, using the mouse.

•	Each field is represented by a simple text box, a multiple-line text box, a multiple-choice listbox, or a more complex user-interface "widget". To the left of this widget is a descriptive label for the field. (A red label indicates a required field.)

Special Subtabs

Every Issue form has two special subtabs, which appear and work differently than the standard fill-in-the-blanks "pages":

•	The Changes subtab displays the issue record's change package, and provides options for analyzing and manipulating the change package's entries. See The Issue Form -- "Changes" Subtab on page 304 for more information.

•	The Issue History subtab displays a complete breakdown of how the issue record's field values have changed over time. See The Issue Form -- "Issue History" Subtab on page 306 for more information.

Workflow Toolbar

If your site is configured to use the optional AccuRev workflow feature, your Issue form may display the following workflow toolbar:

AccuRev Workflow is documented in the AccuRev® Web Interface User’s Guide, Version 2012.1 or later, but a brief summary of this toolbar is:

Workflow:

A label that identifies the name of the workflow to which the current issue is subject.

Stage:

A label icon that identifies the issue's current workflow stage. (This is not clickable.)

Transitions:

One or more buttons that execute any transitions that are valid for the issue.

Note: If an issue doesn't match any workflow stages, or is subject to multiple workflows, AccuRev displays a message to that effect where the buttons would otherwise appear. If an issue's fields don't match with the logic specified for a transition, the transition button appears, but it is grayed out until the user changes the fields required to bring the issue into compliance.

Working in an Issue Form

You can enter and change values in any number of fields, and visit different pages in a multiple-page form. Here are some notes, describing aspects of AccuWork Issue forms that may differ from other fill-in-the-blanks forms:

1.	Navigating fields and pages

To move from field to field, use the mouse or press Tab and Shift-Tab. To move from page to page in a multiple-page Issue form, click the subtab name (there is no keyboard accelerator).

The Enter key confirms a menu choice or enters a line-break in a multiple-line text field. It does not perform field navigation. Within a multiple-line text field, the Tab key inserts a TAB character, rather than jumping to the next field.

2.	Browsing multiple issue records

While you’re working with issue record, browse arrows are enabled in the Issue form’s toolbar.

This makes it easy to view a set of consecutive issue records. If you’ve made some changes that you haven't yet saved, AccuWork prompts you to save or discard those changes before switching to the previous or next one.

3.	Field initializations

When an Issue form appears after you invoke Create Issue, you may notice that some fields already have values. AccuWork can include any number of such field initializations.

4.	Required fields

If a field's label appears in red, it is a required field. You cannot Save the issue record until every required field has a value. (A text field has a value if it's non-empty. A multiple-choice listbox field has a value if it's not “<none selected>”.) Some of those fields may have gotten their values through an automated field initialization.

If you attempt to save the issue record when one or more required fields still need a value, a pop-up window prompts you to supply the value(s).

5.	Other field validations

Field initializations and required fields are implemented through AccuWork's field validations (or "edit checks") facility. As you work in an Issue form, changing field values, you may notice these field-validation effects:

•	A text field, multiple-choice listbox field, or timestamp field has automatically been set to a specified value.

•	The set of required fields has changed.

•	A listbox's set of choices has changed.

•	The entire issue record, a particular page (subtab), or a particular field has been set to read-only status.

6.	An issue record's unique identifier

Each issue record has an integer identifier, its issue number. This number is unique within the depot (but not within the entire repository). AccuWork assigns the issue number automatically the first time the issue record is saved, and it cannot be changed thereafter. The issue number is stored in field issueNum. By default, the label for this field in an Issue form is Issue, but the edit-form designer can change the label for this field.

Saving or Discarding Your Work

Your entries in an Issue form are not stored in the issue record until you click the Save or Save & Close button in the Issue form toolbar. If you don't wish to save your work, just close the edit-form tab as you would any GUI tab.

When you save an issue record:

•	(for a new issue record) AccuWork assigns the next available integer issue number to the new issue record. This number cannot be modified.

•	The issue record is stored in the depot. A transaction of kind dispatch records the creation or modification of the issue record. No matter how the issue record is modified subsequently, you can revisit the issue record in its current form on the Issue History subtab.

•	If you clicked Save, the Issue form remains open, with the newly assigned issue number replacing the "New Issue" label and appearing in the Issue field.

Note: "Issue" is the default label for the issueNum field, but it might have a different label, depending on how the schema is configured.

•	If you clicked Save & Close, the Issue form closes.

Working with Special Fields

AccuWork supports special field types, which have special user-interface "widgets" on an Issue form. These are described in the following sections.

Timestamp field

You can fill in the individual subfields manually, or use the Select Date button to display choices ("tomorrow", "2 days ago", etc.) that fill in the subfields automatically. Once these subfields are filled in, you can revise them individually or by clicking the Select Date button again.

Multiple-Line Text and Log fields

A text field can have multiple lines, and can also specify both the width and the height of the textbox on the Issue form.

When you use the form you can use the control at the top of the textbox to temporarily expand the height. Click the control again (it is now ) to decrease the height. A scroll bar appears on the textbox whenever the current contents of the field are not completely visible.

A log field is a variant of a multiple-line text field. You can type directly into such a field. And if you click the Add Timestamped Text control, a timestamp text line is inserted at the beginning or end of the field.

Rich text fields

If support for rich text has been enabled by your AccuRev administrator, AccuWork displays tools to help you work with HTML, as shown in the following example of a Description field:

The following table summarizes rich text tools and what they do.

Tool	Description
Show Source button	Displays the HTML source for formatted text. When clicked, the button text changes to Hide Source. Clicking the Hide Source button reverts the display to formatted text only.
Toolbar	Contains tools for text formatting and working with elements like table and images § Font size § Font color § Bold text § Italic text § Underlined text § Unordered list § Ordered list § Hyperlink § Image

Fields for which rich text support has been enabled display formatted text (numbered lists and bolded text, for example) by default. For example, if you create an issue in the AccuRev Web UI or a third-party issue tracking tool that supports rich text, the formatted text is displayed in AccuWork.

Note: If a field contains unescaped bracketed text in, say, a third-party issue tracking system, AccuWork renders the brackets and the string they contain as a button, as is the case with the string <unescaped> in the example shown here:

To resolve issues like this:

1.	Click the Show Source button to display the HTML source.

2.	Copy the HTML source.

3.	Click the Hide Source button to revert to the rich text display.

4.	Replace the rich text with the HTML source you copied in Step 2.

Rich text support is available for fields with a data type of either Text or Log and is enabled on a per-field basis. See Enabling Rich Text for Text and Log Fields on page 384 for more information.

Timespan field

A timespan field is AccuWork's only numeric field type. You can type any value into the field, but when you leave the field, AccuWork automatically erases a non-numeric value. Negative numbers and decimals are allowed. If you enter an integer (e.g. 45), it is automatically converted to a decimal (45.0).

Attachments field

An Issue form can contain one or more attachment fields. In each such field, you can specify one or more files and/or Internet addresses (URLs) to be attached to the current issue record. AccuWork displays the attachments data as a table.

In addition to specifying the location of a file or Internet resource, you enter a name and optional comment. AccuWork automatically fills in your username, the date, and the size of the attached file. (Internet URLs are assigned a size of 0.) If the edit-form field is not large enough to show all these attachment parameters, use the scroll bar to see all the data. You can also resize and rearrange the columns of an attachments table.

An attachment field includes its own toolbar, with these buttons:

Field	Description
New Attachment	Define a new file attachment for this issue record. A New File Attachment dialog appears, in which you can specify one or more files, a name for the attachment, and a comment string. You can specify multiple files at once -- each one becomes a separate file attachment. In this case, the Attachment Name input field is disabled; each filename is automatically assigned as the attachment name. The comment string that you specify is assigned to each file attachment.
New URL	Define a new attachment to be the address (URL) of an Internet resource. A New URL Attachment dialog appears, in which you specify a URL, a name for the attachment, and a comment string. AccuWork inserts the string http:// in the URL field. You can erase this if you want to specify a location accessed by another Internet protocol, such as ftp:// .
Open Attachment	Open the existing attachment that is currently selected, using the appropriate program.
Save Attachment As	Create a copy of the currently selected attachment on the client machine.
Properties	Launch a Properties window, displaying the definition of the currently selected attachment. You can use this window to change the attachment's Name or Comment value.
Delete Attachment	Remove the attachment from the issue record (and from the depot). A URL attachment can be deleted at any time. A newly added file attachment can be deleted if you haven't yet saved the issue record.

When you save the issue record, each file is copied to the depot, so that the data always remains available through the issue record, even if an original file is deleted.

Relationship field

AccuWork supports several kinds of relationships between a pair of issue records:

•

Duplicate: You can specify that issue record B duplicates issue record A, so that no work need be done on B. (Perhaps the same bug was reported twice.) Any number of records (B, C, D, ...) can duplicate a given record (A). The default AccuWork issue schema requires that a Duplicate relationship be established when an issue record's State field is set to the value Duplicate. See Viewing and Maintaining an Issue Record's "Duplicate" Relationships on page 302 for more information.

•	Dependency: You can specify that issue record B depends on issue record A (for example, from a project management viewpoint). AccuRev imposes no further semantics on such dependencies; this is a good application for user-defined scripts or practices.

IMPORTANT NOTE: Issue dependencies you define manually on the Issue form are independent of change package dependency relationships among issue records, which are maintained automatically by AccuRev. See Change Packages, Segments, and Dependencies on page 334 for more information.

•	Subtask: You can specify that issue record B defines a subtask of the work to be performed for issue record A. In this case, AccuRev considers issue record A to be "in" a particular stream only if issue record B is "in" that stream, also.

•

Tracking: Tracking issues are sometimes required after you cross-promote and patch multiple issues to a destination stream, and you might choose to use them if for some reason you wish to have a patch operation (for example) tracked by its own unique issue rather than by a variant of an existing issue. See Tracking Issues on page 375 for more information.

You cannot create "relationship chains": for example, if B duplicates A, you cannot make C a duplicate of B.

Issue record relationships can be viewed only in the AccuWork GUI. The Issue form tables that display relationships are not included when you export an issue record (for viewing or printing). These tables are not included when you use the AccuWork command line interface (CLI) to dump the contents of an issue record. (See the AccuWork™ Command-Line Interface chapter in the AccuRev CLI User’s Guide.)

When you create or delete a relationship between issue records, the change to both issue records is saved immediately. There is no need to invoke Save on the issue record. (The Save button is not enabled in the edit-form toolbar.)

Viewing and Maintaining an Issue Record's "Duplicate" Relationships

The "duplicate" relationship is not symmetrical: "A duplicates B" is not the same as "B duplicates A".

Accordingly, an edit-form field displaying a duplicate-type relationship consists of two tables: the top table shows issue records that are duplicated by the current record; the bottom table shows issue records that the current record duplicates.

Because of the "relationship chains" restriction, issue records can appear in only one of these tables, not both.

On the other hand, "A duplicates B" is the same as "B is duplicated by A". This means that when you add an entry to the top table of one issue record, AccuWork automatically adds it to the bottom table of the other issue record (and vice-versa).

A Duplicate relationship field has its own toolbar, with these buttons:

Link Issue

Create a relationship link with another issue record. AccuWork prompts you to enter an issue record number.

Remove Link

Remove the selected relationship link.

Note: Duplicate Relationship and Duplicate State

In AccuWork's default issue schema:

•	There is a State field in the header section, one of whose values is Duplicate. (The Status value must be Closed to enable the setting of the State value to Duplicate.)

•	There is a Duplicates field in the Relationships subtab.

•	An edit-form validation specifies that when you set the State field's value to Duplicate, you must indicate which issue record is duplicated, by creating an entry in the Duplicates field.

Exporting an Issue Record

You can export issue records in either HTML or XML.

1.	Click the Export button in the form's toolbar.

2.	Select the file type in the Save As dialog that appears.

3.	Specify a pathname for the export file. You don't need to specify the .html or .xml suffix -- AccuWork adds it automatically.

When creating an HTML file, AccuWork outputs all the content of the issue record and approximates the form layout, too. Even if the Issue form has multiple pages, you need to "print" only once. All of the pages are combined into a single HTML or XML file:]

On Windows machines, AccuWork automatically invokes a web browser on the HTML file it creates. If you wish, resize the browser window to optimize the look of the issue record. HTML documents automatically adjust to changes in window width. Then, use the browser's print option to create a printout of the issue record.

The Issue Form -- "Changes" Subtab

The Changes subtab of an issue record's Issue form shows the change package of the issue record. You can invoke options to see the details of the change package's changes, maintain its entries, and view the transaction and version history of its elements.

For a detailed discussion of change packages, see Chapter 10 Change Packages.

"Changes" Subtab Layout

The Changes subtab contains a table, each row displaying one "change package entry". A given element can have at most one entry in a change package -- but this entry can "grow" over time, as development work continues on the element. The table includes these columns:

Element (or separate "Name" and "In Folder" columns)

The element's pathname within the depot.

Version

The head version of the change package entry.

Basis Version

The basis version of the change package entry.

The head version and basis version are the "endpoints" of the change package entry. That is, the entry consists of all the versions between these two versions. (The head version is included; the basis version isn't.)

Working in the "Changes" Subtab

The Changes subtab has options for modifying change package contents:

•	Remove deletes one or more selected entries from the change package.

•	Send to Issue copies one or more selected entries to another issue record's change package.

But the change package facility is designed so that most modifications to change packages occur as "side effects" to the Promote operation, by the change-package-level integration between AccuRev and AccuWork. (Change-Package-Level Integration between AccuRev and AccuWork on page 400.)

See also: Working with Tables on page 14

Options Available in the "Changes" Subtab

Remove

Deletes the selected entry(s) from the change package.

This change takes effect immediately -- you cannot discard the change by closing the Issue form without invoking Save. (Removing change package entries does not enable the Save button in the edit-form toolbar.)

Diff Against Basis

(text-file elements only) Compares the entry's head version with the basis version. This shows exactly what changes to this element are included in the change package.

Show History

Open a History Browser tab, containing the transactions involving the selected element.

Browse Versions

Open a Version Browser tab, showing all the versions of the selected element, and their interrelationships (ancestry).

Send to Issue

Copies the selected entry(s) to another issue record's change package. If there's an existing entry for an element in a destination change package, an attempt is made to combine the existing entry with the entry you specified. The change(s) take place immediately in the destination issue record(s). There is no way to cancel the change(s) -- but you can open the issue record(s) and Remove the entry(s).

The default query is executed, and the results are displayed in a dialog (see Send to Issue : Associating Changes with an Issue on page 354). You are prompted to choose one or more of the issue records selected by the query. You can also create a new issue record, whose number will be entered in the dialog.

Properties

Displays information about the selected element. The data items displayed vary with the type of element.

The Issue Form -- "Issue History" Subtab

The Issue form of an AccuWork issue record always includes a subtab named Issue History, which is maintained automatically by AccuWork. This subtab shows, on a field-by-field basis, how the issue record has changed over time.

You can use this subtab to view past "versions" of the issue record.

"Issue History" Subtab Layout

The Issue History subtab contains a table, each row of which shows how one field was changed (or initially created) by a particular save of the issue record.

The table contains these columns:

TransNum

The number of the Save transaction. (The transaction kind is dispatch.)

User

The user who made the change to the issue record.

Date

The time at which the change tool place.

Field

The field whose value changed (or was initially created).

New Value

The value to which this transaction changed this field.

Old Value

The value of this field prior to the Save. (Empty for the issue record's initial Save transaction.)

Working in an "Issue History" Subtab

If you double-click any row of the Issue History table, AccuWork opens a read-only Issue form, showing the state of the issue record at the time of that particular Save operation. (Exception: the issue record's change package does not participate in this feature.)