Vivid Trace 1.4 Add-on Administration

This document discusses how to administer the Vivid Trace add-on for JIRA, addressing the entire deployment life cycle. 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 and 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 and 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. Additional languages are enabled by JIRA language pack add-ons. Optionally, other JIRA add-ons are also correctly deployed, such as JIRA Agile / JIRA Software and Zephyr for JIRA, that provide their own task, sub-task, and 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.

Installing the Vivid Trace Add-On into JIRA

Vivid Trace is packaged as an add-on for JIRA. While there are other methods for installing add-ons into JIRA Server, two primary methods are detailed here:

Note that the method used to install the add-on is independent of how the add-on is licensed, as detailed in Licensing the Add-On.

Installing the Add-On Through the Atlassian Marketplace

Use the following procedure to install the Vivid Trace add-on software into JIRA through the Atlassian Marketplace.

  1. Log 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 identify Vivid Trace in the search results.
  4. JIRA might prompt you for product licensing; see Licensing the Add-On for more information.
  5. Re-index JIRA. If you wish to perform the re-index without disrupting JIRA availability, choose Background Indexing.

Search for vivid trace in the Atlassian Marketplace.

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.

After completing the installation procedure, Vivid Trace will need to be configured with a valid license. Vivid Trace is ready for use when the add-on software is installed, registered with a valid license, and JIRA is re-indexed.

Manually Installing a Specific Version of the Add-On using File Upload

Vivid Trace can also be installed by first downloading the Vivid Trace add-on software product as a JAR or OBR file and then uploading that file to JIRA.

A previous version of Vivid Trace can be installed using this method. If you are installing a previous version with the intention of downgrading, please be aware of limitations associated with downgrading the add-on.

Ensure that the version you download and install is compatible with your version of JIRA. Some versions of Vivid Trace come in variations, each compatible with a single, specific major version of JIRA. For example, a JIRA7 variant of the add-on software that will operate only on JIRA systems whose major version is 7.

Use the following procedure to manually install a specific version of the add-on using file upload.

  1. Download the desired version of the Vivid Trace JAR or OBR file from either the 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 in Downloads.
  3. Log in to JIRA with System Administrator permissions.
  4. Navigate to the "Manage add-ons" administration page within JIRA.
  5. Click "Upload add-on" and follow the prompts to select the downloaded add-on file and upload it into JIRA for installation.
  6. JIRA might prompt you for product licensing; see Licensing the Add-On for more information.
  7. Re-index JIRA. If you wish to perform the re-index without disrupting JIRA availability, choose Background Indexing.
Figure: Manually uploading the Vivid Trace add-on to JIRA

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

After completing the installation procedure, Vivid Trace will need to be configured with a valid license. Vivid Trace is ready for use when the add-on software is installed, registered with a valid license, and JIRA is re-indexed. For more information on the File Upload method of installation, refer to Installing add-ons by file upload in the JIRA documentation.

Accessing Add-On Management

Operations that affect the add-on as a whole can be performed in Add-On Management. Use the following procedure to access the add-on's management page.

  1. Log 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.

Examine the nature of the proposed update, if available.

Identify the installed version of the add-on, and the newest available version that is compatible with your JIRA system, if available.

Figure: Managing the Vivid Trace add-on in JIRA

When Vivid Trace is configured with an Atlassian Marketplace-issued license, confirm license details here.

Buy nowBuy Vivid Trace directly from the Atlassian Marketplace. Appears when the add-on is not configured with a license issued by the Atlassian Marketplace. For more information, see Purchasing and Support Options.
ConfigureNavigate to the add-on configuration page.
Data security and privacyView the Vivid Data Security and Privacy Notice.
DocumentationView the product documentation.
Marketplace listingView the Vivid Trace product listing on the Atlassian Marketplace.
ModulesList of modules in the add-on. Contains the JIRA Software Quick View Trace Panel feature that is disabled by default.
Support and issuesSee the support information for Vivid Trace registered with the Atlassian Marketplace. This information echoes some of the information available at Vivid Support.
UninstallUninstall the add-on from your JIRA system.
UpdateUpdate the add-on directly within your JIRA system. Appears when a newer version of Vivid Trace than the one installed in your JIRA system is available.
Watch add-onSubscription to receive immediate notifications from the Atlassian Marketplace concerning new releases of the add-on.

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

Licensing

A valid license is required to fully activate Vivid Trace. Licenses are issued by Vivid and Partners and by the Atlassian Marketplace as part of the free trial and purchasing processes. Note that the method for licensing the add-on depends upon the license issuer, and is independent of the method used to install the add-on. For information on licensing terms including pricing, entitlements, special terms for non-profit organizations (NPOs), and the satisfaction guarantee, see Purchasing and Support Options.

