> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timetracker.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a report

> Create a custom report step by step: pick a data source, period, columns, filters, layout, grouping, sorting and totals, then preview and save it.

Build a report by answering nine questions in the builder panel, watching the live preview, then saving it. Nothing is written until you press **Save**.

## Before you start

You need `report.create` and a Pro plan. Saving a report definition is a Pro feature – see [/concepts/plans-and-features](/concepts/plans-and-features).

If you cannot create reports, the page shows **"You can't create reports"** with **"Ask a workspace admin for report access to build a new report."**

## How to build a report

<Steps>
  <Step title="Open the builder">
    Go to **Reports** and click **New report**. The builder opens with an empty draft named **Untitled report**.
  </Step>

  <Step title="Name it">
    Click the pencil next to the name in the toolbar, type a name, and press Enter. A report with no name cannot be saved.
  </Step>

  <Step title="Pick the data source">
    Open the **Data** section and choose a source. Hover any option to read what it covers. Your choice decides every column, filter and grouping the rest of the builder offers.
  </Step>

  <Step title="Set the period">
    Open **Period**. Choose **Relative** and pick a rolling window such as **This month**, or choose **Fixed range** and pick a start and end date.
  </Step>

  <Step title="Choose columns">
    Open **Columns**, click **Add column**, and pick the fields and figures you want. Drag the grip to reorder them. Type in a row to rename its header.
  </Step>

  <Step title="Add filters (optional)">
    Open **Filters** and click **Add group**, then **Add condition**. Each condition is *include or exclude*, a field, an operator and a value.
  </Step>

  <Step title="Choose a layout">
    Open **Layout**. **Plain** is a flat table, **Subgroups** nests rows under grouping levels, **Pivot** builds a matrix.
  </Step>

  <Step title="Group and sort">
    With **Subgroups** chosen, open **Grouping** and add up to three levels. Open **Sorting** and add up to three sort rules.
  </Step>

  <Step title="Check the preview">
    The table on the right runs live as you edit. If it says **"Nothing to preview yet"**, read the reason underneath and fix it.
  </Step>

  <Step title="Save">
    Click **Save report**. On an existing report you get two buttons: **Save changes** overwrites it, **Save as new report** makes a copy.
  </Step>
</Steps>

## The builder screen

The builder has two halves. The left panel configures the report. The right side is a live preview of the result.

The toolbar above the preview holds:

| Control                                  | What it does                                                         |
| ---------------------------------------- | -------------------------------------------------------------------- |
| Panel icon                               | Hides or shows the builder panel, so the preview gets the full width |
| Report name                              | Click the pencil to rename inline. Enter or Escape closes the field. |
| **Unsaved changes**                      | A chip that appears the moment the draft differs from what is saved  |
| **Save changes**                         | Overwrites the existing report. Disabled when nothing changed.       |
| **Save report** / **Save as new report** | Creates a new report from the current draft                          |
| **Expand all** / **Collapse all**        | On a grouped report, opens or closes every group at once             |

<Warning>
  If you leave the page with unsaved changes, your browser asks you to confirm. The draft is not kept – close the tab and the edits are gone.
</Warning>

## The nine builder sections

Each section shows a summary chip on its header so you can read the whole report shape without opening anything.

### 1. Data

One dropdown listing the eight sources. Each option has a tooltip describing what it covers.

Switching source is not free. Columns, filters, grouping, sorting and date basis that do not exist on the new source cannot come with you. TimeTracker asks first:

> **Switch to Invoices?**
> Some settings in this report don't exist for Invoices and will be removed. Anything that also exists for Invoices is kept.

The dialog lists exactly what will be dropped, bucket by bucket – columns, filters, grouping, sorting and date basis. It also tells you that the new source's default columns and sorting will be applied wherever the switch would leave the report empty. Cancel and the source snaps back.

### 2. Visibility

| Option       | Who sees the report                            |
| ------------ | ---------------------------------------------- |
| **Personal** | Only you                                       |
| **Shared**   | Everyone in the workspace who can view reports |

**Shared** is disabled unless you hold report management access, and the panel says so: *"You need report management access to make a report shared."* See [/reports/share-a-report](/reports/share-a-report).

### 3. Period

