Vivid Trace 1.4 Issue Relation Graphs

This document describes the elements and interpretation of Issue Relation Graphs, a fundamental feature of Vivid Trace.

Overview
Elements of Graphs
Security

Overview

Vivid Trace automatically gathers up related issues by tracing along linked issues using Jira's Issue Linking feature and parent/sub-task relationships using Jira's Sub-task feature, and presents the resulting issue and relationship information as customizable issue relation graphs. As one of the main workhorses in Vivid Trace, these graphs are used to display trace results everywhere: in the Trace Studio, and in issue, project, project component (Jira 6.3 only), and project version (Jira 6.3 only) context traces.

The graph format faithfully provides the most direct and accurate view of the underlying issue and relationship information. All of the issues in the graph are either directly related, or are indirectly reachable by following further along the web of related issues, no matter how distant. Graph elements are subtly illuminated to naturally focus the human eye and reduce cognitive load.

Issues are displayed individually in lozenges, by default with issue type and issue key.
Issue types are shown using Jira's issue type iconography.

Lines connecting issues indicate a direct relationship between the issues with issue links or as parent/sub-tasks.
Relationships are labeled with the nature of the relation. Additional, overlapping relations between the same two issues are denoted with +n.

Resolved issues are shaded and their issue keys are struck through.

The current issue (if any) has a halo.
Quickly navigate to another issue by clicking or tapping it.

Issue relation graphs yield total visibility of all issue relations, even cross-project, enabling you to understand which issues are involved, how they are related, and a variety of other customizable information.

Interpreting the graph in this figure, work has been planned for the implementation and testing of a product feature (MD-50). Four issues each tackle a portion of the work. A new, dependent feature (MD-55) is scheduled for special attention by Quality Assurance, and a trivial defect (DNN-3208) has been identified en-route that now blocks completion. Nearly half of the workload (by issue count) has been resolved, leaving half pending completion.

Nuances

Interpretation of relations: Interpretation of issue relation graph content depends on its makeup. Each type of relation needs to be interpreted according to your agreed-upon conventions. If you come across relations outside of your area of agreement, at least the issue relation graph will serve as a good basis for discussion when confirming the meaning of equivocal relations with those who know. Moreover, the sequence that issues must be completed in depends on the interpretation of each of the relations in play and not necessarily the superficial order of appearance of issues in the graph.

Context: Issue and relation information expressed in a graph is a snapshot in time, a product of the trace configuration, the data in Jira, the access rights afforded to the user account executing the trace, the display settings and issue field layout, and processing restrictions imposed by the Issue Count Soft Maximum and Graph Traversal Time Limit. When viewing a graph, the context within which the graph was generated might not be obvious as to what information is included, and what is excluded.

Elements of Graphs

Issue Lozenges and Field Layouts

Vivid Trace displays issues individually in lozenges, each containing issue information according to customizable issue field layouts. These layouts act as templates, determining the selection and position of issue fields shown in each of the lozenges.

The default issue field layout consists of a single row of two issue fields: issue type, and issue key.

A halo indicates the current issue in issue-context traces on issue details pages.

Resolved issues are gently shaded, and their issue keys are struck through with a solid horizontal line.

Various appearances of issue lozenges.

Issue Relationships

A relation relates a pair of issues with a specific type of relation, and is either an issue link or a parent/sub-task relation.

Issue on the outward side of the relation.

A label indicates the type of relation, using its outward description.

Issue on the inward side of the relation.

A connecting line indicates a direct relation between the issues.

Direction of the relation, indicated by an arrowhead pointing to the issue on the inward side.

Figure: The elements of an issue relation.

The elements of an issue relation. The relation between these two issues is read as "MD-78 blocks MD-95".

Issue Link Relationships

Issue links are a standard feature of Jira. They have a type and a direction.

Types

: Which issue link types are enabled depends on the settings in the Trace Studio, the project configuration, or the issueLinkType parameter of the relations() JQL function suite.

Vivid Trace supports the issue link types packaged with Jira, with those included in plugins such as Xray for Jira, as well as with your own custom types. Jira administrators can create and manage issue link types. When creating a new issue link type (a one-time event), investing in a reasonable name, outward description, and inward description will pay off in saved time and reduced communications when people read the links (frequently thereafter).

The issue link types created by Jira at installation are discussed in the following table.

