# Reports & dashboards

Source: https://iskue.com/docs/reports-dashboards/

> Every Iskue report explained — burndown, velocity, flow metrics, workload — plus CSV exports, dashboard gadgets, sharing and the sprint roadmap.

Iskue has two reporting surfaces: a per-project **Reports** page at `/projects/{key}/reports`, backed by read-only API endpoints, and user-composed **dashboards** at `/dashboards`, assembled from a small gadget catalogue. A read-only **sprint roadmap** timeline completes the picture. This page describes every report, its exact data window and caps, which four reports export CSV, and how dashboard sharing works.

> **Note:** **Edition:** configurable dashboards (`/api/v1/dashboards/**`) require the **Professional** edition; the per-project reports and the personal **My Work** overview (`/api/v1/dashboard`) are available in every edition.

## Conventions that apply everywhere

- All project report endpoints live under `/api/v1/projects/{projectKey}` and require project membership.
- **Unestimated tickets count as 1 point** in every points-based figure: burndown scope, velocity, workload points and sprint-report points.
- Flow reports (burndown, cycle time, cumulative flow, created vs resolved) are computed from recorded status-change **history**, matched by status id and grouped by status **category** (`TODO`, `IN_PROGRESS`, `DONE`). Renaming a status therefore does not corrupt past data, and "done" always means the **last** entry into a DONE-category status — a ticket that was reopened and finished again counts on its final finish.
- Dates bucket in UTC; weekly reports use ISO weeks, labelled by their Monday, oldest first and zero-filled.
- Row-level reports (the sprint report and cycle-time rows) omit tickets hidden from you by security levels.

## The Reports page

Open a project and choose **Reports** (route `/projects/{key}/reports`). The heading reads "Reports — N tickets"; each section renders only when it has data. Everything below is fetched with `GET` requests under `/api/v1/projects/{projectKey}`.

| Report | Endpoint | Window and cap | CSV |
| --- | --- | --- | --- |
| Statistics (status / type / priority) | `/stats` | all tickets in the project | — |
| Sprint report | `/sprints/{sprintId}/report` | one sprint | — |
| Burndown | `/sprints/{sprintId}/burndown` | sprint start → end date or today | — |
| Velocity | `/velocity` | all completed sprints | — |
| Cumulative flow | `/cumulative-flow` | last 14 days; first **500** tickets in rank order | — |
| Created vs resolved | `/created-vs-resolved` | last 8 ISO weeks; first **500** tickets in rank order | Yes |
| Cycle & lead time | `/cycle-time` | **100** most recently finished tickets; 50 rows returned | Yes |
| Throughput | `/cycle-time` (same payload) | last 8 ISO weeks | Yes |
| Workload by assignee | `/workload` | every open ticket (no cap) | Yes |
| Time tracking | `/time-report` (optional `sprintId` query parameter) | project, or one sprint | — |

**Statistics** — `/stats` returns the total ticket count plus exact counts **by status** (in workflow order, zero-count statuses included), **by type** and **by priority**, rendered as bar rows with percentages. These are precise database counts — unlike the dashboard statistics gadget, which is capped (see below).

**Sprint report** — pick any sprint from the selector. The report shows the sprint's goal, points done out of total, and two tables — **done** and **open** — each row carrying key, title, status and points. For a `COMPLETED` sprint only finished tickets remain attached (unfinished ones return to the backlog at completion), so the open table is empty and `donePoints` is the sprint's delivered velocity.

### Burndown

The burndown is computed from status-change history, not from a stored daily snapshot. Scope is the sum of points of tickets currently in the sprint; the chart plots remaining points for each day from the sprint start to its end date (or today, whichever is earlier). A ticket burns down on the day of its **last** entry into a DONE-category status, matched by status id with a name fallback for legacy rows — so the chart survives status renames. Tickets already done with no recorded transition count as done from creation. The Reports page shows the active sprint's burndown automatically; any sprint can be charted via the dashboard gadget.

> **Warning:** Burndown requires a started sprint. Requesting it for a sprint with no start date returns a `409` with the message `Sprint has not been started yet`.

**Velocity** — `/velocity` lists completed sprints in creation order with the points completed in each (`completedPoints`), rendered as "Velocity (completed points per sprint)". Because unfinished tickets leave the sprint at completion, the points of tickets still attached are exactly the delivered work.

**Cumulative flow (14 days)** — stacked columns showing how many tickets sat in each category — to do, in progress, done — at the end of each of the last 14 UTC days. Category-at-day is derived from history: a ticket is DONE after its last entry into a DONE status, IN_PROGRESS between its first IN_PROGRESS entry and that, and TODO from creation otherwise. The scan is capped at the first **500** tickets in board rank order.

**Created vs resolved (last 8 weeks)** — intake versus completion per ISO week: `created` counts tickets by creation date, `resolved` counts last entries into a DONE-category status, both derived from the same history mechanism as the CFD and subject to the same **500-ticket** cap in rank order. Paired columns per week make a growing or shrinking backlog visible at a glance.

### Cycle & lead time, throughput and the control chart

This report scans up to the **100 most recently finished** tickets (DONE-category status, most recently updated first), skipping any you cannot see. **Lead time** is creation → last entry into done; **cycle time** is first entry into an IN_PROGRESS status → done, and is null for tickets that jumped straight to done. Tickets done since creation with no recorded transition are excluded — there is no flow to measure. The `count` and both averages cover all measured tickets; the response returns at most **50** rows and the on-page table shows the first 10. **Throughput** buckets the same tickets by the ISO week they were finished — the last 8 weeks, oldest first, zero-filled. Beneath it, a **control chart** plots each finished ticket as a dot (cycle days, falling back to lead days) against its finish date, with a 5-point rolling average line and the overall average as a dashed guide.

