Configuring multi-level snapshots

A snapshot can capture more than a flat list of issues. By adding levels, you can show a hierarchy — for example, epics with their child stories, stories with their blockers, requirements with the tests that cover them. Most relationships available in Jira can be expressed as a snapshot level.

By the end of this page, you have a snapshot with two or more levels showing related issues from Jira.

Before you start

• A page with a single-level Snapshots macro already configured. See Taking your first snapshot from Confluence if you need to create one.

• A clear idea of which Jira relationship you want to show across levels (parent/child, blocked by, linked, sub-tasks, and so on).

How levels work

Each level has its own JQL search. Level 1 runs first and returns a set of issues. Level 2 runs for each issue in level 1 — and you reference level 1's results in level 2's JQL using a $ placeholder.

The most common reference is $key, which inserts the key of the level-1 issue into level 2's JQL. So a JQL like parent in $key reads as "for each level-1 issue, find all issues whose parent is that issue's key." You don't write the actual key; Snapshots substitutes it as it runs the search.

You aren't limited to $key — you can reference any field on the level-1 issue by name. If level 1 has a custom field called Manager (a user picker), level 2 can use assignee = $Manager to find issues assigned to the manager named on each level-1 row. The pattern is $<field name> for any field whose value Snapshots can substitute into the JQL.

Level 3 references level 2's results the same way, level 4 references level 3, and so on. There is no fixed depth limit — the practical limit is the width of your Confluence page once the table starts spreading out.

Referencing fields from higher levels

A level's JQL can also use fields from any level above it, not only the one directly above. Name the level, then the field: $level1.fixVersions is the Fix versions of the level 1 row, $level2.fixVersions the Fix versions of the level 2 row.

The link to the level directly above is still what brings issues into the level, and it is mandatory. The higher-level reference filters those issues further. For example, with requirements at level 1, the tests covering them at level 2, and the defects linked to those tests at level 3, this level 3 JQL keeps only the defects that are in the requirement's release:

issue in linkedIssues($key) AND fixVersion in $level1.fixVersions

The field you reference must be one of the fields selected in that level. In the example, level 1 must include Fix versions among its fields. Type $ in the JQL to see the fields you can reference, from the level above and from higher levels.

1. Add a second level

1. Edit the page and open the Snapshots macro configuration.

2. On the level configuration screen, click Add level. A second level appears with its own title, JQL, and field list.

3. Give the level a title — for example, Children.

4. Enter the JQL for the level. The field offers a dropdown with the two most common ways to link a level to the one above it, so for most snapshots you can pick rather than type:

   parent in $key
   

   issue in linkedIssues($key, "is tested by")
   

   Pick the one you need, or type your own JQL if the relationship you want is not one of the two. To use a different link type, replace the link name in the linkedIssues example.

5. Check the preview pane to verify the relationship works. Snapshots runs level 1, then runs level 2 against the first level-1 issue's key, and shows the result. Confirm the children returned match what you'd see in Jira.

   

6. Add the fields you want to display in level 2. For example: Type, Key, Summary, Status.

7. Click Insert snapshot to save the configuration.

2. Take a new snapshot

The configured levels don't capture data on their own — Snapshots only retrieves what's in scope at the moment you take a snapshot. After adding (or changing) a level, take a new snapshot from the page so the new scope is captured.

When the snapshot finishes, the table shows the level-1 issues on the left and their level-2 children stretched across to the right.

‌

Tip: As you add columns, the table gets wider. In the macro layout settings, switch the page width to wide so the snapshot has more horizontal room.

3. Add deeper levels

To go beyond two levels, repeat the process. For example, to add a third level showing blockers of the level-2 issues:

1. Open the macro configuration and click Add level. A third level appears.

2. Give it a title — for example, Blockers.

3. Enter the JQL using a different relationship. To find issues that block the level-2 results:

   issue in linkedIssues($key, "blocked by")
   

4. Check the preview pane to verify the level returns the expected linked issues.

5. Add the fields you want and Insert snapshot.

Common relationships you can express

Practical limits

You aren't limited to three or four levels — Snapshots supports as many as your data justifies. Real-world examples go up to eight levels. Beyond that, the Confluence page becomes uncomfortably wide; consider whether the deepest level should be a separate page or a separate snapshot instead.

What's next

• Display options on the Layout tab — for example, switch to "full grid" so each row has a complete set of values across levels.

• Grouping rows by a field — restructure the level-1 view by grouping on a column.

• Sorting, filtering, and grouping on the page — manipulate how the multi-level table displays at view time.