Documentation

Stepwise Time in Status for Jira: user guide

Where to find the app, how to run a report, how every number is counted, and the details admins ask about: calendars, limits, permissions and data.

On this page
  1. Getting started
  2. Run a report
  3. JQL examples
  4. The reports
  5. How time is counted
  6. Working calendars
  7. Saved reports
  8. CSV export
  9. Premium features
  10. Permissions
  11. Limits and slowing down
  12. Data and privacy
  13. FAQ
  14. Troubleshooting
  15. Not available yet

Getting started

Stepwise Time in Status for Jira is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its two permissions (explained under Permissions). There is nothing to set up on your statuses or workflows: the app reads the history Jira already keeps, so old work items are covered from the first report.

Where to find it

  • Apps menu. Open Apps in the Jira top bar and choose Stepwise Time in Status. This is the full report page: you type the JQL.
  • Project tab. Every project gets a tab for the app. It is the same report page, and it starts with that project already chosen in the JQL.
  • Work item panel. Open any work item and look for the Stepwise Time in Status panel at the right: a strip showing how long this work item spent in each status, with the entries and the assignees. It updates when the work item changes.
  • Dashboard gadget. On a dashboard choose Add gadget and add Stepwise Time in Status. Set its JQL, grouping, unit, calendar and period in the gadget settings. It shows bars of the average time per status and three numbers: average cycle time, average lead time and the number of work items.
  • Jira settings, Apps. Jira admins set up working calendars here.

Jira changes the names and places of its menus from time to time, and a Jira admin can hide apps from the menu. If you cannot find the app, ask your Jira admin where it was added.

Run a report

  1. Type a JQL query that finds the work items you care about. See JQL examples.
  2. Choose a period: all time, the last N days or a date range.
  3. Choose a calendar (working hours or 24/7), a unit for durations, how to group the result and which statistic to show (average or median).
  4. Optionally set status groups and excluded statuses. See How time is counted.
  5. Press Run report.

While the report runs, a progress line shows what is happening, for example Reading work items… 1,500 and then Reading history… 750 of 5,000. Cancel stops it at any moment. The result is a snapshot: the screen shows the time at which the data was read.

Durations can be shown as days, hours and minutes, as decimal days, as hours or as minutes. A “working day” is as long as the working day of the calendar you chose.

JQL examples

Jira needs the query to have at least one restriction, such as a project or a date. A query that is only a sort order is refused by Jira. These are typical starting points:

QuestionJQL
What did one project finish in the last 30 days?project = WEB AND statusCategory = Done AND resolved >= -30d
How is the current sprint doing?project = WEB AND sprint in openSprints()
Last month’s bugsproject = ENG AND issuetype = Bug AND created >= startOfMonth(-1) AND created < startOfMonth()
Work of one epicparent = ENG-100
Everything with a labelproject = ENG AND labels = payments
What I touched recentlyassignee = currentUser() AND updated >= -14d
Work waiting in one status nowproject = SUP AND status = "Waiting for customer"

On a project tab the report starts with project = KEY already in the query. Keep the report to the work you want to compare: a report covers up to 5,000 work items (see Limits).

The reports

Each tab shows a table and a chart. The table summarises by your chosen group and opens down to single work items. You can sort it. Names that are too long are cut and show in full on hover.

TabWhat it shows
Time in statusFor each status, the time work items spent in it, as average or median, by your group (assignee, work type, priority, sprint, epic, label or project), down to each work item
AssigneesThe time each person held each work item. Time with nobody assigned is its own row
Cycle & leadCycle time and lead time: average and median, by your group, plus the count of work items still in progress
EntriesThe first and last date a work item entered each status, how many times it entered it, and how many transitions it had
BlockedHow long work items were flagged
TrendsPremium. See Premium features

The Blocked tab reads Jira’s own Flagged field, so it works when your team uses the standard flag on work items. If the tab is empty although you use flags, tell us: Jira sites differ in how they name the field and we are still checking this on live sites.

The result of any report is only what Jira shows the person who ran it. A work item with a security level that you cannot see is not in your report, and the screen says so.

How time is counted

The numbers come from the history Jira keeps for each work item: every change of status, assignee and flag, with the time it happened. These are the rules, in plain words.

Statuses and visits

  • A status is identified by its id. A renamed status is one row under its new name. A deleted status stays under the last name Jira remembers. Statuses with the same name (case ignored) are one row.
  • Where a work item started. Its first status is the one it left at its first transition. A work item with no transitions has been in its current status since it was created.
  • The last status runs until now. A work item still in a status counts time up to the moment the report was read.
  • A row is the sum of all visits. If a work item went to “In Review” three times, the time in “In Review” is the total of the three visits.
  • Entries. Creating a work item counts as its first entry into its first status. A transition that lasted a second, for example one run by automation, is kept and counted as an entry.
  • Status groups. Put several statuses in one group, such as “In work”. A group is one row, and moving between statuses inside the group is one visit.
  • Excluded statuses are not counted at all, and they end a visit.

