Worklog Reports for Jira: documentation

User documentation for the Marketplace listing. This file is the source of truth: it is published as is on https://toolooloo.fr/docs/worklog-reports-for-jira by toolooloo-site (npm run sync && npm run build), and that URL goes in the listing's Documentation field. Edit the file, never the published page.

What the app does

Jira already records every worklog your team enters. It does not add them up for you in any way you can group, compare, share or export.

Worklog Reports reads those native worklogs and answers four questions:

• How many hours, and on what. Grouped by person, work item, epic, component or release, over any period.
• Against what was planned. Original estimate against actual, per work item and rolled up per epic, with the correction factor spelled out.
• Against what was budgeted. An hours budget per project, with the date it is projected to run out.
• Who owed it. A punctuality view built on working days.

What it does not do. It does not enter time. There is no timer, no timesheet form, no approval workflow. It reads what Jira already holds. It also does not know about leave unless you fill in the capacity calendar described below.

Requirements

• Jira Cloud. There is no Data Center or Server version.
• A Jira site where people log work with the native worklog feature (Log work on a work item). Time recorded only inside a third party app that does not write native worklogs will not appear.
• No external account, no server, no configuration file. The app runs entirely on Atlassian infrastructure.

Installing

1. Open the listing on the Atlassian Marketplace and choose Get it now, or in Jira go to Apps > Explore more apps and search for Worklog Reports for Jira.
2. Pick the site to install it on and confirm the permissions.
3. After installation the app appears under Apps > Worklog Reports in the Jira top navigation.

Installing requires Jira administrator rights. Reading a report does not.

First run: building the report

The app does not read Jira every time you open a page. It builds its figures on a scheduled daily run and stores them, so a report opens in one step no matter how large the site is.

Right after installation there is nothing stored yet. A Jira administrator opens Apps > Worklog Reports and presses Rebuild now. The button is only shown to administrators, because a rebuild walks the whole worklog stream of the site.

The rebuild takes from a few seconds to a few minutes depending on how much history the site holds. When it finishes, the page shows the date and time of the run and the time zone it used.

One thing worth knowing. Jira's worklog change feed is eventually consistent: work logged in the last minute or two may not yet be visible to a rebuild started immediately afterwards. It is picked up by the next one. Every run rebuilds the whole window rather than adding a delta, so nothing is lost permanently and nothing is counted twice.

Reading a report

Choose a project, a period and a grouping.

Periods. This week, last week, this month, last month, this quarter, this year, and a custom range. Days are cut in your site's own time zone, taken from Jira, and not in UTC. A worklog entered at 1 am in Paris belongs to that day and not to the day before.

Groupings.

Person filter. Restrict the report to one person. The filter restricts, it does not recompute: shares and totals stay those of the whole period, so a search box can never make somebody look like they did 100 % of the work.

One deliberate limit. Person and work item are stored side by side, not crossed. Under a person filter the work item view says so rather than showing a figure it cannot justify.

Comparison with the previous period. Each total can be shown against the equivalent preceding period, so "40 hours" becomes "40 hours, up from 31".

Sorting and searching. Column headers sort, and the search box filters rows. Both are carried into the CSV export, so an exported file always matches what you were looking at.

Estimates against actual

Where a work item carries an original estimate, the report shows estimate against actual, per item and rolled up per epic, with the correction factor (actual divided by estimate).

Three limits are printed on the view itself, because a number without them is misleading:

• An estimate belongs to the whole work item, while the actual belongs to the period you selected.
• The estimate read is today's, not the one set at the start.
• Not estimated is not estimated at zero. Unestimated items are counted separately and never folded in as zeros.

Budgets

Set an hours budget per project. The report shows consumption against it and, more usefully, the date the budget is projected to run out at the current pace.

A budget already blown is a fact. A budget that will be blown on 14 October is a decision. Where the pace cannot support a projection, the app says why rather than drawing a line.

Capacity calendar

Optional, and the one thing the app cannot infer. Enter working days, public holidays and known absences, and two things change:

• Per person and per period figures are read against real available time instead of a theoretical full week.
• Somebody on leave stops showing up as silence.

Without it, the app declines to score completeness rather than guessing.

