paginated-report

# Paginated Reports (RDL)

A paginated report is a print-faithful, multi-page document (invoice, statement, operational list, regulatory filing) defined by a single `.rdl` XML file. The `.rdl` is plain, hand-editable, diff-friendly XML holding everything: data sources, datasets, parameters, page setup, layout, and expressions. Power BI Report Builder is a Windows GUI over this same XML, so a coding agent edits the artifact directly.

This skill teaches the RDL format and its unwritten rules, how to connect to data, the rendering quirks, and a dev loop that confirms a report actually renders. It is the home for everything RDL. For interactive screen-first reports (PBIR), use `reports:create-pbi-report` instead; see "Is paginated the right tool?" in `references/report-structure.md`. This is for Power BI paginated reports (the Power BI service / Fabric), not classic SSRS; the format is shared but the environment differs (see `references/differences-with-ssrs.md`).

## Before building: interview the user

A paginated report is a fixed-format document where the data source, parameters, and delivery target are expensive to change later. Before authoring anything, run a requirements interview using **`references/questionnaire.md`**. Treat it as a dynamic, two-way conversation, not a form: research the data source yourself (inspect it, run candidate DAX, read a similar example), bring concrete options and a quick Enter Data draft for the user to react to, and follow the threads that matter rather than reading a fixed list. Settle the essentials (purpose, data source, target workspace and capacity), reflect back a short brief, then build against it and refine the rest as the draft takes shape.

## Three rules that prevent most breakage

1. **Element order is load-bearing in practice.** Report Builder and the report processor's reader expect the conventional order and fail to load out-of-order children with no useful error (the failure is from the processor, not schema validation, so an XSD validator will not reliably catch a reorder). Preserve the documented order when editing. This is the number-one cause of a broken hand-authored `.rdl`.
2. **Validate after every structural edit.** Run `scripts/validate_rdl.py <file.rdl>` to catch order, name-collision, tablix-count, reference, and unit errors before publishing. A clean pass plus a successful render is the bar for "done".
3. **Reuse a template, do not hand-type from scratch.** The verbose XML (charts especially) is error-prone to write by hand. Copy the closest `assets/*.rdl` starter and change the data source, query, fields, and layout. Regenerate `rd:ReportID` to a fresh GUID when copying.

## Workflow

```
1. Pick a starting template       assets/enter-data-starter.rdl | semantic-model-starter.rdl | sql-starter.rdl
2. Iterate layout offline          edit XML; keep an Enter Data dataset so no live source is hit
3. Validate                        python3 scripts/validate_rdl.py report.rdl
4. Wire the real data source       swap <DataSource>/<DataSet><Query>; keep field names so layout is untouched
5. Validate again                  python3 scripts/validate_rdl.py report.rdl
6. Publish to a workspace          scripts/publish_rdl.sh report.rdl <workspaceId>
7. RENDER AND CONFIRM (hard gate)  scripts/export_rdl.sh <reportId> <workspaceId>  ->  open the PDF
```

Steps 2-3 are local and free. Do the layout work against the Enter Data inline dataset (a fixed handful of typed rows embedded in the `.rdl`) before touching a live source; re-querying a real source on every layout tweak is the biggest time sink. Keep the Enter Data field names identical to the real query's fields so swapping the source touches only the `<DataSource>` and `<DataSet><Query>`, never the layout. Publishing and rendering need a workspace on Premium/Embedded/Fabric capacity.

**Step 7 is the real bar, not step 5.** A green `validate_rdl.py` is necessary but not sufficient: it checks structure, never expressions, field references, or DAX, so a report with a wrong `DataField`, a mistyped measure, a `@`-prefix mismatch, or a parameter pointing at the wrong column passes validation, publishes, and only fails (or renders blank/wrong) at export. So the moment the real source is wired (step 4), render immediately and: confirm the PDF opens with the **expected, non-empty content**; read the export error body if it fails; and verify the data contract by running the exact `EVALUATE`/SQL against the live source (via `semantic-models:dax`) and checking the returned column names and types match the `<Field>` definitions. Do not call a report done on a green validator alone.

## Starting templates (assets/)

- **`enter-data-starter.rdl`**: portrait-letter report with a title header, page-number footer, and a 3-column table bound to an embedded Enter Data dataset. No data source needed; renders in the service with zero config. Best starting point for layout iteration and the fastest thing to test end-to-end.
- **`semantic-model-starter.rdl`**: connects to a Power BI semantic model (PBIDATASET) via DAX, with a single-value `Category` parameter wired through `TREATAS` (plain valid DAX; render-proven against a live model) and a dataset-driven default. Fill the `REPLACE_WITH_*` tokens (dataset GUID, workspace/model names, table/column/measure names).
- **`sql-starter.rdl`**: connects to Azure SQL (SQLAZURE) via T-SQL with a multi-value `Category` parameter. Fill the server/database tokens and adjust the query/fields.
- **`platform-template.json`**: the `.platform` sidecar Fabric Git expects beside an `.rdl` in a `<Name>.PaginatedReport/` folder.

## Scripts (scripts/)

- **`validate_rdl.py`**: stdlib-only structural validator (cross-platform). Checks XML well-formedness, the 2016 root namespace, a valid `rd:ReportID` GUID, top-level element order, `Name` uniqueness, tablix column/row/cell-span invariants, dataset-to-datasource and tablix-to-dataset references, embedded-image references, and dime