Working time

  • With a working calendar, only the time inside its working hours counts, in the calendar’s time zone. A holiday is a day off whatever the weekday.
  • When clocks change for daylight saving, a working window keeps its length on the wall clock: 09:00 to 17:00 is eight hours before and after the change.
  • An empty calendar, with no working hours at all, counts zero.
  • The built-in 24/7 calendar simply measures the time between two moments.

Cycle time and lead time

  • Cycle time runs from the first time the work item entered a start status to the last time it entered an end status, as long as it did not leave that end status again.
  • Lead time runs from the creation of the work item to that same moment.
  • By default, start statuses are those in the “In Progress” category and end statuses are those in the “Done” category. You can choose your own.
  • A work item that is not in an end status is in progress. Its time keeps running until now, but it is left out of the averages and medians and shown as a count.
  • A work item that is reopened is in progress again, until it reaches an end status once more.
  • A work item that goes from To Do straight to Done has a lead time and no cycle time.

Period

When you choose a period, time is cut to the period, and entries are counted only when they happened inside it. Cycle time and lead time are not cut: a work item is measured in full.

Assignees

Time per assignee follows the assignee changes in the history. Time with nobody assigned is shown as its own row. Work held by a person who no longer exists in Jira is shown as Unknown user.

Average, median and 85th percentile

The average of a row covers only the work items that entered that status. The median is the middle value. The 85th percentile (Premium) is the value that at least 85 percent of the work items stay at or below, using the nearest-rank method.

Trends

The trend (Premium) groups finished work items by the week (starting Monday) or the month in which they were finished, in the time zone of the calendar.

What cannot be known exactly

  • Search is a little behind. Jira’s search can lag behind a change by seconds to minutes. A report is a snapshot and shows when it was read.
  • History that is cut short. If the history of a work item ends in a different status from the one the work item is in now, the report shows a warning. The app does not invent the missing time.
  • Unreadable history entries are skipped, and the report says so.

Working calendars

A calendar has working hours for each day of the week, a list of holidays and a time zone. Choose a calendar in each report, in the gadget settings and as the default for the work item panel.

  1. Open Jira settings, then Apps, then Stepwise Time in Status. You need to be a Jira admin.
  2. Create the calendar: set the hours for each day, add holidays and choose the time zone.
  3. Choose which calendar is the default.

The built-in 24/7 calendar is always available and needs no set-up. Without a calendar of your own, reports use it. You can keep one calendar of your own; Premium adds more.

Saved reports

  • Save keeps the settings of the report: JQL, period, calendar, group and so on. It does not keep any results or work items. Open a saved report and press Run report to get fresh numbers.
  • Each person can keep up to 25 saved reports of their own. Rename or delete them from the list.
  • The JQL is stored as you typed it. If you wrote a person’s account ID into the query, it is stored with it, and the screen warns you when you save.
  • Share turns a saved report into one the whole team can open. See Premium features.

CSV export

Press the export button on a report to download its table as CSV, then open it in Excel or Google Sheets.

  • Every cell is in quotes.
  • A cell that starts with =, +, - or @, or with a tab or line break, gets an apostrophe in front, so a spreadsheet never runs it as a formula.
  • The file starts with a byte-order mark, so Excel reads accents and other languages correctly.
  • Person names are in the file as they are on screen; account IDs are not.

Premium features

Everything above works without Premium. Premium adds the following, each marked with a small crown in the app.

Several calendars

Keep up to 20 working calendars, for example one per team or time zone, and choose one per report.

Shared reports

Share a saved report so the whole team opens the same one. Up to 200 shared reports. Jira admins edit them. A shared report keeps only the settings, as a saved report does.

  • Trends by week or month, with the 85th percentile.
  • Compare periods puts two periods side by side.

Permissions

Who can do what

ActionWho
Run a report, use the panel and gadget, keep your own saved reportsAnyone who can open the app in Jira. Reports show only the work items that person may see
Create or change calendars, and the default calendarJira admins
Share or change shared reports (Premium)Jira admins

What the app is allowed to do

When the app is installed, Jira asks the admin to approve two permissions:

PermissionWhy the app needs it
read:jira-workTo search work items, read their history of changes, list statuses and fields, and ask Jira whether the current person is an admin
storage:appTo keep saved reports and calendars in Atlassian-hosted app storage

The app has no write permission for work items. Everything you do on screen runs as you, with your own permissions. It does not act as itself anywhere.

Limits and slowing down

ItemLimit
Work items in one report5,000. If your JQL finds more, the report shows the first 5,000 and says so
Saved reports per person25
Calendars of your own1 (up to 20 with Premium)
Shared reports (Premium)200

