Skip to content

Treetop user guide ​

Treetop adds up story points, estimates and logged time from every level of a Jira hierarchy, so you can see how much of each epic or initiative is done, estimated and spent. It is read-only: it never changes your issues.

Treetop is a Jira Cloud app built on Atlassian Forge. Every number you see is computed with your own Jira permissions, so you only ever see issues you can open in Jira.

Getting started ​

Where to find Treetop ​

WhereHow to open itWhat it's for
Treetop reports pageIn the Jira top navigation, choose Apps → Treetop reports.Build, run, save and export reports across any projects.
Project pageIn a project's sidebar, choose Treetop (it may be listed under Apps).The same report page, scoped to that project.
Issue panelOn any issue, choose the Treetop button below the summary to add the panel.Rolled-up totals and the child tree for that one issue.
Dashboard gadgetOn a dashboard, choose Add gadget and pick Treetop progress.One shared saved report as a progress summary.

The first time you open the report page you'll see Roll up any hierarchy with a short explanation. Start from a template, open a saved report, or type JQL and run it.

Your first report in one minute ​

  1. Open Apps → Treetop reports.
  2. Under Templates, choose Open epics progress. The report runs straight away.
  3. Read the tiles at the top, then expand an epic with the ▸ arrow to see its stories and sub-tasks.

Building a report ​

A report has four parts: which top-level issues to start from, whether to also follow issue links, an optional pivot, and the columns to show.

Top-level issues (JQL) ​

Type a JQL query in Top-level issues (JQL). These issues are the top rows of the report. Everything below them (stories, sub-tasks and any custom level above or below epic) is found through the parent field and rolled up automatically. You don't need to include the children in your query.

  • Press Ctrl+Enter (Windows, Linux) or ⌘+Enter (Mac) to run, or choose Run report.
  • If the box is empty, Use the example fills in issuetype = Epic AND statusCategory != Done ORDER BY rank.
  • JQL can be up to 4,000 characters.
  • If your query also returns some of the children, Treetop still uses only the issues whose parent isn't in the result as the top rows. A child is never shown twice.

Or start from a saved Jira filter ​

Choose a filter in Or start from a saved Jira filter. Treetop replaces the JQL with filter = <id>. Your favourite filters are listed first and marked ★. Up to 100 filters you can see are listed.

Templates ​

Templates set the JQL, link types, pivot and columns in one click, then run the report. On a project page, every template's JQL starts with project = <KEY> AND.

TemplateJQL (global page)Pivot byColumns
Open epics progressissuetype = Epic AND statusCategory != Done ORDER BY rankNo pivotType, Status, Points, % done (points), Done / issues, Time spent (h), Remaining (h)
Open epics by fix versionSame as aboveFix versionFix versions, Status, Points, % done (points), Done / issues, Remaining (h)
Active sprint by assigneesprint in openSprints() AND issuetype not in subTaskIssueTypes() ORDER BY rankAssigneeAssignee, Status, Points, % done (points), Time spent (h), Remaining (h)
Time spent per epicissuetype = Epic AND statusCategory != Done ORDER BY rankNo pivotStatus, Original estimate (h), Time spent (h), Remaining (h), Done / issues
Roll up through "…" linksissueLinkType = "<outward name>" AND statusCategory != Done ORDER BY rankNo pivotType, Status, Points, % done (points), Done / issues, Time spent (h)

The last template only appears if your site has a link type whose name starts with "Contains", "Parent" or "Hierarchy". It selects that link type for you, so you get a link-based hierarchy straight away.

If you've changed the current report and not saved it, choosing a template asks Discard your unsaved changes to this report? first.

By default Treetop follows only the parent field. To build a hierarchy from issue links too, open Also roll up through links and tick one or more link types. Each option shows which way round it works, for example Contains · A contains B → A is the parent.

The rule is: the issue on the outward side of the link is the parent. For a link "A contains B", A is the parent and B is the child. For a link type whose outward and inward descriptions read the same, such as Relates ("relates to"), the direction depends on how each link was created. Check the tree after running, and prefer a directional link type such as Contains for hierarchies.

