Vivid Trace 2021.1 Confluence Integration

Along with information managed in Atlassian Jira, teams manage veritable galaxies of documents in Atlassian Confluence: Release plans, requirements, implementation and work breakdown structures, incident post-mortems, test plans, quality initiatives, and customer satisfaction improvement plans, to name a few. The Trace macro provided by Vivid Trace for Confluence allows you to bring traces from Jira and embed them into these kinds of Confluence pages and more.

Embedded traces automate the busy work of duplicating and maintaining information from related Jira issues, and helps prevent such information in your Confluence content from becoming stale. The concept is similar to Confluence's own Jira Issues macro, but the traces preserve inter-issue relationship context in an accurate, customizable display format that is always up-to-date.

This document explains installation and usage of Vivid Trace for Confluence:

How to Embed a Trace into a Confluence Page
How to List Trace Results in a Confluence Page
Administration of Vivid Trace for Confluence Add-on Software
Limitations and Security Considerations

Note: This release of Vivid Trace for Confluence 2021.1 has limitations and security considerations; please review them carefully before continuing.

How to Embed a Trace into a Confluence Page

Ensure that the Vivid Trace for Confluence add-on software is correctly installed in your Confluence system before starting.

Starting with some trace configurations prepared in the Trace Studio in Jira, use the following steps to embed a trace configuration into a Confluence page. Keep in mind that a trace configuration must grant you at least Viewer permission to be able to select and insert it.

While editing a Confluence page, position the cursor at the desired insertion point.
Select "Trace" from the Insert More Content drop-down menu in the editing toolbar.
In the "Insert a Trace" dialog, select the trace configuration you want to embed.

List of trace configurations, aggregated from all Jiras connected by application links.
Click or tap a trace configuration to select it. The currently selected trace is highlighted.

Inserts the selected trace into the page.

Selecting a trace from the list of traces configurations. If the list of traces is empty, save a trace configuration in the Trace Studio in Jira first and then come back to Confluence to insert it.
Click the Insert button to insert the selected trace configuration into the page and return to page editing mode.
After the trace has been inserted into the page and you are finished editing, save the page to view the resulting embedded trace.

Figure: Manually uploading the Vivid Trace add-on to Jira

The Trace macro, provided by Vivid Trace for Confluence, embeds traces in Confluence pages. Whenever the trace configuration is updated in Jira or the trace results change, those changes are always automatically reflected in the embedded trace.

Note that if the trace configuration is deleted from the Trace Studio in Jira, the page viewer lacks permission to view the trace, the Application Link is changed or deleted, or network or service conditions are temporarily disrupted, in place of the graph you may see a message describing the problem; See Limitations and Security Considerations for special information.

How to List Trace Results in a Confluence Page

This section describes how to list issues from trace results in a Confluence page using the relations() JQL function suite with the Jira Issues macro bundled in Confluence. Ensure that the Vivid Trace for Confluence add-on software is correctly installed in your Confluence system before starting.

Insert the Jira Issue macro while editing a page in Confluence. The macro settings window will appear.
Input a JQL query into the search field to trace issues of interest using one of the functions from the relations() JQL function suite.
Insert the macro into the page.

Should Confluence not report specific JQL errors and warnings, you can use the advanced search in Jira for diagnosing problems with the JQL query. If Confluence misinterprets your JQL query, you might be able to workaround this problem by saving the trace JQL query as a saved filter in Jira with appropriate access permissions, and then referencing the saved filter from the Jira Issue macro search field as follows: filter = Name of saved filter

Figure: Embedding trace results as a list of Jira issues into a Confluence page with the Jira Issues macro

Embedding trace results as a list of Jira issues into a Confluence page by referencing a saved filter in Jira that performs the trace.

Administration of Vivid Trace for Confluence Add-on Software

This section concerns administration of the Vivid Trace for Confluence add-on software:

Requirements

Supports Atlassian Confluence Server version 7.4 and newer.
Confluence must have at least one Application Link established to one or more Jira Server instances.
The Jira system from which trace information is drawn upon must have a supported version of Vivid Trace for Jira (at least version 2021.1) installed that is correctly licensed.

Installation and Support

From an administrative perspective, Vivid Trace for Confluence is different from the Jira variant:

The software is named "Vivid Trace for Confluence" and is packaged as an add-on for Confluence.
This Confluence add-on is free for all Vivid Trace customers to use; no further licensing is involved.
This add-on requires the host Confluence system to have Application Links established to one or more Jira Server instances before its features can be utilized.
This add-on has no configurable settings.
Confluence will experience virtually no increase in processing load or data storage requirements with this add-on deployed.

Search for vivid trace in the Atlassian Marketplace.

Figure: Atlassian Marketplace search results for the search term "vivid trace"

Install Vivid Trace for Confluence by selecting "Install" and following the directions.

Installation, updates, and uninstallation of the Vivid Trace for Confluence add-on software follows the same pattern as for Vivid Trace for Jira.

Refer to Add-on Administration for step-wise administrative procedures that are adaptable to the Vivid Trace for Confluence add-on software as well as for getting support from Vivid or your Vivid Partner.

Establishing an Application Link to Jira

The Trace macro accesses trace information from Vivid Trace for Jira through Application Links. If you don't have any application links to Jira configured, the Trace macro will prompt you to begin the configuration process.

Use the following procedure to create an application link between Confluence and Jira.

Log in to Confluence with System Administrator permissions.
Navigate to the "Application Links" administration page within Confluence.
Enter the base URL of a Jira Server instance and then click "Create new link".
Continue the configuration process to establish the application link to Jira.

Limitations and Security Considerations

Display Width and Page Overflow: Embedded trace graphs do not resize themselves to fit within their context such as on an issue details page in Jira; instead they are displayed at their natural height and width. Graphs wider than the page / web browser view will overflow.

"Jira Issues" Confluence Macro and relations() JQL function: A defect in the Confluence macro Jira Issues prevents the relations() JQL function arguments from being anything other than a single Jira issue key.

Sharing Permissions of Trace Configurations: You can insert any trace configuration that you have access to at that time. Thereafter, who can see the trace and what they can see in the trace are open to change whenever sharing permissions or issue security settings are changed.