/paginated-report

name: paginated-report
description: Author, validate, publish, and test Power BI paginated reports in the RDL format. Automatically invoke when the user mentions "paginated report", "RDL", ".rdl", "Report Builder", "Power BI Report Builder", "SSRS report", "PBIRS", "Power BI Report Server", or asks to "create a paginated report", "build an invoice/statement report", "make a print-perfect report", "connect a paginated report to a semantic model", "edit an RDL file", "publish an .rdl", or "render a paginated report to PDF/Excel".

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 t