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

# Platform Reports

> Browse, run, and manage organization reports; build new custom reports; and edit existing saved report definitions.

Reports hub at `/reports` where users browse, select, run, and download organization reports and platform-provided report templates.

## Overview

The Reports page presents a two-panel interface: a left panel for browsing and selecting reports (via `ReportLibrary` for organization reports and platform templates), and a right panel for configuring parameters and viewing results (`ReportParameters`, `ReportViewer`). A history panel (`ReportHistory`) shows prior executions. The active report definition is fetched via `useReportDefinition`; execution is triggered via `useReportExecution`. The breadcrumb label updates to the selected report's name.

## Who it's for

Access follows your organization's role and module configuration.

## Before you start

* You must be signed in to the platform.
* At least one report or template must exist. Use `/reports/builder` to create a custom report.

## Steps

1. Navigate to `/reports`.
2. Browse the report library on the left and select a report or platform template.
3. Configure any required parameters in the parameters panel.
4. Select an export format if applicable.
5. Click **Run** to execute the report.
6. Review results in the viewer. Prior executions appear in the history panel.

## Key concepts

**Platform Template vs. Organization Report** — Platform templates are provided by the system; organization reports are created via the Report Builder. The run source label indicates which type is active.

**Report execution** — A report run is asynchronous; the viewer shows row count and execution time on completion.

## Creating a report

Users can create a new custom report at `/reports/builder`. The path `/reports/new` is not defined as a distinct route; report creation is handled at `/reports/builder` which renders `ReportBuilder` from `src/platform/reports/ReportBuilder.tsx`.

The Report Builder page provides a visual interface for composing custom reports. Users select one or more source tables via `TableSelector`, choose columns via `ColumnSelector`, define table joins via `JoinBuilder`, and add filter conditions via `FilterBuilder`. A `SQLPreview` component shows the resulting query. Reports have a name, description, and category (defaulting to `custom`). On save, `useCreateReport()` persists the report definition. Created reports are accessible from the reports list at `/reports`.

1. Navigate to `/reports/builder` or select **New Report** from the reports list at `/reports`.
2. Enter a report **Name** and optional **Description**.
3. Select a **Category**.
4. Add one or more source tables using the table selector.
5. Choose columns to include using the column selector.
6. Define joins between tables if needed.
7. Add filter conditions to narrow the result set.
8. Review the SQL preview.
9. Save the report.

**Category** — Reports are tagged with a `report_category` enum value. The default is `custom`.

**SQL preview** — Shows the generated query for transparency and debugging. SME: confirm if this is visible to non-admin users.

## Editing a report

The Edit Report page (`/reports/:reportId/edit`) allows users to modify the metadata and SQL query of an existing saved report definition.

No permission gate is on this route. The page loads the report definition via `useReportDefinition` using the `:reportId` parameter. Updates are applied via `useUpdateReport`. A draft state (`draftOverrides`) holds unsaved edits to `name`, `description`, `category`, and `querySql` before the user saves. `useEntityBreadcrumb` updates the breadcrumb with the report's name.

1. Navigate from the Reports page (`/reports`) by opening a report and clicking its edit action.
2. The form pre-fills with the existing report's data (name, description, category, SQL query).
3. Update the report name, description, and category using the form fields.
4. Modify the `querySql` textarea with the updated report query.
5. Click **Save**. On success, navigate back to the reports list.

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/reports/ReportsPage.tsx
  * src/platform/reports/ReportLibrary.tsx
  * src/platform/reports/useReportDefinition.ts
  * src/platform/reports/ReportBuilder.tsx
  * src/platform/reports/EditReportPage.tsx
  * src/platform/reports/useReportMutation.ts
</Accordion>