Documentation for non-current version Vivid Trace 1.3.
See documentation for the current release Vivid Trace 2021.1

Vivid Trace 1.3 Add-on Administration

This document discusses how to administer the Vivid Trace add-on for JIRA. This document covers the following topics:

System Requirements and Compatibility

Refer to the Specifications for information on the supported editions, versions, and feature configurations of Atlassian JIRA, including supported browsers and devices as well as integrations with third-party JIRA add-ons.

Deployment Readiness Checklist

Use this checklist to streamline the process of introducing Vivid Trace into your organization. If you would like assistance, contact Vivid Support.

  • Administrators of JIRA Administrators know how to control enablement of and how to diagnose & remediate problems concerning Issue Types, Sub-Tasks, and Issue Linking, as well as how to configure them for use in projects. Administrators are aware of the Vivid Trace product documentation, are familiar with the Add-on Administration material & relevant Release Notes and how to obtain product support from Vivid.
  • JIRA System Your JIRA system satisfies Vivid Trace's System Requirements and Compatibility. Both the Issue Linking and Sub-Tasks features are enabled in JIRA according to your needs, and the users of Vivid Trace have the necessary JIRA permissions to make use of these features. Tasks, Sub-Tasks, and Issue Link Types are available in the desired projects in support of your process needs. Vivid Trace is installed in JIRA, is properly licensed, and is up to date. JIRA has been re-indexed. The Vivid Trace add-on configuration doesn't report any error conditions, and any warnings have been handled adequately. Optionally, other JIRA add-ons are also correctly deployed, such as JIRA Agile and Zephyr for JIRA, that provide their own Task, Sub-Task, and/or Issue Link Types to more richly support your processes.
  • Organizational Processes Stakeholders are aware of Vivid Trace's visualization and traceability capabilities, and processes are ready to start leveraging these capabilities. Stakeholders have confirmed that the required issue types, sub-task types, and issue link types are available for use in projects as necessary.
  • Users of JIRA Users know the appropriate uses for each of the available issue types. Users are aware of the available sub-tasks, and are familiar with the features associated with them. Users know how to use issue links appropriately, can differentiate between the available types of issue links, and are cognizant of the potential impact that errors in issue link direction can have on decision making (For example, "blocks" versus "is blocked by"). Devices and web browsers used to interact with JIRA satisfy Vivid Trace's System Requirements and Compatibility.

Print this checklist...

Installing the Vivid Trace Add-On in JIRA

Vivid Trace is packaged as an add-on for JIRA and is distributed through the Atlassian Marketplace. Use the following procedure to install the Vivid Trace add-on in JIRA.

  1. Ensure you are logged in to JIRA with System Administrator permissions.
  2. Navigate to the "Find new add-ons" administration page within JIRA.
  3. Search the marketplace for Vivid Trace, and when you have identified Vivid Trace in the search results, click either "Free trial" to begin a new trial or "Buy now" to purchase a license. Vivid Trace begins to download.
  4. After logging into to My Atlassian, enter your information and click "Generate license" followed by "Apply license." If you're using an older version of UPM, you can copy and paste the license key into your JIRA instance.
  5. Re-index JIRA. JIRA version 5.1 instances will be unavailable while re-indexing is taking place, but with JIRA instances whose version is 5.2 or newer you can choose Background Indexing with no disruption to availability.
Figure: Atlassian Marketplace search results for the search term "vivid trace"

Install Vivid Trace by selecting either "Free trial" or "Buy now" and following the directions.

Vivid Trace is ready for use when installed and registered with a valid license, and JIRA is re-indexed. Licenses are obtained through the Atlassian Marketplace as part of the free trial and purchasing processes. For more information on installation, refer to Installing Marketplace apps in the JIRA documentation.

Installing a Specific Version by File Upload