Links are followed at every level, together with the parent field. Linked issues can be in any project.

Pivot by ​

Pivot by adds a second view that groups every issue in the report by one field. Choosing a pivot opens its tab.

OptionGroups byOne group per issue?
AssigneeAssignee, or "Unassigned"Yes
Status categoryTo do, In progress, DoneYes
StatusWorkflow statusYes
Issue typeIssue typeYes
ProjectProject keyYes
SprintEvery sprint the issue has been in, or "(none)"No, an issue can be in several
Fix versionEvery fix version, or "(none)"No
ComponentEvery component, or "(none)"No
LabelEvery label, or "(none)"No

Choose No pivot to remove it.

Columns ​

Open Columns to choose what the hierarchy shows. Key and Summary are always shown. If you untick everything, the picker reads Key and summary only.

ColumnWhat it shows
TypeIssue type
StatusStatus, coloured by status category
AssigneeAssignee's display name
ProjectProject key
PointsRolled-up story points (see How the numbers are calculated). Blank when nothing at or below the issue is estimated, so 0 always means a real zero
Points doneRolled-up points on issues in a Done status category
% done (points)Points done ÷ Points
Done / issuesDone descendants / all descendants (a leaf shows itself, 1 / 1 or 0 / 1)
% done (issues)Done / issues as a percentage
UnestimatedOpen leaf issues below with no points and no estimate above them
Original estimate (h)Summed original estimate, in hours
Time spent (h)Summed logged time, in hours
Remaining (h)Summed remaining estimate, in hours
Sprint, Fix versions, Components, LabelsThe issue's own values, comma-separated
Extra number fieldsAny number fields your Jira admin added in Treetop settings, rolled up like story points

Default columns are Type, Status, Points, % done (points), Done / issues, Time spent (h) and Remaining (h).

What needs a re-run ​

Changing columns or Pivot by updates the results immediately. Changing the JQL or the link types needs a new run, and the page shows The query or links changed. Run the report to update the numbers. until you run it.

Running and stopping ​

While a report loads you'll see Loaded N issues, N levels down…. The previous results stay on screen, dimmed, until the new ones arrive. Choose Stop to end early. You then see the partial numbers with the warning Loading was stopped early, so these numbers are partial.

Reading the results ​

Summary tiles ​

TileMeaning
Points donePoints done / total points across all top-level issues, with a progress bar
Issues doneDone issues / all issues. If any top-level issue has children, the tile says counted below the top-level issues: parents are measured by their children, not counted themselves
Time spentTotal logged time, in hours. Shows Nh originally estimated below when there are original estimates
RemainingTotal remaining estimate, in hours
UnestimatedOpen issues with no points (see the rules below). Subtitle: open issues with no points

If your site has no story points field, the Points done and Unestimated tiles are hidden and the page shows No story points field found. Progress is then shown by issue count.

Hierarchy tab ​

The Hierarchy tab shows a tree table. Top-level issues start expanded, so you see their first layer of children.

  • Expand or collapse one issue with ▸ / ▾, or all of them with Expand all and Collapse all.
  • Filter by key or summary shows matching issues together with their parents, fully expanded, and highlights the matches. Typing an exact key such as APP-14 matches only that issue, not APP-140. Expand all and Collapse all are disabled while a filter is active.
  • Sort by clicking a column heading. Sorting reorders siblings under each parent, so the tree stays intact. Numbers sort largest first and text A to Z; a second click reverses the order and a third click clears the sort. Empty values always go last.
  • Issue keys open the issue in Jira.
  • A dot ● next to a parent's points means some open issues below it have no points. Hover over it to see how many.
  • Large reports show 500 rows at first. Choose Show more to see more.

Pivot tab ​

When a pivot is chosen, a tab such as By assignee or By fix version appears. Each row is one group, with these columns: Issues, Done, Points, % done (points), Spent (h) and Remaining (h). Groups are sorted by the number of issues, largest first.

For single-valued fields (assignee, status, status category, issue type, project), the groups add up to the report totals. For multi-valued fields (sprint, fix version, component, label), the page says An issue with several labels counts in each of them, so the groups can add up to more than the total. (with the field name in place of "labels").

