Vivid Trace 2021.1 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. Issues and Issue Link Types are available in the desired projects in support of your process needs. Vivid Trace is installed in Jira, up to date, and properly licensed. 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 Jira languages are installed as required by your team members. Jira site-level default settings are determined, particularly Visibility of Traces in Issue Detail Views. Optionally, other Jira add-ons are also correctly deployed, such as Jira Software and Zephyr for Jira, that provide their issue types 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 issue types available in their projects. 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. Two of the primary methods for installing the Vivid Trace add-on into Jira 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 has been 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 jira-8 variant of the add-on software that will operate only on Jira systems whose major version is 8.

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 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 in Vivid Trace 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 has been re-indexed. For more information on the File Upload method of installation, refer to Installing an app from a file 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 Vivid Trace license purchasing 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.
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 apps 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 Vivid Trace license purchasing 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 "Manage apps" group of Jira Administration.
  2. Access the Vivid and Partner-issued license information page by selecting "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. Also indicates approaching and recent changes to licensing status.
Date purchasedDate that the license was purchased or issued.
SupplierName of the issuer from whom the license was obtained. Can be Vivid, a Vivid Partner, or the Atlassian Marketplace.
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.
License KeyApply, update, or remove license keys supplied by your Vivid Partner.

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 "Manage apps" group of Jira Administration.
  2. Access the add-on configuration page by clicking "Add-on settings" 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.

Here you can change an add-on setting or reset it to its factory default. These add-on settings apply as default settings to all projects, but projects are individually able to override certain settings.

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.

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.

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.

Display Format of Traces in Issue Detail Views

This site default setting controls how traces are displayed in issue detail views, either as an issue panel (the default) or an issue activity tab. Setting this to Issue Activity Tab will have the effect of still displaying traces to viewers (according to Visibility of Traces in Issue Detail Views, but only when each user has intentionally switched the activity tab to Trace. Changing this setting will immediately apply the change across all projects that do not override this setting.

Visibility of Traces in Issue Detail Views

This site default setting controls to whom contextual traces are made visible in issue detail views. By default, contextual traces are visible to All logged-in users, but for system performance or other reasons you may wish to curtail this list here at the site level to a more discriminating list of members. As an example, you could make a best-guess approximation and set default visibility to just (by example) the Developers project role and the Support Desk group. These members would then see contextual traces in issue detail views and everyone else won't. Another deployment configuration option is to remove all members from the list, leaving it empty, and rely on individual projects to determine their own settings. Changing this setting will immediately apply the change across all projects that do not override this setting.

Managing Trace Configurations

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 "Manage apps" group of Jira Administration.
  2. Access the trace configuration management page by clicking "Trace configurations" in the "Vivid Trace Configuration" menu section.

Inspect a trace configuration's metadata or change its name.

Figure: Vivid Trace Configuration page in Jira administration.

Comprehensive list of all trace configurations in your Jira system.

Modify sharing permissions, useful for surgically re-establishing ownership or revivifying older traces.

Additional Languages

Vivid Trace provides language localizations that complement the localizations bundled with your Jira system. 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 have Jira accommodate your language needs, take the following actions.

Add Jira Language Packs: Install additional language packs from the Atlassian Marketplace.

Configure 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 Find a Vivid 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

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 in the future. 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

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 configurations that specify projects by their project keys 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.