Vivid Trace can also be installed by first downloading a Vivid Trace product JAR or OBR file and then uploading that to JIRA. A previous version of Vivid Trace can be installed using this method.

  1. Download the desired version of the Vivid Trace JAR or OBR file from either the Vivid Trace Downloads or from the Atlassian Marketplace Version History.
  2. Confirm the file size and SHA hashes of the downloaded file according to the information provided on the download page. This information is available on the Vivid Trace Downloads page.
  3. Ensure you are logged in to JIRA with System Administrator permissions.
  4. Navigate to the "Manage new add-ons" administration page within JIRA.
  5. Select the downloaded file and upload it into JIRA by selecting "Upload add-on" and following the prompts.
  6. After the add-on installs, obtain a license for Vivid Trace from My Atlassian and apply it to the product's entry in the list of User-installed add-ons.
  7. Re-index JIRA. JIRA version 5.1 instances will be unavailable while re-indexing is taking place, but with JIRA instances whose version is 5.2 or newer you can choose Background Indexing with no disruption to availability.
Figure: Manually uploading the Vivid Trace add-on to JIRA

After downloading the desired version of the JAR file, upload Vivid Trace into JIRA by selecting "Upload add-on" and following the directions.

Vivid Trace is ready for use when registered with a valid license. Licenses are obtained through the Atlassian Marketplace as part of the free trial and purchasing processes. For more information on installation, refer to Installing an app from a file in the JIRA documentation.

Managing the Add-On

Add-on licensing and version information can be confirmed in Add-on Management. Also, operations that affect the add-on as a whole can be performed here. Use the following procedure to access the add-on management page.

  1. Ensure you are logged in to JIRA with System Administrator permissions.
  2. Navigate to the "Manage add-ons" administration page within JIRA.
  3. Expand the Vivid Trace entry within the list of User-installed add-ons.

Configure Vivid Trace add-on settings.

Buy Vivid Trace directly from the Atlassian Marketplace. Appears when the add-on is not configured with a purchased license key.

Uninstall the add-on from your JIRA system.

Figure: Managing the Vivid Trace add-on in JIRA

Confirm add-on and license details, and update the license key.

View the documentation and support options.

For more information on handling add-ons, refer to Viewing installed apps Managing purchased add-ons in the JIRA documentation.

Updating the Add-On

If a newer version of the Vivid Trace add-on is available on the Atlassian Marketplace, the add-on management user interface will highlight that fact and feature an "Update" button that allows you to perform the add-on update process directly in your JIRA system. After the add-on update process finishes and you re-index JIRA, the new release will be immediately available to all users.

Although the process of updating the add-on itself is a matter of pressing the "Update" button and re-indexing JIRA, Vivid strongly advises that you first carefully confirm the Release Notes to identify any issues that might impact your organization. If the proposed update to Vivid Trace is several releases newer than your installed version, please take care to also confirm the Release Notes of all intervening versions.

Confirm the nature of the proposed available, newer version.

Update the add-on directly within your JIRA system.

Figure: Managing the Vivid Trace add-on in JIRA

Identify the installed and available versions.

Vivid Trace's Custom Field

Vivid Trace utilizes a custom field. On JIRA version 5.2 and newer, this field is locked to prevent it from being changed.

Figure: The correct configuration of Vivid Trace's custom field.

JIRA 5.1 Caution: This custom field is not lockable on JIRA 5.1. It is unlocked and vulnerable to modification. Vivid recommends taking steps to prevent it from being changed.

Correct configuration of Vivid Trace's custom field. If this field is at all changed, Vivid Trace will malfunction, and in catastrophic cases, appear to function correctly while delivering misinformation to users. If in the event this field needs to be restored to its shipping configuration, you can either disable then re-enable or uninstall then re-install Vivid Trace.

Configuring the Add-On

The Vivid Trace add-on can be configured from within JIRA's administration system. Use the following procedure to view the configuration settings.

  1. Ensure you are logged in to JIRA with System Administrator permissions.
  2. Navigate to the "Manage add-ons" administration page within JIRA.
  3. Expand the Vivid Trace entry within the list of User-installed add-ons.
  4. Click or tap the Configure button to view the add-on configuration page.

Pay heed to any errors and warnings that appear in the configuration page. These messages indicate conditions where add-on functionality is degraded or disabled, and need to be addressed before full functionality can be restored.