Punctuality, and what is deliberately not scored

The punctuality view measures the delay between the day the work was done and the day the entry was made, counted in working days. Work done on Friday and logged on Monday is one day late, not three.

This is the only recording quality figure the app scores, and there are reasons for that:

• Completeness is not scored. Hours against a full working day needs a capacity calendar. Where you have not provided one, scoring it would amount to accusing whoever took a fortnight off.
• "The right value" is not scorable at all. Nothing in Jira knows that four hours was the true figure.

The view is built so that it measures without ranking people:

• Rows come out in alphabetical order. There is no rank column, and none in the export either.
• The team median is shown above the rows, so the question is "is this person unusual here", not "who is last".
• Nothing is coloured red or green.
• Somebody with fewer than five measurable entries is listed but not measured. Three entries can put anybody first.

Anomalies are shown separately: impossible days, work logged on non working days, days made entirely of whole hours. They are a place to look, never a mark against somebody.

Punctuality is also the one figure that survives not knowing about absences. Somebody on leave makes no entries, so they add nothing to the numerator and nothing to the denominator. A half time person logging three punctual entries a week scores exactly what a full time person logging five scores.

Saved views and sharing

A saved view stores a project, period, grouping, person filter, sort and search under a name you choose.

Share link. The link carries the view and never a figure. Whoever opens it passes the same permission check on their own account: if they cannot browse the project, they see nothing. This is why sharing works from Apps > Worklog Reports and not from the project tab.

Exporting

• CSV, which opens in Excel with the separators of your language. The export honours the sort and the search currently applied.
• PDF, written by the app itself, with the header repeated on every page.

Both are produced in your browser. Nothing is sent anywhere.

Weekly summary

The app produces a summary of the week at a regular interval and leaves it on the page. It does not email it: a Forge app cannot send mail without declaring an external network destination, which would cost the Runs on Atlassian badge. What you lose is the interruption. What you keep is the content and the history.

Languages

English, French and Spanish, including the tab title Jira shows above the app. The app follows the language of your Jira profile. Exports follow the language of the page you exported from, including the decimal separator.

Reporting a problem or suggesting a feature

Every screen, including one that failed to load, carries a Report or suggest button at the top.

The report is stored on your site and a Jira administrator can review it. It carries a fixed, named list of context fields and nothing else: app version, language, tab, period name, grouping, project id, browser, and the error. No hours, no names, no work item titles. The panel shows you exactly what will be stored, produced by the same function that stores it.

If a support form is configured, the button also opens it prefilled in a new tab. The app itself makes no call: it hands the link to your browser, which follows it if you decide to.

Security and data

• Runs on Atlassian. The app declares no external domain and makes no outbound call. Your data never leaves Atlassian infrastructure.
• Everything is stored in Forge storage, inside Atlassian, tied to your site.
• Reports are stored per project and served only to readers who hold BROWSE_PROJECTS on that project. The scheduled build runs with app permissions and therefore sees every worklog, which is exactly why the per project check exists on the read path.
• A worklog the app cannot attribute to a project is dropped rather than pooled somewhere a reader might not be allowed to see.
• The permission check is the only call the interface makes to Jira, and it carries no report data.

Uninstalling the app removes its stored data with it. The native Jira worklogs are untouched: the app never writes to them.

The privacy policy is a separate page, linked from the Marketplace listing.

Troubleshooting

The report is empty. Check that a rebuild has run (the page shows the date of the last one), that the period you chose contains logged work, and that you can browse the project.

Work logged today is missing. Figures come from the last scheduled build. Run Rebuild now, and bear in mind Jira's change feed lags by a minute or two.

Someone sees fewer projects than I do. That is the permission check doing its job. Reports are served per project against the reader's own BROWSE_PROJECTS.

Time tracked in another app does not appear. The app reads native Jira worklogs only.

A person shows no punctuality figure. Their entries carried no creation date, or they have fewer than five measurable entries. The app prints a dash rather than a zero, because "we could not measure" is not "zero".

The tab is hidden behind the ... overflow. On a narrow screen Jira moves extra tabs into the overflow menu. The app is also reachable from Apps > Worklog Reports in the top navigation.