Vivid Trace 2025.1 Atlassian 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 the optional Vivid Trace for Confluence allows you to add traces to your Confluence pages, sourced live from Jira.

Embedded traces automate the 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 usage of Vivid Trace for Confluence:

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.

  1. While editing a Confluence page, position the cursor at the desired insertion point.
  2. Select "Trace" from the Insert More Content drop-down menu in the editing toolbar.
  3. 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 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.

  4. Click the Insert button to insert the selected trace configuration into the page and return to page editing mode.
  5. 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 in the Administration reference for more information.

How to List relations() JQL Function 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. Insert 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 using the relations() suite of JQL functions of Vivid Trace.