How to Configure a Multi-Level Jira Snapshots Macro

What are Multi-Levels Snapshots?

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
XRAY Test issues and their test runs → In this specific case, the 2nd level is a XRay Test Runs levels in Jira Snapshots

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.

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 type	Yes	Jira Issue	To learn more about Test Run Level type, read XRay Test Runs levels in Jira Snapshots . This parameter is not available at the 1st level (as Test Run levels is not available at the first level)
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. 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. 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. 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.