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
• Deployment Readiness Checklist
• Installing the Add-On into Jira
• Accessing Add-On Management
• Licensing
• Configuring the Add-On
• Managing Trace Configurations
• Additional Languages
• Updating the Add-On
• Uninstalling the Add-On from Jira
• Backup and Restore
• Supplementary Topics
• Limitations
• Getting Support

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.

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:

• Installing the add-on through the Atlassian Marketplace, and
• Manually installing a specific version of the add-on software through File Upload.

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.

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.

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.

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

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
• Managing a License Issued by Vivid or a Vivid Partner
• Managing a License Issued by the Atlassian Marketplace

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.

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

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.

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.

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.

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:

• Computation becomes unacceptably resource intensive on your Jira server infrastructure.
• Web browser performance drops to unacceptable levels when displaying issue relation graphs. Possibly attributable to lesser computing resources (slower processors, constrained RAM, older software).

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

• Investigating the need for issue relation graphs of such magnitudes. For example, changing issue relation graph settings in certain projects to trim down issue relation graphs but still be effective in their use cases (possibly even improving signal-to-noise), and building awareness of the project settings feature among users.
• Using a faster web browser or upgrading its hardware.
• Scaling up the computational resources of the Jira server infrastructure.

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.

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.

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.