Two modes. **Relative** picks one of nine rolling windows. **Fixed range** picks a start and end date from the calendar.

A relative period is resolved fresh on every run, so a **This month** report always shows the current month. Full list in [/reports/date-ranges-and-periods](/reports/date-ranges-and-periods).

### 4. Columns

**Add column** opens a searchable catalog grouped by category. Only columns you may see and the source can calculate appear – nothing else is offered.

Each selected column is a row with:

* A **grip** you can drag, or focus and move with the arrow keys. Home and End send it to either end.
* A **rename** box. Leave it blank to keep the standard label.
* An **X** to remove it.

<Note>
  A report must keep at least one column. The last column's remove button is disabled with a tooltip explaining why.
</Note>

### 5. Filters

Filters narrow which records are counted. Groups are joined with **AND**, and conditions inside one group are joined with **OR**.

With no filters the panel reads: *"No filters. The report includes every row in the period."*

Every control and operator is covered in [/reports/report-filters](/reports/report-filters).

### 6. Layout

| Option        | Description in the menu                             |
| ------------- | --------------------------------------------------- |
| **Plain**     | A flat, detailed table – no grouping applied        |
| **Subgroups** | Nest rows under grouping dimensions, with subtotals |
| **Pivot**     | An Excel-style matrix – one metric across two axes  |

Choosing **Pivot** reveals three more fields: **Columns (X)**, **Rows (Y)** and **Metric**. Each one draws from the columns already on the report, and the two axes exclude each other so they can never collide.

### 7. Grouping

Only used by the **Subgroups** layout. Add up to three dimensions and drag them into order. The first is the outer level.

* On a **Plain** report the section says: *"Switch the layout to Subgroups to nest rows into grouping levels."*
* On a **Pivot** report it says: *"Pivot reports use the X and Y axes in the Layout section instead of grouping levels."*

Adding a grouping level also adds it as a column, so the report shows what it groups by.

### 8. Sorting

Add up to three sort rules. Each rule has:

| Control                | Options                                    |
| ---------------------- | ------------------------------------------ |
| Column                 | Any column already on the report           |
| Direction              | **Ascending** or **Descending**            |
| **Empty values first** | A switch that puts blank values at the top |

With no rules, the panel reads *"No sorting – the engine default order."* At three rules the **Add sort rule** button is disabled and the panel says sorting is capped at 3 columns.

### 9. Totals

Three switches:

| Switch               | What it says                                |
| -------------------- | ------------------------------------------- |
| **Grand total**      | A footer row summing the whole report       |
| **Subtotals**        | A subtotal row per grouped section          |
| **Percent of total** | Show each row as a share of the grand total |

## The live preview

The preview runs the draft as you edit. It only runs when the draft is valid – an incomplete draft shows a placeholder instead of an error.

| State                   | What you see                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------ |
| Loading                 | Three shimmer rows                                                                   |
| Valid, no matches       | **"No data for this report."**                                                       |
| Invalid draft           | **"Nothing to preview yet"** with the exact reason                                   |
| More rows than one page | A banner: *"Showing one page of N records. Totals cover the complete filtered set."* |

<Note>
  The banner matters. The rows on screen are one page, but every total is calculated over the whole filtered set – never over the visible page.
</Note>

### Reasons a draft will not preview

| Message                                               | Fix                                                                           |
| ----------------------------------------------------- | ----------------------------------------------------------------------------- |
| A report needs a name                                 | Type a name in the toolbar                                                    |
| Add at least one column                               | Add a column                                                                  |
| Grouping allows at most 3 dimensions                  | Remove a grouping level                                                       |
| Sorting allows at most 3 columns                      | Remove a sort rule                                                            |
| Metric "x" is not available yet                       | That figure cannot be calculated on this source – remove it, or switch source |
| Pivot needs a distinct X and Y dimension and a metric | Fill all three pivot fields                                                   |
| A fixed period needs a start and end date             | Pick both dates                                                               |
| The start date is after the end date                  | Swap the dates                                                                |

## Drilling into a total

On a grouped report, click a group's subtotal to open a panel on the right listing the records behind it. Its header is the group name, with *"Entries behind this total that you can view."*