License management tasks:

Start a Free Trial During Installation

To install Vivid Trace and start a free trial, use the following procedure.

  1. If you haven't already, start installing Vivid Trace by clicking the Free trial button in the add-on search results. Vivid Trace begins to download and install.
  2. Wait for the download and install process to finish.
  3. Log in with your Atlassian account if prompted.

After installation finishes and you are logged in with your Atlassian account, Vivid Trace will be automatically registered in your JIRA system with a 30 day free trial license issued by the Atlassian Marketplace.

Managing a License Issued by Vivid or a Vivid Partner

If your license was issued by Vivid or a Vivid Partner, then this section applies to you.

To access the Vivid Trace license information and management page, use the following procedure.

  1. As a JIRA administrator, navigate to the Add-ons group of JIRA Administration.
  2. Access the Vivid and Partner-issued license information and management page by clicking "Vivid Trace License" in the Vivid Trace menu section.

Diagnostic summary of add-on licensing status.

Figure: Vivid Trace License Information page in JIRA administration.

Manage the license key for licenses issued by Vivid and Partners.

OrganizationThe end-user organization licensed to use the Vivid Trace add-on software.
StatusSummarizes the license validity and maintenance period. Will indicate approaching or recent changes to licensing status.
Support Entitlement Number (SEN)Displays a VSEN in the case of a Vivid or Partner-issued license, or a SEN in the case of an Atlassian Marketplace-issued license. Please provide this number when contacting Vivid Support or your Partner.
License typeIndicates the applicable add-on product and user tier of the license.
SupplierName of the issuer from whom the license was obtained. Can be Vivid, a Vivid Partner, or the Atlassian Marketplace.
Date purchasedDate that the license was purchased or issued.

Managing a License Issued by the Atlassian Marketplace

If your license was issued by the Atlassian Marketplace, then this section applies to you.

Licenses issued by the Atlassian Marketplace are managed in the Universal Plugin Manager by accessing the Vivid Trace add-on entry using the same management patterns as other paid add-ons available in the Marketplace. For general information, refer to How to Update Your Add-on License in the JIRA documentation.

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. As a JIRA administrator, navigate to the Add-ons group of JIRA administration.
  2. Access the add-on configuration page by clicking "Vivid Trace Configuration" in the Vivid Trace menu section.

Definitive technical information about the version of the add-on software installed in your JIRA system.

Direct access to various administrative resources.

Figure: Vivid Trace Configuration page in JIRA administration.

Change an add-on setting or reset it to its factory default.

Pay heed to any errors and warning messages that appear in the configuration page. These messages will 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 issues.

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.

This graph is incomplete, and might be misleading or inconsistent.
VTW-6: Limiting quantity of displayed issues to the Issue Count Soft Maximum of 1000.

Warning message VTW-6 that accompanies issue relation graphs when the quantity of issues displayed in the graph has been 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.

Graph Traversal Time Limit

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 3 seconds.

The Graph Traversal Time Limit is an execution guard that terminates long-running queries in order to cap the processing load of your JIRA server system. It functions by limiting the amount of wall-clock time JIRA spends traversing and accumulating information on each issue relation graph query, no matter how idle or busy JIRA is. If issue relation graphs take longer than desirable to appear or results are being truncated more frequently than desirable, you can adjust the graph traversal time limit. Reducing the time limit increases the likelihood that issue relation graphs will be truncated, accompanied by warning VTW-15.

This graph is incomplete, and might be misleading or inconsistent.
VTW-15: Displaying portion of graph that was discovered within the Graph Traversal Time Limit of 3 seconds.

Warning message VTW-15 that accompanies issue relation graphs when processing was abruptly ended due to being capped by the Graph Traversal Time Limit.

Additional Languages

Multi-cultural teams are becoming more common, and JIRA's support for multiple languages enhances its viability as a practical solution. Vivid Trace provides languages that complement the languages bundled with your JIRA system plus many more. Refer to the Specifications for the full list of language localizations in Vivid Trace and their degrees of completeness.

Users can personalise their accounts to use JIRA in their preferred language. But, without adding language packs to JIRA, users who have set their preferred language to a language not bundled with JIRA might see the non-Vivid Trace parts of JIRA in a different and potentially unintelligible language. To position your JIRA system along your language needs, take the following actions.

Add JIRA Language Packs: Atlassian offers several methods for adding languages to JIRA: Install language packs from the Atlassian Marketplace, and download and install user community-derived language packs from Atlassian Translations.

Choose JIRA's Default Language: Set JIRA's default language setting to a sensible choice of site-wide fall-back language.

Inform Users About the Account Language Setting: Inform users about the procedure for setting their preferred language.

