Versions Compared

Old Version 4

changes.mady.by.user Rina Nir _RadBee

Saved on

compared with

New Version 5

changes.mady.by.user Rina Nir _RadBee

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

There are two Jira JQL Snapshot Macros:

  1. Jira jql snapshot:

    1. Retrieves the results of a Jira JQL query.

    2. The list of columns (fields) is configurable by the Macro

  2. Jira jql traceability snapshot:

    1. Retrieves a two level traceability report: for example the list of requirements, and the specifications which are implemented by each requirement.

    2. Each of the levels is defined by a JQL query. The lower level query is dependent on the first level.

    3. The list of columns (fields) is configurable by the Macro.

...

Adding the Jira Snapshots Macro to a Confluence Page

  1. Navigate to the page and click the Edit icon, or just type E to open the editor. (Alternatively, you can create a new page.)

  2. In the Confluence editor, click the '+' iconand choose View more from the drop down menu.

  3. Find the item to be inserted and select it.

  4. Click Insert.

  5. Configure the macro and Save. Further down on this page you’ll find more information about configuration.

Info

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

  1. Once the macro is configured, continue editing the rest of of the page, and click Publish when finished.

  2. After the page is published, click Update to generate the first snapshot.

What are Levels?

By default, each Jira snapshot report includes a “Level 1.” This is a list of Jira issues retrieved using a JQL clause.

Sometimes you’ll need to include other issues, which are dependent or related to the issues in Level 1. These will be retrieved by adding a Level 2 to the report.

Examples of Level 1 - Level 2 issues:

  • Epics and their stories

  • Issues and their subtasks

  • Stories and their related bugs

  • Issues and their “blocker” issues

Jira Snapshots supports additional levels; you could go as far as three or four levels, if needed.

...

Parameters (for Each Level)

Parameters are options that you can set to control the content or format of the macro output.

Info

JQL is Jira Query Language. This is the native query language for Jira, and these macros use it directly when retrieving data from Jira.See here the complete JQL reference: 

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.

(lightbulb) It's a good practice to test the JQL first in Jira. Refer to the Jira manual for more information: https://

...

support.atlassian.com/

...

jira-software-cloud/docs/what-is-advanced-searching-

...

in-jira-cloud/

In Level 2 (or higher):

The JQL clause for Level 2 needs to include a reference to Level 1, in order to achieve the dependency/cascading effect.

Therefore, the search clause must reference fields in the previous level.

For example:

  • parent=$key : will retrieve subtasks of issues in the previous level

  • issue in linkedIssues($key) : will retrieve issues linked to the issue in the previous level

  • issuetype = Test AND issue in linkedissues($Key, "is tested by") : will retrieve test issues that are linked with this link type, to the issue in the first level.

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.

(lightbulb) The list of available fields is specific to the Jira instance the snapshot is connected to. The list includes custom fields configured for this instance.


(lightbulb) If integration with 3rd party apps is configured, such as Xray Test Management, then the list of fields here will also include fields available via the integration.

Key Features

  1. Any legitimate JQL clause can be used to retrieve data from Jira.

  2. List The list of columns is configurable.

  3. Retrieving fresh data from Jira into Confluence is done from the page VIEW Page View mode, by clicking the refresh button Update.

  4. Each time fresh data is imported, it generates a new Confluence Page page version is generated. This can be seen in the Page History view. 

  5. A The DIFF tool allows enables you to compare between the current Jira data and with any of the previous snapshotssnapshot. 

  6. A single Confluence page may include multiple instance of the snapshot macros, each retrieving another a different set of data.

Known Limitations

  1. The snapshot macros cannot retrieve files (ie- images) from Jira. So, if a 'description' field contain a screenshot image, this image will not be included in the Confluence data. Note: You might still see this image ij Confluence if it is cached in your browser, but this is just a coincidence. The image will no longer display if you clear you browser cache.

  2. Jira fields may have many different formats, and some Apps may even have their own custom field types with their special formats. This may lead to situations that some fields do not display correctly. Please contact RadBee if you run into this situation: and we'll try to adjust.

Using The Jira JQL Snapshot Macro

We assume you have a Confluence page, on which you want to add a table of Jira data. 

  1. EDIT the page and navigate to the location where you want the table to be.

  2. Enter this Macro on the page: "Jira jql snapshot"

  3. These are the parameters:

    1. JQL: This is a legals JQL clause that retrieves the data you want to have in the table, for example: filter="PPD Breast Risks"

    2. Fields: A semicolon separated list of fields. 

      1. For example: issue type;key;Components;Summary;Fix versions;Hazard;Harm;Probability;Impact;Risk level;Protective measures;Information for safety;Residual Probability;Residual Impact;Residual risk level;Residual risk impact;Residual risk acceptability

    3. Macro id: put here any unique string (unique in the scope of this page). This parameter is only needed if you have more then a single Snapshot macro on the same Confluence page.

  4. After configuring the parameters you can save the page.

  5. Initially, no data will be presented.

    1. Note: it is possible that you will be required to "authenticate to Jira": this is required to allow you to retrieve fresh data from Confluence.

  6. Click the "CREATE CONTROLLED SNAPSHOT" button to initiate the retrieval of fresh data from Jira.

Using The Jira JQL Traceability Snapshot Macro

Using the "Jira JQL traceability snapshot" macro is identical to using the "Jira jql snapshot", except that the list of configuration parameters is longer and caters to the "two levels traceability".

Here is the list of parameters

  1. Level 1 Title

  2. Level 1 JQL: This is any legal JQL clause that retrieves the data you want to have in the table,

    1. for example: project = PPD AND issuetype in ("Functional Requirement", "Non Functional Requirement") AND component = "Paige Breast Classification"

  3. Level 1 Fields: A semicolon separated list of fields. 

    1. For example: Key;Summary;Description

  4. Level 2 Title

  5.  Level 2 JQL: This is any legal JQL clause that retrieves the data you want to have in the table. In this JQL clause you can include reference to any of the columns of the first level, by refereing to it with a $ sign

    1. For example: issuetype = Test AND issue in linkedissues($Key, "is tested by")

  6. Level 2 Fields: A semicolon separated list of fields. 

    1. For example: Key;Summary;TestRunStatus - Current Version

  7. Macro Id: put here any unique string (unique in the scope of this page). This parameter is only needed if you have more then a single Snapshot macro on the same Confluence page.