Each entry shows the date, the duration, the member, project and task, the description, whether it is billable, and how it was captured. Billing and cost rates appear only if your role can see them.

If some records are outside your reach, a footer says how many: *"N more entries aren't shown because you don't have access to them."* When none are visible at all it reads *"No entries you can view for this total."*

## Example

Priya Raman wants this month's hours per project for Northwind Studio.

<Steps>
  <Step title="New report">Reports → **New report**, named `Hours by project – live`.</Step>
  <Step title="Data">Source: **Time entries**.</Step>
  <Step title="Period">Relative → **This month**.</Step>
  <Step title="Columns">Reported time, Billable time, Non-billable time, Entries.</Step>
  <Step title="Filters">None – she wants everything.</Step>
  <Step title="Layout">**Subgroups**.</Step>
  <Step title="Grouping">**Project**, then **Client**.</Step>
  <Step title="Sorting">Reported time, Descending.</Step>
  <Step title="Save">**Save report**.</Step>
</Steps>

Bluebird Coffee – Website Redesign lands at the top with 62 hours, of which 58 are billable. Sarah Lin's 3 hours on "Homepage wireframes" are part of that subtotal, and clicking it shows them.

## Permissions

| Action                                    | Capability                        |
| ----------------------------------------- | --------------------------------- |
| Open the builder                          | `report.create`                   |
| Save changes to a personal report you own | `report.edit` plus ownership      |
| Save changes to a shared report           | `report.manage`                   |
| Set visibility to **Shared**              | `report.share` or `report.manage` |

Ownership alone is never enough. A personal report needs both ownership and `report.edit`.

## What happens next

A saved report appears in the library straight away. From there you can rename it, duplicate it, share it, schedule it, export it, or archive it. See [/reports/saved-reports](/reports/saved-reports).

## Common questions

<AccordionGroup>
  <Accordion title="Can I start from an existing report instead?">
    Yes. Open any report, change it, and click **Save as new report**. TimeTracker asks for a name and leaves the original untouched.
  </Accordion>

  <Accordion title="Why is a figure I want missing from the column list?">
    Two reasons. Either your role cannot see it – cost and revenue are gated – or the source cannot calculate it. Budget and estimate figures come from the **Projects** source, not from time entries.
  </Accordion>

  <Accordion title="What happens if I switch source halfway through?">
    A dialog lists exactly which columns, filters, grouping, sorting and date basis will be dropped. Anything that exists on both sources is kept. Cancel to stay put.
  </Accordion>

  <Accordion title="Does changing the period change the saved report?">
    In the builder, yes – it is part of the draft you save. In the read-only viewer, no – period changes there are temporary. See [/reports/saved-reports](/reports/saved-reports).
  </Accordion>

  <Accordion title="Why can I only group by three things?">
    Three levels is the cap. Beyond that a table stops being readable and the answer is better found by filtering instead.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Problem                                                        | Fix                                                                                             |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Save report** stays greyed out                               | The draft is invalid. The reason is printed under the preview.                                  |
| **Save changes** is greyed out on a saved report               | Either nothing changed, or you may not edit this report                                         |
| A saved report says it was updated to match the current fields | A field it named no longer exists and was repaired on load. Save the report to keep the repair. |
| Save fails with a permission message                           | The server re-checks every save. You need `report.edit` plus ownership, or `report.manage`.     |

## Related guides

<CardGroup cols={2}>
  <Card title="Report sources" icon="database" href="/reports/report-sources">
    What each source counts and offers.
  </Card>

  <Card title="Report filters" icon="filter" href="/reports/report-filters">
    Every filter field and operator.
  </Card>

  <Card title="Grouping and pivots" icon="folder-tree" href="/reports/grouping-and-pivots">
    Nested rows, subtotals and the pivot matrix.
  </Card>

  <Card title="Date ranges and periods" icon="calendar" href="/reports/date-ranges-and-periods">
    All nine rolling windows plus fixed ranges.
  </Card>

  <Card title="Saved reports" icon="bookmark" href="/reports/saved-reports">
    Rename, duplicate, archive and restore.
  </Card>

  <Card title="Metrics reference" icon="list" href="/reports/metrics-reference">
    Every figure and how it is calculated.
  </Card>
</CardGroup>