Appearance
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
| Where | How to open it | What it's for |
|---|---|---|
| Treetop reports page | In the Jira top navigation, choose Apps → Treetop reports. | Build, run, save and export reports across any projects. |
| Project page | In a project's sidebar, choose Treetop (it may be listed under Apps). | The same report page, scoped to that project. |
| Issue panel | On 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 gadget | On 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
- Open Apps → Treetop reports.
- Under Templates, choose Open epics progress. The report runs straight away.
- 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.
| Template | JQL (global page) | Pivot by | Columns |
|---|---|---|---|
| Open epics progress | issuetype = Epic AND statusCategory != Done ORDER BY rank | No pivot | Type, Status, Points, % done (points), Done / issues, Time spent (h), Remaining (h) |
| Open epics by fix version | Same as above | Fix version | Fix versions, Status, Points, % done (points), Done / issues, Remaining (h) |
| Active sprint by assignee | sprint in openSprints() AND issuetype not in subTaskIssueTypes() ORDER BY rank | Assignee | Assignee, Status, Points, % done (points), Time spent (h), Remaining (h) |
| Time spent per epic | issuetype = Epic AND statusCategory != Done ORDER BY rank | No pivot | Status, Original estimate (h), Time spent (h), Remaining (h), Done / issues |
| Roll up through "…" links | issueLinkType = "<outward name>" AND statusCategory != Done ORDER BY rank | No pivot | Type, 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.
Also roll up through links
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.
| Option | Groups by | One group per issue? |
|---|---|---|
| Assignee | Assignee, or "Unassigned" | Yes |
| Status category | To do, In progress, Done | Yes |
| Status | Workflow status | Yes |
| Issue type | Issue type | Yes |
| Project | Project key | Yes |
| Sprint | Every sprint the issue has been in, or "(none)" | No, an issue can be in several |
| Fix version | Every fix version, or "(none)" | No |
| Component | Every component, or "(none)" | No |
| Label | Every 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.
| Column | What it shows |
|---|---|
| Type | Issue type |
| Status | Status, coloured by status category |
| Assignee | Assignee's display name |
| Project | Project key |
| Points | Rolled-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 done | Rolled-up points on issues in a Done status category |
| % done (points) | Points done ÷ Points |
| Done / issues | Done descendants / all descendants (a leaf shows itself, 1 / 1 or 0 / 1) |
| % done (issues) | Done / issues as a percentage |
| Unestimated | Open 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, Labels | The issue's own values, comma-separated |
| Extra number fields | Any 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
| Tile | Meaning |
|---|---|
| Points done | Points done / total points across all top-level issues, with a progress bar |
| Issues done | Done 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 spent | Total logged time, in hours. Shows Nh originally estimated below when there are original estimates |
| Remaining | Total remaining estimate, in hours |
| Unestimated | Open 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-14matches only that issue, notAPP-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.
- Set From and To. The default is the first day of the month two months ago up to today.
- Choose a Period: Day, Week (weeks start on Monday) or Month.
- Choose Rows: Person or Top-level issue.
- 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
- Choose Save report (for a new report) or Save (for a saved one you can edit).
- Enter a Report name (up to 100 characters).
- Under Who can see it, choose Everyone who can use Treetop (shared) or Only me (private). New reports default to shared.
- 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.
| Owner | Jira admin | Anyone else | |
|---|---|---|---|
| See and run a shared report | Yes | Yes | Yes |
| See and run a private report | Yes | No | No |
| Save changes to a shared report | Yes | Yes | No, use Save as new |
| Delete a shared report | Yes | Yes | No |
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:
- On the dashboard, choose Add gadget and pick Treetop progress.
- In Saved report, choose a report. Only shared reports are offered, because dashboards are usually shared.
- In Show, choose Totals and top-level issues or Totals only.
- Choose Save.
On a new dashboard:
- Choose Add widget and pick Treetop progress from the Marketplace widgets.
- In the edit panel, choose a Saved report and what to Show. The preview updates as you choose.
- 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.
| Example | Result |
|---|---|
| Epic estimated at 40, with stories of 5 and 8 points | Epic shows 13. Its own 40 is replaced. |
| Story of 5 points, with two sub-tasks that have no points | Story shows 5. Its own value stands. |
| Epic estimated at 40, with three stories that have no points | Epic 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.
| Example | Unestimated |
|---|---|
| Story with no points and no children, To do | 1 |
| Same story, Done | 0 |
| Story of 5 points with two sub-tasks without points | 0 (the story's 5 covers them) |
| Epic with stories of 5 and 8 points and a third story with no points | 1 |
"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
| Limit | Value | What happens |
|---|---|---|
| Issues per report (report page) | 20,000 | Loading stops and a warning says totals are partial |
| Issues per issue panel or gadget | 5,000 | Same warning |
| Depth below the top-level issues | 8 levels by default; your admin can set 1 to 12 | Deeper levels are left out, with a warning |
| Issues read on the Time by period tab | 2,000 with time logged | A warning says totals are partial |
| Saved reports per site | 500 | Saving a new one is refused |
| JQL length | 4,000 characters | The report can't run |
| Report name | 100 characters | Longer 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
| Warning | What it means | What 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
| Message | Cause | What 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 JQL | The 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 found | Treetop 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 worklogs | Reading 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.