The following sub-sections explain Vivid Trace's configurable add-on settings.

Issue Count Soft Maximum

This is an advanced setting. If you are not certain that you understand the potentially deleterious effects of adjusting this setting, we recommend leaving this setting at its default of 1000.

The Issue Count Soft Maximum is a breaker-switch that limits the number of issues fetched and displayed in individual issue relation graphs, balancing available compute power with the need to display issue relation graphs in their entirety. This setting takes effect immediately whenever updated and affects all projects. Graphs truncated due to this limit are accompanied by warning VTW-6.

Warning VTW-6 that accompanies truncated issue relation graphs due to the Issue Count Soft Maximum

Warning message that accompanies issue relation graphs when the quantity of issues displayed in the graph is limited to the Issue Count Soft Maximum.

Technically, issue relation graph computation resource utilization increases in proportion to the connectedness of issues. JIRA server infrastructure is used to compute issue relation graphs, and web browsers are used to layout and display the graphs. Given this combination of quantity of issues involved, compute power, and frequency of use, if you have a need to reduce computational resource intensiveness or are finding that issue relation graphs are being unacceptably truncated, the Issue Count Soft Maximum can be adjusted.

Reducing the soft maximum increases the likelihood that issue link graphs will be truncated, presenting misleading and inconsistent information liable to negatively impact your organization's decision making processes. Extreme limits, such as 20, might nullify the value of issue relation graphs altogether. For these reasons, it may be wise to deem reducing the soft maximum as an interim solution.

Indications that the Issue Count Soft Maximum may need to be decreased:

Solutions that address the root cause and enable the Issue Count Soft Maximum setting to be restored include:

The Issue Count Soft Maximum may need to be increased if graphs are being unacceptably truncated. Increasing this setting can potentially cause increased server utilization.

Limitations

Downgrading the Vivid Trace Add-on: Vivid Trace is backward compatible with add-on data created by prior releases, but is not forward compatible with add-on data created by newer releases. Re-installing Vivid Trace with an older release ("downgrading") may lead to undefined & unsupported behavior, particularly with features that utilize add-on data.

Issue Linking and Parent/Sub-task Features: It is possible for JIRA to store issue links and sub-task issue data even while the respective features are disabled. Vivid Trace's behavior is unspecified when used in conjunction with such disabled features.

JIRA Project Key Format: The JQL functions in Vivid Trace are designed to recognize project keys that conform to JIRA's customisable supported project key format. If a given key is not recognized, investigate whether it and your JIRA system's project key format setting conform to JIRA's supported project key format. If the project key is found to be non-conforming, it will need to be corrected before the JQL functions can recognize it.

Renaming JIRA Project Keys: In the event a project key is changed in JIRA, the corresponding Vivid Trace project configuration will follow the change, associating with both the old and new project keys. Note however that although JIRA is able to reimport a JIRA project under an updated key and thereby lose notion of any prior keys, how the Vivid Trace project configuration will associate is unspecified.

Getting Support

To view support options, you can visit Vivid Support directly, or starting in JIRA from the add-on management page follow the "Support and issues" link. Support via email is available to people who provide the add-on "License SEN" information as supplied by Atlassian and that we can verify. If you are planning for your help desk or other people to directly contact Vivid Support, their support experience will be more efficient if that license information is shared with them for inclusion in their support requests. The terms of support are fully detailed on the Vivid Support website.

Uninstalling the Add-On from JIRA

There is no product lock-in, only added value. If you no longer need the benefits of managing work at higher levels, visibility into your work processes, or effortless reporting, use the following procedure to uninstall the Vivid Trace add-on from JIRA.

  1. Ensure you are logged in to JIRA with System Administrator permissions.
  2. Navigate to the "Manage add-ons" administration page within JIRA.
  3. Expand the Vivid Trace entry within the list of User-installed add-ons.
  4. Click the Uninstall button and follow the directions to complete the uninstall process.

Vivid Trace can be easily reinstalled at a later time by following the installation instructions in this document. For more information, refer to Uninstalling apps in the JIRA documentation.