Name	Outward Description	Inward Description	Discussion
Blocks	blocks	is blocked by	In terms of order of execution, this link type can be interpreted as: If issue A blocks issue B, then A must be resolved before B can be resolved.
Cloners	clones	is cloned by	Jira by default automatically creates this relation to an issue from its clone as a result of using the Clone issue operation (Administration topic), leading to the interpretation that the outward issue cloned the inward issue. Issue data was copied into the clone at the time of cloning, and the two issues now stand separately.
Duplicate	duplicates	is duplicated by	Useful while performing triage on issues coming from a variety of sources. Issue relation graphs will help you easily access the cluster of duplicates in case you need to synthesize or merge information from them.
Relates	relates to		A relation between two issues in general. Although this concept implies uniform meaning to the relationship in both directions (a symmetric relation) as evidenced by that fact that both the outward and inward descriptions are identical, as a Jira issue link this link type technically has a direction and is graphed as so. Reading other issue details will probably reveal the reason for the use of this issue link type, and might even provide impetus for creating a new, precisely-described link type.

Issue link types created by Jira add-ons may already have a fixed interpretation. For example, Zephyr for Jira manages its own "Tests" issue link type whose general interpretation means "member of a test suite" but the specific interpretation of the relation's direction depends on Zephyr's add-on configuration regarding links.

Direction

: Links are directional, having "outward" and "inward" directions. When two issues are linked together, they are linked from the outward issue to the inward issue. Vivid Trace can follow issue links in one or both of these directions, with the Directions trace configuration setting and the direction parameter of the relations() JQL function suite. Technically, relationships are directional but your interpretation of particular relation types need not be. Interpretation ultimately depends on your teams' agreement to a consistent interpretation of each type.

MD-81 blocks MD-85.

MD-81 blocks MD-85, and there are also two more relations.

MD-85 blocks MD-81.

Reading relations according to their direction.

Parent/Sub-task Issue Relationships

Sub-tasks are a standard feature of Jira. Sub-tasks are distinguished from Jira issues in that they can be created subordinate to any issue (the parent). Parent/sub-task relations are directional, having "parent" and "subtasks" directions, controlled by settings in the Trace Studio or the direction parameter of the relations() JQL function suite. Jira administrators can define new sub-tasks.

Figure: The appearance of a parent/sub-task issue relationship.

The appearance of a parent/sub-task issue relationship. MD-47 is a sub-task of MD-33, and MD-33 is the parent of MD-47.

Overlapping Relationships

Two or more relations can simultaneously exist between a pair of issues. In such cases the overlapping, additional relations are denoted using the nomenclature +n to indicate their quantity. Hovering the mouse over the relation will reveal a tooltip that lists all of the relations. Note that Jira doesn't allow more than one of the exact same relation between the same two issues.

Relationship Labels

Relation lines can be labeled with the outward description of the relation, according to the "Show relationship labels" setting is in the context trace menu and also in the Display Options of the Trace Studio.

Graph Drawing Direction

Graphs can be drawn leftward, top-down, or rightward, according to the "Graph direction" setting in Display Options in the Trace Studio. The drawing direction indicates in which direction drawing proceeds, from outward side to inward side. In contextual traces, graphs are always drawn rightward. Note that changing the graph direction does not change writing direction, and that the contents of the issue relation graph is always left-justified.

Orphan Issues

Associated issues that don't have relations, or whose relations are disabled in the trace configuration, can be grouped together as orphan issues. This "Group and label orphan issues" setting is in Display Options in the Trace Studio. In contextual traces, orphans are always grouped and labelled.

Interactive Elements

Many of the issue relation graph elements are interactive as described in the following table.

Action	Reaction
Click on an issue	Navigate to that issue's issue detail page.
Click on a URL issue field	Navigate to that URL.
Hover mouse over an issue field	Reveal a tooltip of the full contents of the abbreviated issue field.
Hover mouse over a relation	Reveal a tooltip that lists the relations.
Mouse-over an issue	Raise and highlight the issue, its direct relations, and the directly related issues.
Mouse-over a relation	Raise and highlight the relation and its directly related issues.

Security

If Jira determines that you don't have permission to browse certain issues encountered during the tracing process, the graph will omit the inaccessible issues and be accompanied with warning VTW-7 alerting you of omissions.

This graph is incomplete, and might be misleading or inconsistent.

VTW-7: One or more issues have been omitted due to insufficient browse permissions.

The trace results don't reveal any information about which issues were inaccessible, including which issues in the graph lead to the inaccessible issues.