Documentation for non-current version Vivid Trace 1.4.

Go to current release Vivid Trace 2021.1

End of support

Vivid Trace 1.4 Confluence Integration

Along with project information managed in Atlassian Jira, teams manage entire galaxies of documents in Atlassian Confluence: Releases, requirements, implementation and work breakdown structures, 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 saved traces from Jira and embed them into your Confluence pages so that you can visualize this issue and relation information.

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

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

Note: This release of Vivid Trace for Confluence 1.4.4 has limitations and security considerations; please review them carefully before continuing. It is meant to satisfy use cases where security isn't a primary factor. This release is a fledgling incarnation of a full-featured general solution scheduled for the forthcoming 2021.1 release, and is in part a sounding board for your input on how you'd like it to evolve.

Limitations and Security Considerations

Vivid Trace 1.4 doesn't have the ability to share saved traces with other people, giving rise to the following limitations and security considerations. All of these limitations are scheduled to be resolved in the forthcoming Vivid Trace 2021.1 that does feature the ability to share saved traces. With that release, you'll be able to both embed and/or view any saved trace accessible to you while security is fully enforced.

Restricted Selection of Saved Traces: Only you can insert saved traces that you created in Jira. You can not select and insert saved traces created by others. To insert a saved trace owned by someone else, have that person use the Trace macro to insert the desired trace into the page.

Weakened Permissions Enforcement: A given trace is run as the person who created that trace in Jira. The resulting graphs are displayed to anyone with permission to view the Confluence page, regardless of whether they have permission to see the graphed information in Jira or not. Keep this security consideration in mind as traces expose issue information according to the security priviliges of its owner.

Only One Trace per Page: This release of the Trace macro was designed to be inserted only once per page. Multiple Trace macros embedded in the same page will likely fail to render properly.

Display Locale: Graphs are displayed using the current locale of the Jira account belonging to the person that owns and inserted the graph.

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 will overflow.

Application Link Events: Changes to or deletions of Application Links are partially ignored. Such events might cause subsequent viewings of affected embedded traces to fail to render and even fail to display appropriate messages to help you resolve problem.

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. Keep in mind that for this release you can only insert traces that you created in Jira (as in Limitations and Security Considerations above), one per page.

Starting with having some saved traces prepared in the Trace Studio in Jira, use the following steps to embed a saved trace into a Confluence page.

  1. While editing a Confluence page, position the cursor at the desired insertion point.
  2. Select "Other macros" from the Insert More Content drop-down menu in the editing toolbar.
  3. Locate and select "Trace" from the list of macros.
  4. In the "Insert a Trace" dialog, select the Saved Trace you want to embed.
    Figure: The Insert a Trace dialog for the Trace macro.

    List of saved traces, aggregated from all Jiras connected by application links.
    Click or tap a saved trace to select it. The currently selected trace is in bold.

    Inserts the selected saved trace into the page.

    Selecting a trace from the list of saved traces. If the list of saved traces is empty, save a trace in the Trace Studio in Jira first and then come back to Confluence to insert it.

  5. Click the Insert button to insert the selected saved trace into the page and return to page editing mode.
  6. After the trace has been inserted into the page and you are finished editing, save the page to view the resulting saved trace.
Figure: Manually uploading the Vivid Trace add-on to Jira

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

Note that if the saved trace is deleted from the Trace Studio in Jira, the Application Link is changed or deleted, or network or service conditions are temporarily disrupted, you may see a message in place of the graph describing the problem; See (as in 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.

  1. Use the Jira Issue macro while editing a page in Confluence. The macro settings window will appear.
  2. Input a JQL query into the search field to trace issues of interest using one of the functions from the relations() JQL function suite.
  3. 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

Installation and Support

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

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.

The Trace macro accesses saved 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. Note that Vivid Trace for Confluence has only been tested in the case where both Confluence and Jira have the same set of users and usernames and the relevent application link is configured as so (referred to as "OAuth Impersonation.")

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

  1. Log in to Confluence with System Administrator permissions.
  2. Navigate to the "Application Links" administration page within Confluence.
  3. Enter the base URL of a Jira Server instance and then click "Create new link".
  4. In the application link configuration dialog, enable the option labelled "The servers have the same set of users and usernames."
  5. Continue the configuration process to establish the application link to Jira.
Figure: Configuring the Application Link to Jira with OAuth Impersonation enabled

Vivid Trace has only been tested in the case where both Confluence and Jira have the same set of users and usernames and an Application Link to Jira is established to this effect by enabling OAuth Impersonation as demonstrated in this figure.