Vivid Trace 1.4 Feature Tour

This document introduces features of Vivid Trace, an add-on for Atlassian JIRA. This document covers the following topics:

Vivid Trace automatically gathers up related issues by tracing along related issues using JIRA's Issue Linking feature and parent/sub-task relationships using JIRA's Sub-task feature, and presents the resulting trace information as an issue relation graph. 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. An issue that has even many relations will appear exactly once in the graph. 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.

This graph format faithfully provides the most direct and accurate view of the underlying issue and relationship information. See Issue Relation Graphs for full details.

Issues are displayed in individual 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.

Figure: The Issue Relation Graph

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.

The Trace Studio

Accessible from nearly everywhere in JIRA, the Trace Studio is a new focal point in Vivid Trace. With it, you can visualize related issues, produce traceability reports, conduct change impact analysis, ascertain compliance, and much more. You can design, run, save, and tweak traces with parameters that parallel the relations() JQL function suite. You can also design the information display to help you visualize, analyze, and communicate trace results. See Trace Studio for full details, including the quickstart.

Trace arbitrary JQL queries or any number of issues of interest, according to various criteria. Design the presentation of results.

Export the results in a variety of formats for reporting and further action.

Figure: The Trace Studio, initialized to a ready state

Save traces for instant recall using the same tracing criteria on up-to-the-moment data in JIRA.

Visualization of trace results including issues and their relations.

Context-specific Traces

Vivid Trace provides traces in various contexts throughout JIRA such as in individual issues and at the project level. This section details each of these contexts.

Issue Context Traces

The issue context trace displays an issue relation graph for the current issue, according to its associated project configuration. You can access the issue relation graph for a specific JIRA issue wherever issue pages are regularly displayed in JIRA, including in the issue browser and in the Issue Navigator. You can configure the project to display traces as issue panels or issue activity tabs, and to restrict visibility of traces to certain people.

Note that the graph might not automatically refresh when performing certain issue operations, such as manipulating issue watchers or voters.

The issue relation graph is in the Trace section, accessible when viewing an issue.
Click this section header to alternately hide or reveal the graph. While hidden, graphs won't be shown, improving page load performance.

Bring the graph as-is into the Trace Studio to conduct further inquiry, export the graph, or save the trace for future recall.

Figure: The Issue Relation Graph within JIRA issue views

Instantly refresh the graph in real-time, avoiding the need to reload the entire issue page.

Change your personal graphing options, perform actions with all issues in the graph, or configure graphs for the project. See Context Trace Menu below.

Context Trace Menu

A context trace menu accompanies contextual issue relation graphs. This menu contains options for changing your personal graphing options, actions that operate on the graph as a whole, and an entry point to the project configuration.

Click or tap the drop-down button to reveal the context trace menu.

Figure: Contextual menu attached to context traces
DistanceRestricts tracing of issue relations to a maximum distance of N issues away from the issues in context.US
Show relationship labelsWhen enabled, the names of the relationships are written on the lines that relate given issues. For issue link relations the outward label is used. Overlapping relations are denoted using the nomenclature +n to indicate that, in addition to the labeled relation, n further relations exist between the two issues.US
List issuesProduces a list of issue search results in JIRA's Issue Navigator as an advanced JQL search query translated from the current trace. Essentially, it allows you to bring a graph into the Issue Navigator and manage the set of connected issues as a larger, singular unit. For example, you can view the issues in list form with a desired field view configuration, reuse the JQL query as a starting point for further investigation or discovery, or efficiently perform further processing with your other tools. The search results might differ from the issues appearing in the graph if the underlying issue and relation information has changed since the graph was generated. Note that no ordering is specified in the listed issues.
Bulk change issuesPerform bulk operations on the issues produced from running the same trace on current JIRA data.
Configure projectConfigure the issue link type enablements and issue field layout for contextual traces within this project.PS
PSProject Settings apply to contextual traces anywhere within the associated project.
USUser Settings are personal choices. Such settings can potentially override graph settings, project settings, and system settings. User settings are stored in JIRA or within the web browser in use.

Project Context Traces

You can also see traces for an entire project. The graph depicts all issues associated with the project, including their out-of-project relations, according to the project configuration.

View the issue relation graph for the project by selecting Trace from the project navigation sidebar.

Figure: Per-project, per-component, and per-version issue relation graph views

The Project Context Trace section. The trace depicted here is actual trace data from Vivid Trace's own development project.

If you are using JIRA version 6.3, the project components and project versions sections have their own contextual trace panels. Note that these project component and version section features were removed from the JIRA product in JIRA 6.4. No matter your version of JIRA, project components and versions are traceable using an appropriate JQL query as the seed issues criteria in the Trace Studio such as project = "Surface FSS" AND component = "ceramic shell"

JIRA Agile and JIRA Software Context Traces

Issue context traces can be shown as an issue quickview section within JIRA Software boards. Traces are generated according to the project configuration associated with the given issue. This feature has the potential to slow down board operations such as drag and drop and is therefore disabled by default. To enable it system-wide, follow the instructions in Add-on Administration.

Figure: Contextual trace in the JIRA Software quickview.