Time by period tab ​

Time by period shows logged work from worklogs, per person or per top-level issue, by day, week or month.

  1. Set From and To. The default is the first day of the month two months ago up to today.
  2. Choose a Period: Day, Week (weeks start on Monday) or Month.
  3. Choose Rows: Person or Top-level issue.
  4. Choose Load worklogs.

Only issues in the report with time logged are read. The page tells you how many before you load, for example 3 issue(s) in this report have time logged. Worklogs are dated by the day they were logged for, as entered in Jira.

After loading, you can change the period, the rows and a later From or earlier To without reloading. If you move From earlier than the date you loaded from, the page shows The start date is earlier than the loaded worklogs. Reload worklogs to include the extra days. Choose Reload worklogs.

The tab reads worklogs for at most 2,000 issues. Beyond that, or if you choose Stop, you see Only part of the worklogs were loaded (stopped early, or more than 2,000 issues with time). Totals are partial.

Re-running the report clears loaded worklogs, because the rows may have changed.

Saving and sharing reports ​

Save a report ​

  1. Choose Save report (for a new report) or Save (for a saved one you can edit).
  2. Enter a Report name (up to 100 characters).
  3. Under Who can see it, choose Everyone who can use Treetop (shared) or Only me (private). New reports default to shared.
  4. Choose Save. You'll see Saved "name".

A saved report stores the JQL, link types, pivot and columns. It does not store results. Every time anyone opens it, it runs again with that person's Jira permissions, so two people can see different numbers from the same report.

Save as new saves your current settings as a copy, named "(copy)" by default, which you own. Use it to keep your own version of someone else's shared report.

Saved reports list ​

The Saved reports panel lists Mine and Shared with everyone. Private reports are tagged private, and reports saved on a project page are tagged with the project key.

OwnerJira adminAnyone else
See and run a shared reportYesYesYes
See and run a private reportYesNoNo
Save changes to a shared reportYesYesNo, use Save as new
Delete a shared reportYesYesNo

Project reports ​

Reports saved from a project page belong to that project. The project page lists only that project's reports. The global Treetop reports page lists every report you can see, tagged with its project.

Unsaved changes ​

The page shows Unsaved changes to <name> (or Not saved yet for a new report). Opening another report, choosing a template or choosing New report asks Discard your unsaved changes to this report? first.

Delete a report ​

Choose × next to the report, then Delete to confirm or Keep to cancel. Dashboard gadgets showing that report stop working.

A site can hold up to 500 saved reports.

Exporting ​

Export CSV and Export Excel are on the Hierarchy and pivot tabs.

  • Exports contain every row, fully expanded, with your current columns, sort and filter. With a filter active, you get the matching rows and their parents.
  • A Level column (0 for top-level issues) keeps the hierarchy. In Excel, summaries are also indented.
  • Done / issues becomes two number columns, Issues done and Issues, so spreadsheets can add them up.
  • Export CSV on a pivot tab exports the pivot table.
  • Export Excel writes a Roll-up sheet, plus a Pivot sheet when a pivot is chosen.
  • On the Time by period tab, Export CSV exports the time table.

File names use the report name and today's date, for example Open-epics-2026-10-17.csv. CSV files are UTF-8 and open correctly in Excel. Text that starts with =, +, - or @ is prefixed with ' so spreadsheets don't run it as a formula.

The issue panel ​

Open any issue and choose the Treetop button to add the panel. It shows the roll-up for that issue:

  • Points done N of N, Issues done N of N, Spent, Remaining and, when there are any, Unestimated.
  • A progress bar labelled Progress by story points, or Progress by issue count when there are no points below.
  • A table of everything below the issue: Issue, Status, Points (with "(N unestimated)" where relevant), % done (points) or % done (issues), and Spent. It shows 10 rows per page.

The panel follows the parent field, plus any link types your Jira admin chose in Treetop settings. Choose Refresh to recalculate after changes. An issue with nothing below it shows Nothing below this issue to roll up yet. The panel loads up to 5,000 issues.

The dashboard gadget and widget ​