Note that other add-ons may or may not offer localizations for your language choices.

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 accompanying 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.

To update the Vivid Trace add-on, use the following procedure.

  1. Access the Vivid Trace add-on entry in JIRA's add-on management page.
  2. Identify the currently installed version, the available version, and the applicable Release Notes.
  3. When you are ready, click the entry's Update button. The available version of Vivid Trace begins to download. Observe the add-on download and update process through to successful completion.
  4. Re-index JIRA. If you wish to perform the re-index without disrupting JIRA availability, choose Background Indexing.

After completing the update procedure, briefly confirm correct operation of Vivid Trace and your JIRA system. If you experience a problem resulting from the update that you cannot resolve on your own, please contact Vivid Support or your Partner. In the event interim measures need to be taken for emergency situations until a satisfactory resolution can be achieved, options include disabling the add-on, and re-installing the older, known-good version of the add-on ("downgrading").

Uninstalling the Add-On from JIRA

There is no product lock-in, only added value. If you no longer need the benefits of Vivid Trace, use the following procedure to uninstall the Vivid Trace add-on from JIRA.

  1. Access the Vivid Trace add-on entry in JIRA's add-on management page.
  2. Click the entry's Uninstall button and follow the directions to complete the add-on uninstall process.

After uninstallation, your Vivid Trace data will remain in JIRA, and will be available should the add-on be re-installed. Vivid Trace can be easily reinstalled at a later time by following the installation instructions in this document. For more information, refer to Uninstalling add-ons in the JIRA documentation.

Backup and Restore

For complete backup and recovery of the Vivid Trace add-on software, the only aspect that needs to be subjected to your backup procedures is the add-on data, which is stored in JIRA's database. JIRA supports two methods for backing up database contents: Native database backup tools, and JIRA's XML backup utility. Both of these methods backup and restore the add-on's data along with JIRA's own data. If you already have JIRA backup procedures in place using either of these supported methods, then Vivid Trace's data will automatically be folded into JIRA's own backups, with no additional work on your behalf.

Technically, the add-on stores all of its data using JIRA's ActiveObjects which in turn stores data in JIRA's SQL database system. Because JIRA's backup and restore system automatically targets add-on data in the ActiveObjects sub-system, all Vivid Trace add-on data is written as a part of JIRA's own process of backing up JIRA data to a backup file, and is automatically restored with JIRA is restored from such a backup file. You can confirm the presence of add-on data in the backup files by scanning the unarchived contents for strings such as (case-insensitive) vivid trace and/or vivid.trace. You can confirm add-on data in a restored system by connecting to JIRA's SQL database system and inspecting add-on data tables whose names are prefixed with the string AO_FF0AC4_, and also by asking individual users whether their data is as they expect.

Supplementary Topics

Enabling JIRA Software Quick View Trace Panel Feature

The Quick View feature, specific to JIRA Agile and JIRA Software, provides a quick and detailed overview of an individual, selected issue within Agile boards. Vivid Trace has the ability to contribute an issue trace panel as an additional panel to the Quick View. However, because this feature has the potential to slow down board operations, such as drag and drop, it is therefore disabled by default. Use the following procedure to enable the issue trace Quick View panel. Enabling this feature will cause the Quick View panel to be available system-wide in JIRA, present in all Agile boards.

  1. Access the Vivid Trace add-on entry in JIRA's add-on management page.
  2. Expand the list of modules within the entry.
  3. Identify the "JIRA Agile Quick View Trace Panel" module within the expanded module list.
  4. Enable the module by clicking its "Enable" button.

After enabling the Quick View Trace Panel, you can confirm that quick views contain contain trace panels by viewing a few issues within Agile boards.

Vivid Trace's Custom Field

Vivid Trace utilizes a custom field. This field is locked to prevent it from being changed.

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

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.

Limitations

Automatic Refresh of Issue Relation Graphs: Graphs do not automatically refresh whenever certain issue fields are manipulated using the inline editing feature, due to lack of on-page update notification support in JIRA. In particular, the Votes and Watchers issue fields are known to not send such notifications.

Changing the System Clock: The Graph Traversal Time Limit mechanism depends upon the notion of the current time as supplied by the operating system. Changing the system clock by significant amounts may affect all in-flight graph requests that Vivid Trace is processing at the moment of change. Those requests might run much longer (if the clock is set backwards) or be abruptly ended (if the clock is set forwards).

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.

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 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. Saved trace criteria that specify projects project key rather than ID will not be automatically updated to reflect project key renamings.

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. If you purchased your license from a Vivid Partner, you can also obtain support from them by contacting them directly. Support via email is available to people who provide the add-on "License SEN" information as supplied by Atlassian or the "License VSEN" information as supplied by your Vivid Partner 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.