Project Configurations

The contextual issue, project, project component (JIRA 6.3 only), and project version (JIRA 6.3 only) views can be customized in each of your projects. Administer Projects permission is required on the project to adjust its configuration. The project configuration determines the information display format for all contextual traces displayed within a JIRA project, and even applies to related issues coming from other projects whose own configurations may differ.

The visibility settings for traces within a project are located in the JIRA project's Project Settings area. These settings are separate from the Issue Field Layout and Issue Link Types project settings accessible from the Context Trace Menu. Use the following procedure to access the visibility settings in the Project Settings area.

  1. Ensure you are granted permission to Administer Projects on the project.
  2. Navigate to the project.
  3. Select Project Settings in the project navigation sidebar. In earlier versions of JIRA, select Administration from the navigation group below the project header. This opens the Summary page in Project settings.
  4. Select Visibility from the Vivid Trace category in the list of configuration sections.

Trace Display Format

Issue-context traces in issue detail pages within the project can be displayed either as a panel or as an activity tab. This setting is situated in the project visibility settings, accessible using the procedure at the start of this section.

Changes made to the project configuration will be immediately visible to all viewers, and do not affect the tracing configurations of other projects.

Figure: Display format options for issue-context traces.

Select your preferred choice of trace display format for issue-context traces.

Visibility of Traces

The Trace Visibility setting is intended as a convenience for selectively limiting the display of contextual traces to specific users, hiding traces from unconcerned users, and generally improving performance.

By default, traces within the context of the project are visible to any viewer of issues in the project. To limit display of traces to specific JIRA security principals and hide traces from everyone else, adjust the membership list by adding specific project roles, groups, and individual users. Traces will not be shown at all when the list is empty, in effect disabling contextual traces for the project. Note that this setting is not a form of security access control; people to whom traces are hidden will still be able to trace issues belonging to the project, subject to security settings.

This setting is situated in the project visibility settings, accessible using the procedure at the start of this section. Changes made to the project configuration will be immediately visible to all viewers, and do not affect the tracing configurations of other projects.

Make traces visible to any viewer of issues within this project. Replaces all other list entries.

Figure: Settings for visibility of contextual traces by project role, group, and users.

Make contextual traces visible to specific JIRA security principals by adding project roles, groups, and individual users to the membership list.

Contextual traces are visible to members of this list. Remove individual entries using the action button.

Issue Field Layout

You can customize what issue information is displayed in the issue relation graphs. When viewing graphs in the context of a certain project, the trace information display will use the layout for that project, even for issues coming from other projects whose project configuration may be different. Issue Fields and Layouts explains usage and details the fields supported by Vivid Trace.

Changes made to the project configuration will be immediately visible to all viewers, and do not affect the tracing configurations of other projects.

Figure: Configure Project menu item Figure: Project Configuration window displaying the Issue Field Layout tab

Issue relation graphs are calculated in part by following issue link relationships between issues. You can customize traces to follow or ignore specific issue link types as desired. When viewing graphs in the context of a certain project, traces will follow relations according to the settings for that project, even for issues coming from other projects whose project configuration may be different. See the Issue Link Types section in the Trace Studio document for information on usage.

Changes made to the project configuration will be immediately visible to all viewers, and do not affect the tracing configurations of other projects.

Figure: Configure Project menu item Figure: Project Issue Relation Graph Configuration dialog open to Issue Link Types tab

The Trace menu is located in the global navigation menu bar at the top of nearly every page within JIRA.

Figure: The global navigation menu bar entry for Vivid Trace.

JQL Functions for Tracing Issue Relationships

Vivid Trace provides a suite of JQL functions for comprehensively tracing issues along their issue link relationships and their parent/sub-task relationships at the aggregate level. Highly customizable, these functions address a wide range of needs, from producing the same list of issues as when viewing an issue relation graph for that same issue, to pinpointing all issues outside of a project that are blocking a release, and much more. The JQL function relations() and its siblings relatesWith(), links(), parents(), and subtasks() are all thoroughly documented in the JQL Reference, along with plenty of example JQL queries modelling real-world situations that you can refer to when writing your own queries.

Figure: Demonstration of the "relations" JQL function

All issues in the issue relation graph can be found with a search using the relations() JQL function. These functions essentially produce the same set of issues as corresponding issue relation graphs but in the form of advanced JQL search results in JIRA's Issue Navigator.

User Account Settings

Figure: Vivid Trace My JIRA Home setting.

Your language setting is accessible in your JIRA account profile.

LanguageChange your language in your JIRA account profile. Note that while Vivid Trace offers many languages, you may need to ask your JIRA administrator to install a JIRA language pack matching your choice of language for the purpose of extending support for that language to JIRA's own user interfaces. Vivid Trace's open translation management system welcomes improvements and new language contributions.US
My JIRA HomeYou can change your JIRA home page to the Trace Studio in Vivid Trace. Having done so, logging in to JIRA will bring you straight to the Trace Studio.US
USUser Settings are personal choices. Such settings can potentially override graph settings, project settings, and system settings. User settings are stored in JIRA or within the web browser in use.