When Jira asks the app to slow down

A report of 5,000 work items makes about 72 requests to Jira: the work items are read 100 at a time and their history 250 at a time. Jira limits how fast apps may read, and it can ask for a pause.

  • The app waits for as long as Jira asks, with a little random variation, and shows a countdown. It tries again up to four times. You can cancel at any time.
  • If Jira says the app’s hourly allowance is used up, or the wait would be longer than two minutes, the app stops at once. It shows what it already has, only for the work items whose history it read in full, marks the report in large letters as incomplete, and shows the waiting time and a Continue button. Continue picks up from what was already read.
  • If Jira is unavailable or the network drops, the app tries twice more and then tells you that Jira is unavailable.
  • A work item whose last update has not changed since it was read earlier in the same visit is taken from memory, not read again.

We have tested all of these cases against a stand-in for Jira. How often the largest reports meet Jira’s limits on busy live sites is still being measured. If your reports often stop with “incomplete”, narrow the JQL by project, period or sprint, and tell us.

Data and privacy

  • The app is built on Atlassian Forge. It has no external servers, no analytics and no AI, and it sends nothing outside Atlassian.
  • Reports are calculated in your browser from data that Jira returns to you. Results are not stored.
  • The app stores only: calendars, saved report settings (JQL, grouping, statuses and so on) and an installation-wide default calendar.
  • Personal saved reports are filed under a short label made from your account ID and a random key of the installation by a one-way hash. Your account ID itself is not stored.
  • Not stored: work item data, titles, report results, names, emails and account IDs.
  • The app writes nothing to your work items.
  • Names of assignees are shown on screen and in CSV as Jira provides them, and are not saved.
  • To remove the app’s stored data, uninstall the app.

More detail: Security and data. Legal wording: Privacy policy.

FAQ

What does Stepwise Time in Status for Jira show?
How long every work item spent in every status, who held it, when it entered each status and how often it came back. Also cycle time, lead time and blocked time, with averages and medians by assignee, type, priority, sprint, epic, label or project.
Does it count working hours?
Yes. Choose a working calendar with days, hours, holidays and a time zone. The built-in 24/7 calendar counts every hour.
How are cycle time and lead time defined?
See Cycle time and lead time. Cycle time starts at the first entry into your start status and stops at the last entry into your end status. Lead time starts at creation.
Why is a work item not in the averages?
A work item that is not in an end status is in progress. It is shown as a count and left out of averages and medians.
Can I see time per assignee?
Yes, on the Assignees tab, with unassigned time on its own row.
Does it work on work items I already have?
Yes. It reads the history Jira keeps, so old work items are covered from the first report.
How many work items can a report cover?
Up to 5,000 per report. Narrow the JQL if you need more detail, or run separate reports for separate projects.
Does it write anything to my work items?
No. It has read access only.
Where does the data go?
Nowhere outside Atlassian. Reports are calculated in your browser, and the app stores only calendars and saved report settings.
Does it work with Jira Service Management projects?
Support for Jira Service Management is not part of this release.
Does it support dark theme?
Yes, it follows each person’s Jira theme automatically.

Troubleshooting

A work item I expected is missing
Check that your JQL finds it. The report cannot show a work item that you are not allowed to see in Jira, for example because of a security level. Jira’s search can also lag by seconds to minutes after a change, so a work item changed a moment ago may not be in the snapshot yet.
The report says it shows the first 5,000 work items
Your JQL found more work items than one report can cover. Narrow it by project, period or sprint.
The report is marked incomplete
Jira asked the app to slow down for too long. The numbers shown cover only the work items the app finished reading. Press Continue after a few minutes, or narrow the JQL. See When Jira asks the app to slow down.
The numbers look different from what I expected
Check the calendar (working hours or 24/7), the unit, the period and the status groups. Remember that work in progress is left out of cycle time and lead time averages, and that a period cuts time in a status but not cycle time or lead time.
A warning says the history ends in a different status
Jira returned a history that does not end where the work item is now. The app shows the warning and does not invent the missing time for that work item.
The Blocked tab is empty
The tab reads the Flagged field. Check that work items on your site are flagged with Jira’s standard flag, then tell us if it is still empty.
The CSV download does not start
Try again in another browser tab or browser. Downloads from inside Jira’s app frame are still being checked in every browser. Tell us which browser you use.
I cannot save a calendar or share a report
These need a Jira admin. Shared reports and more than one calendar also need Premium.

Not available yet

These are not in the app today. We list them so that you know what not to look for yet. There are no dates attached.

  • Keeping results between visits, for reports of thousands of work items
  • Scheduled reports and email
  • Jira fields with calculated time, and JQL functions
  • Jira Service Management projects

Missing something else? Tell us.