### Workload by assignee

`/workload` groups every open (non-DONE) ticket by assignee: open count, open points and how many sit in an IN_PROGRESS status. Rows sort by open points descending with the unassigned bucket always last. This report scans the whole project — no cap.

**Time tracking** — `/time-report` sums logged, remaining and original estimate seconds across the project, or across one sprint when `?sprintId=` is given, along with how many tickets carry any tracking data. The Reports page also shows a satisfaction summary when CSAT ratings exist (ratings are submitted by ticket reporters — see the [Service desk & portal](https://iskue.com/docs/service-desk-portal/) page).

## CSV downloads

Exactly four reports have a CSV download on the Reports page: **workload**, **created vs resolved**, **cycle & lead time** and **throughput**. Files are generated entirely in the browser from the already-loaded report data — RFC 4180 quoting, UTF-8 with a byte-order mark so spreadsheet applications detect the encoding.

| Button | Filename | Columns |
| --- | --- | --- |
| Download CSV (workload) | `{key}-workload.csv` | `assignee,open,openPoints,inProgress` |
| Download CSV (created vs resolved) | `{key}-created-vs-resolved.csv` | `weekStart,created,resolved` (8 rows) |
| Download CSV (cycle time) | `{key}-cycle-time.csv` | `key,title,leadDays,cycleDays,doneAt` (up to 50 rows) |
| Throughput CSV | `{key}-throughput.csv` | `weekStart,done` (8 rows) |

## Dashboards

There are two dashboard surfaces. The personal **My Work** overview at `/dashboard` (`GET /api/v1/dashboard`) is fixed and always available. Configurable gadget dashboards live at `/dashboards`, backed by the `/api/v1/dashboards` resource (Professional edition): list (`GET`), read one (`GET /{id}`), read your default (`GET /default`), list the gadget catalogue (`GET /catalog`), create (`POST`), rename or re-scope (`PATCH /{id}`), replace the gadget set (`PUT /{id}/gadgets`), set default (`POST /{id}/default`), delete (`DELETE /{id}`), and compute one gadget's data (`POST /gadget-data`).

### My Work — the personal overview

My Work aggregates your assigned tickets across every project you belong to (archived projects are skipped): open and total counts, open work by category and by project, and a table of your open tickets sorted highest priority first, then most recently updated — capped at the top **50**.

### Creating and laying out dashboards

Create a dashboard from `/dashboards` with a name (maximum 120 characters), a sharing scope and **1–3 columns** (default 2). The first dashboard you create becomes your default; until then a built-in, read-only "My Work" dashboard with a single *Assigned to me* gadget stands in. In edit mode, add gadgets from the catalogue, move them with the arrow controls, give each an optional title (maximum 120 characters), and save — saving replaces the dashboard's whole gadget set in one call.

### Sharing

Two scopes exist: `PRIVATE` (visible to the owner only) and `ALL_USERS` (visible to every signed-in user). Group- or project-scoped sharing does not exist. Only the owner can modify, re-share or delete a dashboard; a dashboard shared with all users is strictly view-only for everyone else.

### The gadget catalogue

| Gadget | Type | Data source | Configuration |
| --- | --- | --- | --- |
| Assigned to me | `ASSIGNED_TO_ME` | your My Work overview | none |
| Filter results | `FILTER_RESULTS` | a saved filter or a TQL query | `savedFilterId` or `query`; `limit` 1–50, default 10 |
| Statistics | `STATS_BY` | TQL-scoped ticket counts grouped by a dimension | `dimension`, optional `query` |
| Sprint burndown | `SPRINT_BURNDOWN` | the burndown report | `projectKey` and `sprintId` |
| Note | `NOTE` | none — static note text rendered client-side | `text` |

The statistics gadget groups by `STATUS_CATEGORY` (default), `STATUS`, `TYPE`, `PRIORITY` or `ASSIGNEE`, counting over at most **1,000** matching tickets, largest buckets first. All gadget data inherits your project visibility, and a saved filter can only be used if it is yours or shared. A misconfigured gadget shows its own error message rather than failing the whole dashboard render.

*Computing one gadget's data — the same call drives the dashboard view and the configuration preview.*

```json
POST /api/v1/dashboards/gadget-data
{
  "type": "STATS_BY",
  "config": {
    "dimension": "ASSIGNEE",
    "query": "project = CORE AND status != Done"
  }
}
```

> **Note:** There is deliberately no created-vs-resolved gadget: it would need a per-ticket history scan on every dashboard render. Use the project report at `/projects/{key}/reports` instead.

## Sprint roadmap timeline

`/projects/{key}/roadmap` draws a **read-only** timeline of every sprint that has a start date: one bar per sprint positioned across the overall date span, coloured by state — planned grey, active green, completed blue — with a vertical "today" marker when today falls inside the span. Below the timeline, an epics section shows each epic's progress (done/total tickets, points and due date where set), and sprints without dates are listed under "unscheduled". The roadmap offers no editing; change sprint dates from the backlog's sprint management.

## Caps at a glance

| Surface | Cap |
| --- | --- |
| Cycle & lead time / throughput | 100 most recently finished tickets scanned; 50 rows returned |
| Cumulative flow, created vs resolved | first 500 tickets in rank order |
| Statistics gadget | 1,000 matching tickets |
| Filter results gadget | 50 rows maximum per gadget |
| My Work open-ticket table | top 50 tickets |
| Workload, project statistics, velocity, burndown | uncapped |
