Vivid Trace 1.4 Trace Studio
Accessible from nearly everywhere in Jira, the Trace Studio is a fundamental feature of Vivid Trace. With it, you can visualize related issues, produce traceability reports, conduct change impact analysis, ascertain compliance, and much more. Its premise is to place the full power of Vivid Trace into your hands to trace issues and their relations over the entirety of your Jira system while benefiting from its data-centric operation, rapid feedback cycle, and outcome-driven design. 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. This document explains how to use the Trace Studio in terms of these outcomes.
Prerequisites: Familiarity with Issue Relation Graphs. Some knowledge of JQL, Atlassian's Jira Query Language for filtering issues.
At Vivid's Concierge Service you can schedule a walk-through of the Trace Studio and any other aspect of Vivid Trace (free of charge).
Quickstart
This section helps orient you to the Trace Studio's user interface, guiding you towards self-proficiency. Approximate time required: 10 minutes.
- Go to the Trace Studio within Jira to begin a new tracing session. Select "Trace" from the global navigation menu bar at the top of the Jira page, and then select "Trace issues".
- Input seed issues criteria into the Relations Parameters. The seed issues specify which issues to start tracing from. Use either a valid JQL statement or a list of issue keys.Here are some ideas for use as starting points:
project = "CRM Connector" AND fixVersion = "1.2.3"A release version in one of your projectspriority = HighestRelease blockerscomponent = "Memory cache"A particular project componentvotes >= 50Highly-voted issuesproject = ABC AND fixVersion = "1.2.3" AND issueType = RequirementRequirements satisfaction for a releaseduedate >= 6m AND resolution IS EMPTYUnresolved issues long-past due datefilter = "Tier 2 escalations"Issues in a saved filterproject = ABC AND issueType = Epic AND resolution IS EMPTYUnfinished epics in a projectassignee = currentUser() AND resolution IS EMPTYUnfinished issues assigned to youduedate <= 1wIssues due around nowABC-123, ABC-127Any number of issue keys of issues of interest, such as for blockers, epics, or sub-tasks (separated with spaces and/or commas)project IS NOT EMPTY
- After inputing the seed issues criteria (and with your cursor still in the Seed issues field) press the Enter key to run the trace. The issue relation graph appears dimmed while the trace executes.
- When the trace completes, an issue relation graph appears with the results of your trace. Inspect the results. Do you recognize some of the issues and their relations in the graph?
You can adjust your seed issues query, pressing Enter after each adjustment to re-run the trace. Note that if the seed issues don't have issue links or parent/sub-task relations, or there are no issues in Jira for you to access, the trace results won't be impressive and the value of the Trace Studio won't be apparent.
Now let's experiment with the Trace Studio's iterative, rapid-feedback approach to developing traces and inspecting data while reducing your cycle time. This process will be more meaningful if you have a specific goal in mind.
Experiment with trace configuration settings. In Relations Parameters, try setting the distance to 0 (zero) and then slowly incrementing it one-by-one to better grasp how distance works. You can graph the exact results of JQL queries by setting the distance to 0. Adjust some Display Options to influence how the results are graphed and arranged. Add fields to the Issue Field Layout to produce more information about the issues in the results, such as the Summary field. Try disabling irrelevant types in Issue Link Types to improve signal-to-noise in the graph.
To save your trace: If you've made a trace you'd like to refer to later, save it by selecting "Save as" in the Current Trace and providing a name for the trace. The saved trace appears in the list of Saved Traces. You can confirm that the saved trace has been properly saved by starting a New trace to re-initialize the Trace Studio and then selecting your saved trace to load it back into the Trace Studio.
To export the trace results, use the Export button in the Toolbar to export the graph in the file format of your choice. A file will be downloaded. Locate the downloaded file, and open it to inspect the results. The selection of file formats enjoys wide-spread compatibility with other software and services meaning that exported files can be used as you see fit, such as to be embedded in other documents like Microsoft Excel spreadsheets and Word documents, or sent to other people.
At this point, hopefully you have a sense for what you can accomplish with the Trace Studio. As you gain proficiency, it all comes down to asking the right questions through the seed issues and the other tracing criteria, and in designing the information display of the results.
User Interface
This section provides an overview of the Trace Studio user interface and then proceeds to detail each of its constituent parts. The user interface is composed of several panels and toolbars that surround a results panel. The results displays the issues and relations of your current trace results as an issue relation graph. This overview is interactive: click, tap, or hover the mouse to focus on specific parts of the user interface.
| Saved Traces | Instantly recall and execute saved trace configurations on current Jira data, and manage saved traces. |
|---|---|
| Current Trace | Indicates the currently active trace and provides means to save and update named trace configurations for future recall. |
| Toolbar | Provides features for operating on the trace as a whole and for generating reports from the graphed results. |
| Relations Parameters | Specify which issues to start tracing from and how the trace should proceed. |
| Display Options | Control arrangement and appearance of issues and relations in the trace results. |
| Issue Field Layout | Design the issue field information that appears in issue lozenges in the resulting graph. |
| Issue Link Types | Control which issue link types are followed and ignored during tracing. |
| Issue Relation Graph | Results of the most recent successful run of the current trace, represented as a graph of issues and their relationships. |
Saved Traces
Click to alternatingly hide and reveal the Saved Traces side panel to increase viewing space and reduce distraction.
Click to reveal a menu of operations for a saved trace.
Select a saved trace to load it.
Instantly recall and execute saved trace configurations on current Jira data, and manage saved traces.
| New trace | Reinitialize the trace studio and start a new trace, discarding any unsaved changes. |
|---|---|
| Rename | Change the name of the saved trace. |
| Duplicate | Copies all settings of the saved trace, making a duplicate of it under a new name. |
| Delete | Permanently delete the saved trace. |
Once created, traces can be saved for later recall, allowing you to regenerate the trace with its particular settings but executing on current Jira data. These saved traces are listed in the Saved Traces column. Loading a saved trace, by clicking or tapping it, sets it as the active trace in the Trace Studio. The current trace session is discarded and the loaded trace immediately executed.
Saved traces are susceptible to changes in the various Jira objects used in their trace configuration. If those objects change in name, or are deleted, then recalling affected traces might result in missing information, misleading results, or errors. Examples of such objects includes referring to custom fields and projects by name in the seed issues criteria. For this reason, we recommend that you confirm the validity of the trace configuration and examine any warning and error messages whenever the trace results are important. Alternatively, you can consider the use of object IDs as reckoned by Jira, which trade readability for stability.
Current Trace
Name of the current trace.
Click to reveal more operations for the current trace.
Indicates that changes have been made to the current trace configuration since it was last saved.
This component indicates the currently active trace and provides means to save and update named trace configurations for future recall.
| Save | Save the current trace configuration. You will be prompted for a name in the case of a new trace. Existing saved traces will be overwritten with the current trace configuration. |
|---|---|
| Save as | Saves the current trace configuration as a new saved trace with the name of your choice. |
| Discard changes | Reloads the current saved trace, discarding any changes made to it since it was last saved. |
Toolbar
Refresh the trace results by re-running the active trace configuration on current Jira data.
Refresh the graph in real-time, and export the trace in a variety of file formats.
| PNG (Portable Network Graphic) | Exports the current trace (issue relation graph) as a raster graphic in the PNG file format. Suitable for viewing and embedding as the PNG standard enjoys near universal compatibility. |
|---|---|
| SVG (Scalable Vector Graphic) | Exports the current trace (issue relation graph) as a vector graphic in the SVG file format. Most graph elements are cleanly scalable to nearly any size. Suitable for viewing and embedding on modern software and devices as support for this standard is gaining wider levels of support (as of 2016). The exported file is completely self-contained, but unlike the trace within Jira, only certain interactive features are included and usable. |
The Export feature requires a web browser that meets certain levels of compliance with web standards. Support for these standards among prevalent web browsers is not uniform, meaning that the quality of exported files might suffer. Vivid Trace makes limited attempts to detect browser support, and in cases where the web browser in use doesn't support specific export formats the associated Export menu items will appear disabled. Concretely, Google Chrome offers the best support, followed by Firefox. Exports are completely unsupported on Apple Safari and Microsoft Internet Explorer.
The export derives its data directly from the trace issue relation graph; the trace is not re-executed.
Perform operations on the graph as a whole.
| List issues | Produces 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. Note that no ordering is specified in the listed issues. |
|---|---|
| Bulk change issues | Perform bulk operations on the issues produced from running the same trace on current Jira data. |
List issues and Bulk change issues find issues not by re-using the issues in the trace results but by executing the same trace configuration on current Jira data. 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.
Relations Parameters
Click the label to alternatingly hide and reveal Relations Parameters.
Press the Enter key to run the trace after inputing or editing the seed issue criteria.
Input a whole number to limit the tracing distance, or select one of the presets.
The Relations Parameters component of the trace configuration specifies which issues to start tracing from and how the tracing process should proceed.
| Seed issues | The seed issues indicate the issues to start tracing from. Accepts a JQL query that produces issues, or one or more issue keys (separated with spaces and/or commas). This setting corresponds respectively to the issue and jql parameters of the relations() suite of JQL functions. |
|---|---|
| Directions | Directions controls which issue relationship directions are followed during the tracing process. Enabling Inward and/or Outward will cause the search to follow inward issue links and/or outward issue links, respectively. Likewise, enabling Parents and/or sub-tasks will cause the search to follow along parent issue and/or sub-task issue relationships, respectively. This setting corresponds to the direction parameter of the relations() suite of JQL functions. |
| Distance | When set to a whole number d, the Distance setting restricts tracing of issue relations to a maximum distance of d issues away from the seed issues in any direction. A value of 0 will prevent searching beyond the seed issues. While this input has focus, use the up & down arrow keys to quickly increment or decrement distance by one. A blank value means unlimited distance.This setting corresponds to the distance parameter of the relations() suite of JQL functions. |
| Include seed issues | Determines whether the seed issues are included in the results. When deselected, seed issues are omitted from the trace results. Chains of related issues that bottleneck through seed issues will be split, potentially orphaning some issues. This setting corresponds to the inclusive parameter of the relations() suite of JQL functions. |
Even if the distance is set to zero (0, meaning "graph only the seed issues"), the graph will show the relations between the traced issues according to the other settings in the trace configuration. This is useful for graphing the exact issues resulting from a JQL query.
The trace is re-run anytime a setting is changed.
Display Options
Click the label to alternatingly hide and reveal Display Options.
The Display Options component of the trace configuration controls arrangement and appearance of issues and relations in the trace results.
| Graph direction | Graphing of related issues proceeds in this direction. Note that changing the graph direction does not change writing direction, and that the contents of the issue relation graph is always left-justified. |
|---|---|
| Group and label orphan issues | Issues that appear in the trace results but have no relations to other graphed issues, according to the trace configuration, are treated as orphan issues. Enabling this setting will group orphans at the bottom of the graph. Orphans will be interspersed with their peers in the graph when this setting is disabled. |
| Show relationship labels | When 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. |
The graph is redrawn whenever a setting is changed.
Issue Field Layout
Click the label to alternatingly hide and reveal Issue Field Layout.
Use the Issue Field Layout component of the trace configuration to design the issue field information that appears in issue lozenges in the trace results.
Issue Fields and Layouts explains usage and details the fields supported by Vivid Trace. Note that all issue fields available to you across all projects in Jira are available in the issue palette. The trace is re-run whenever the layout is changed.
Issue Link Types
Click the label to alternatingly hide and reveal Issue Link Types.
All issue link types in your Jira system are listed here.
Click a checkbox, or anywhere in its row, to toggle the issue link type. Only enabled types are followed and drawn during tracing.
The Issue Link Types component of the trace configuration controls which issue link types are followed and ignored during tracing.
Issue relation graphs are calculated in part by following issue link relationships between issues when the Inward and/or Outward Directions parameters are set in Relations Parameters. Issue link relationships are explained in-depth in Issue Relation Graphs.
Deselect irrelevant and unwanted issue link types to trim them from the trace results. Given the example settings in the figure above, if clone relationships are producing irrelevant noise in your trace results, disable the "Cloners" issue link type. From then on, trace results will be calculated without following clone relationships, resulting in more concise graphs.
The issue link types setting corresponds to the issueLinkType parameter of the relations() suite of JQL functions. The trace is re-executed each time a setting is changed.