Jira is moving to new dashboards. Treetop works on both:

  • On a classic dashboard, Treetop is a gadget.
  • On a new dashboard, Treetop is a widget.

They show the same thing.

On a classic dashboard:

  1. On the dashboard, choose Add gadget and pick Treetop progress.
  2. In Saved report, choose a report. Only shared reports are offered, because dashboards are usually shared.
  3. In Show, choose Totals and top-level issues or Totals only.
  4. Choose Save.

On a new dashboard:

  1. Choose Add widget and pick Treetop progress from the Marketplace widgets.
  2. In the edit panel, choose a Saved report and what to Show. The preview updates as you choose.
  3. Save the dashboard.

The gadget and the widget show the report name, any warnings, the totals and, if chosen, a table of top-level issues with Points, % done (points) (or % done (issues)) and Remaining. It runs the report as the person viewing the dashboard, so viewers see only issues they can open. It loads up to 5,000 issues.

If there are no shared reports yet, the gadget says so. Save a report with Everyone who can use Treetop on the Treetop reports page, then come back.

How the numbers are calculated ​

These rules apply everywhere: the report page, exports, the issue panel and the gadget.

Story points and extra number fields: children replace the parent ​

If any child has a value, the sum of the children replaces the parent's own value. If no child has a value, the parent's own value stands. The same rule applies to the extra number fields your admin adds.

Teams usually estimate either the epic or its stories. Adding both would double count.

ExampleResult
Epic estimated at 40, with stories of 5 and 8 pointsEpic shows 13. Its own 40 is replaced.
Story of 5 points, with two sub-tasks that have no pointsStory shows 5. Its own value stands.
Epic estimated at 40, with three stories that have no pointsEpic shows 40.

A parent's points are done when they come from done children. A parent's own points count as done only if the parent itself is in a Done status category.

If your site has more than one story points field (for example "Story point estimate" in team-managed projects and "Story Points" in company-managed ones), each issue uses the first field that has a value.

Time: always summed ​

Time spent, Original estimate and Remaining are added up at every level, including time on the parent itself. Time logged on an epic is real work, so it isn't replaced.

Example: an epic with 1h logged on itself and 4h on its stories shows 5h spent.

Issue counts: parents are measured by their children ​

Done / issues and % done (issues) count the issues below a parent, not the parent itself. An open epic whose stories are all done reads 100%.

A leaf issue counts as itself: 1 / 1 when done, 0 / 1 when not.

The Issues done tile and the gadget use the same rule: each top-level issue with children contributes its descendants, and each top-level issue without children counts as itself.

Example: an epic with 5 issues below it, 2 of them done, shows 2 / 5 and 40%.

Percentages are rounded down ​

Percentages are floored, so 100% only ever means complete. 5 of 13 points is 38.46%, shown as 38%. 99.9% shows as 99%.

Unestimated ​

Unestimated counts open leaf issues with no points and no estimate above them. Done issues don't count, because finished work no longer needs an estimate.

