Vivid Trace 2021.1 Confluence Integration

Along with project 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 your Confluence pages.

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 data in an accurate, customizable 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 2021.1 has limitations and security considerations; please review them carefully before continuing.

Limitations and Security Considerations

Sharing Permissions of Trace Configurations: You can insert any trace configuration that you have access to at that time. Other viewers of the page may or may not have permission to view the trace.

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 privileges 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 / web browser view 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 a trace configuration must give you at least Viewer permission to be able to embed it. You can only insert one trace per page (as per Limitations and Security Considerations).

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.

  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 trace configuration you want to embed.
    Figure: The Insert a Trace dialog for the Trace macro.

    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 in bold.

    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.

  5. Click the Insert button to insert the selected trace configuration 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 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.

  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:


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