Adding the Jira Snapshots Macro to a Confluence Page
Navigate to the page and click the Edit icon, or just type E to open the editor. (Alternatively, you can create a new page.)
In the Confluence editor, click the '+' icon and choose View more from the drop down menu.
Find the item to be inserted and select it.
Click Insert.
Configure the macro and Save. Further down on this page you’ll find more information about configuration. 💡 At this stage the macro will display “No Data” which is expected. You need to publish the page and take a new snapshot before data appears.
You can also type '/' (forward slash symbol) while editing the page, to bring up the same list you'd see by in the View more menu.
Publishing and Generating the First Snapshot
Once the macro is configured, continue editing the rest of of the page, and click Publish when finished.
After the page is published, click Update to generate the first snapshot.
To create multi-level snapshots, follow Configure Multi-Level Jira Snapshots
Parameters
Parameters are options that you can set to control the content or format of the macro output.
JQL is Jira Query Language. This is the native query language for Jira, and these macros use it directly when retrieving data from Jira.
New to JQL? We have put here Jira JQL Cheat Sheet some information to help you get started.
Parameter name | Required | Default | Parameter description and accepted values |
|---|---|---|---|
Level title | No | Empty | A title for this level will be displayed above the column titles. |
Search JQL | Yes | - | In Level 1: Any valid JQL, applicable for the Jira from which the snapshot data is retrieved. This may include any JQL extensions by apps, as long as they are valid inside that Jira instance.
In Level 2 (or higher): Refer to Configure Multi-Level Jira Snapshots |
Add fields to display | Yes | Key, Summary | The list of Jira fields to display. Use the widget just below the field to drag and reorganize the order of the columns in the level.
|
It's a good practice to test the JQL first in Jira. Refer to the Jira manual for more information: Key Features
Any legitimate JQL clause can be used to retrieve data from Jira.
The list of columns is configurable.
Retrieving fresh data from Jira into Confluence is done from Page View mode, by clicking Update.
Each time fresh data is imported, a new Confluence page version is generated. This can be seen in the Page History view.
The DIFF tool enables you to compare the current Jira data with any previous snapshot.
A single Confluence page may include multiple instance of snapshot macros, each retrieving a different set of data.
Known Limitations
Snapshot macros cannot retrieve files, such as images, from Jira. So if a “Description” field contains a screenshot image, this image will not be included in the Confluence data. (Note that you may still see this image in Confluence if it's cached in your browser, but this is just a coincidence. The image will no longer be displayed after you clear you browser cache.)
Jira fields may have many different formats, and some apps may even have their own custom field types with special formats. This may lead to situations in which some fields are displayed incorrectly. Please contact RadBee if you run into this situation - we'll help you with the needed adjustments.