ExampleUnestimated
Story with no points and no children, To do1
Same story, Done0
Story of 5 points with two sub-tasks without points0 (the story's 5 covers them)
Epic with stories of 5 and 8 points and a third story with no points1

"Estimate" here means story points. Original estimate (time) does not count.

Duplicates and loops ​

With link types, one issue can be reachable from more than one parent. Treetop puts it under the first parent it reaches and counts it once, so totals are never inflated. The report warns you and lists the issues.

If top-level issues are each other's parents (a loop through the parent field or links), Treetop starts a tree from the first one, puts the others inside it, counts each issue once and warns you.

Pivots ​

Pivots use each issue's own contribution, not its rolled-up total, so nothing is counted twice:

  • Points count on the issue that holds them. An epic whose 40 is replaced by its stories contributes 0 points; the stories contribute 5 and 8.
  • Time counts on the issue it was logged on.
  • Issue counts follow the tile rule: a top-level issue with children isn't counted in Issues, but its own logged time still is.

For single-valued fields, the groups add up to the report totals. For multi-valued fields (sprint, fix version, component, label), an issue counts in each group it belongs to, so the groups can add up to more than the total.

Limits ​

LimitValueWhat happens
Issues per report (report page)20,000Loading stops and a warning says totals are partial
Issues per issue panel or gadget5,000Same warning
Depth below the top-level issues8 levels by default; your admin can set 1 to 12Deeper levels are left out, with a warning
Issues read on the Time by period tab2,000 with time loggedA warning says totals are partial
Saved reports per site500Saving a new one is refused
JQL length4,000 charactersThe report can't run
Report name100 charactersLonger names are cut off

Rate limiting ​

Jira limits how fast apps can call it. If Jira says to slow down, or is briefly unavailable, Treetop waits and retries automatically, following Jira's requested wait time where given. Large reports keep showing progress while this happens. If retries run out, the report fails with a message rather than showing partial numbers silently.

Troubleshooting ​

Warnings on a report ​

WarningWhat it meansWhat to do
Loading was stopped early, so these numbers are partial.You chose Stop, or started another run.Run the report again and let it finish.
Stopped at 20,000 issues, so totals are partial. Narrow the JQL to see complete numbers.The report reached the issue limit (5,000 in the panel and gadget).Narrow the JQL, for example by project, fix version or status.
Hierarchy is deeper than N levels below the top issues; deeper levels are not included.Some issues sit more than the maximum depth below the top rows.Start from a lower level, or ask your Jira admin to raise Maximum levels below the top issue.
N issue(s) sit under more than one parent and are counted once, under the first: …Through links, an issue is reachable from more than one parent.Usually fine. If an issue is in the wrong place, untick a link type or fix the links.
Some top-level issues are each other's parents (a loop through the parent field or links). They are shown starting from …, with each issue counted once.A loop in parents or links.Check the links on the listed issues.
N linked issue(s) could not be read (deleted or no permission) and were skipped: …A linked issue was deleted, or you can't browse it.Check access to those issues. Other people may see different totals.
The query or links changed. Run the report to update the numbers.The results on screen are from the previous JQL or links.Choose Run report.

Errors ​

MessageCauseWhat to do
The report could not run · The JQL is not valid: …Jira rejected the query. The rest of the message is Jira's own explanation.Fix the query. Test it in Jira's issue search.
No issues match this JQLThe query returned nothing you can see.Check the query in Jira's issue search, and that you can browse those projects.
Jira is rate limiting requests right now. Wait a minute and run the report again.Treetop's automatic retries ran out.Wait a minute and run again. Very large reports are the usual cause; narrowing the JQL helps.
Jira search failed (HTTP N)…Jira returned an unexpected error.Try again shortly. If it continues, contact support.
No story points field foundTreetop can't find a story points field. Progress is shown by issue count.Ask a Jira admin to choose the field in Jira settings → Apps → Treetop settings.
Only the report owner or a Jira admin can change this report. Use "Save as new" to keep your own copy.You tried to save over someone else's report.Choose Save as new.
Only the report owner or a Jira admin can delete this report.You tried to delete someone else's report.Ask the owner or a Jira admin.
This site has reached 500 saved reports. Delete some before saving new ones.The site limit is reached.Delete reports you no longer need.
This report no longer exists or is private.A gadget points to a deleted report, or a report made private.Edit the gadget and choose another shared report.
Export failed: Excel export took too long. Try Export CSV, or narrow the report.The Excel file took more than 30 seconds to build.Use Export CSV, or narrow the report.
Could not load worklogsReading worklogs failed, often because of rate limits.Wait a minute and choose Load worklogs again.
The start date is after the end date.From is later than To.Fix the dates.
Could not roll up this issue (issue panel)The panel couldn't load.Choose Try again.
Your Treetop licence is not active. Ask a Jira admin to renew it in Manage apps.The site's Treetop subscription has lapsed.Ask a Jira admin.
Log in to Jira to see Treetop reports.You're viewing a public dashboard without logging in.Log in.

My numbers differ from a colleague's ​

Treetop runs as the person viewing. If your colleague can browse projects you can't, their totals include issues yours don't. This is deliberate.

Settings changes don't show up ​

Open reports keep the settings they started with. Reload the page after a Jira admin changes Treetop settings.

Getting help ​

Contact info@solidini.com.