Paginated reports (RDL)
Paginated reports are the right answer to a narrow but unavoidable set of requirements:
output that must paginate predictably, print to a fixed layout, carry a regulatory format, or
leave the platform as a PDF or Excel file on a schedule. An interactive Power BI report cannot
do those things well, and trying to make it do them is how teams end up with a report nobody
trusts and a page that prints across four sheets.
Decide the format before building anything:
| Requirement |
Build |
| Explore, filter, cross-highlight, drill |
interactive report — powerbi-create-pbi-report |
| Print to a fixed page size; page headers/footers; page breaks you control |
paginated (RDL) |
| A table of thousands of rows the user will read or export in full |
paginated |
| Invoice, statement, remittance, compliance filing, regulator submission |
paginated |
| Scheduled PDF or XLSX to an inbox or a file share |
paginated + Export To File API |
| Both — a dashboard that drills to a printable detail |
interactive, with a paginated report as the drillthrough target |
Say this out loud when a user asks for "a report that prints properly". The format choice is
the decision that determines whether the rest of the work succeeds.
Prerequisites
| Requirement |
Notes |
| Power BI Report Builder |
Windows. The authoring tool. Download — also the source of the TOM and ADOMD assemblies pbi-agent uses for Desktop work |
| Workspace on Fabric capacity or Premium / PPU |
Paginated reports do not run in a Pro-only workspace |
| Build permission on the data source |
Semantic model, SQL, or whatever the dataset queries |
fab CLI |
For deploy, export and workspace plumbing — powerbi-fabric-cli |
RDL structure
An .rdl file is XML. That matters: it is diffable, scriptable and reviewable, so paginated
reports belong in source control alongside the PBIP projects. The parts that carry the design:
| Element |
What it is |
Where people go wrong |
| DataSource |
the connection |
hardcoded server/workspace that breaks on deploy — parameterise or rebind at deploy time |
| DataSet |
one query + its field list |
one giant dataset feeding every region of the page; split by region so a slow query does not block the whole render |
| ReportParameters |
user or caller input |
no default and no available-values list, so the report cannot render unattended or be exported by API |
| Tablix |
table / matrix / list |
the single most common source of pagination defects — see below |
| PageHeader / PageFooter |
repeats per physical page |
referencing a dataset field (not allowed outside the body) instead of a report variable or parameter |
| Report page setup |
size, orientation, margins |
body width wider than page width minus margins — the cause of blank alternating pages |
| Subreport |
another RDL rendered inline |
executed once per row when placed in a detail group; a reliable way to make a report take ten minutes |
Pagination defects, and their causes
These account for most "the report prints wrong" tickets:
- Blank pages between every page. Body width exceeds page width minus left and right
margins. Shrink the body, not the margins, and check after any column width change.
- Headers that do not repeat.
RepeatColumnHeaders alone is not enough on a tablix —
the static row in the row-group hierarchy needs KeepWithGroup and RepeatOnNewPage set.
- Page breaks in the wrong place. Set the break on the group, not on the tablix, and
decide explicitly whether the page number resets.
- Totals on the wrong grain. A tablix total aggregates the dataset rows in scope; pass the
scope explicitly in the aggregate rather than relying on the default.
- Interactive sort that does nothing in PDF. Expected — interactive features do not survive
a static render. Sort in the dataset query.
Datasets and parameters
- Push work to the source. Filter in the dataset query, not in the tablix filter. A tablix
filter retrieves every row and then discards it, so the query cost is unchanged and the
render cost grows.
- Against a semantic model, write DAX, not a wrapped SQL query.
powerbi-dax-mastery
applies unchanged. Bound the result — a paginated report over an unbounded EVALUATE on a
real fact table is a capacity incident, not a slow report.
- Every parameter needs a default and a valid-values source if the report will ever be
exported by API or scheduled. A parameter with no default blocks unattended rendering.
- Parameterise the data source for dev → test → prod, or rebind at deploy. Never ship an
RDL whose connection points at a developer's workspace.
- Multi-value parameters need the query to handle an empty selection, which is the case
nobody tests.
Deploy
# Upload / overwrite an RDL into a workspace
fab import "<workspace>.Workspace/<report-name>.PaginatedReport" -i ./reports/Statement.rdl -f
# Confirm it landed, and what it is bound to
fab ls "<workspace>.Workspace"
fab get "<workspace>.Workspace/<report-name>.PaginatedReport"
Confirm the exact item type and import flags with fab import --help for the installed fab
version before a first deploy — item type names have changed across releases. Create any
output directory before an export: fab export does not create intermediate directories.
Deploy rules:
- Deploy to a dev workspace first. A paginated report overwrite is immediate and has no
built-in version history.
- Rebind the data source as part of the deploy, verified — not assumed.
-f suppresses the overwrite prompt. Only use it once you have confirmed what you are
overwriting, and never when sensitivity labels are in play.
Scheduled export (Export To File)
The Export To File REST API renders a paginated report server-side to PDF, XLSX, DOCX, PPTX,
CSV, XML or an image, with parameter values supplied per call. This is how a monthly statement
run or a regulator submission gets automated.
The pattern is asynchronous — three calls, and the middle one is a poll:
POST .../reports/{reportId}/ExportTo with the format and parameter values → returns an
export id
GET .../reports/{reportId}/exports/{exportId} → poll until the status reports success;
it carries a percent-complete and a retry-after
GET .../reports/{reportId}/exports/{exportId}/file → download the bytes
Confirm the current request shape against
Export To File for paginated reports
before writing the client — the payload has gained options over time.
Implementation rules that matter more than the endpoint:
- Honour the retry-after and cap the poll. A fixed-interval poll with no deadline either
hammers the API or hangs forever.
- Fail loudly. An export helper that reports success because polling stopped is worse than
one that raises. Check the terminal status explicitly;
Failed carries a reason — surface it.
- Keep the bearer token out of the process list and the logs. No tokens in command-line
arguments, no tokens echoed on error. Acquire in-process and pass in the header.
- Exports consume capacity, and a month-end run of hundreds of statements is a background
load smoothed over the following day. Estimate it first —
powerbi-fabric-capacity.
- Cap concurrency. Parallel exports are the fastest way to throttle a capacity that was
otherwise healthy.
Migrating from SSRS
An on-premises SSRS RDL usually uploads and runs, which makes the real work easy to
underestimate. What actually needs attention:
| Area |
What changes |
| Data sources |
Shared data sources and shared datasets do not come across the same way; rebind each report |
| Authentication |
Stored credentials and Windows auth give way to Entra ID and, for on-prem sources, a gateway |
| Unsupported features |
Custom assemblies and some expression surface do not run in the service — find these by rendering, not by reading |
| Subscriptions |
SSRS subscriptions become Power BI subscriptions or an Export To File job; email delivery semantics differ |
| Row-level security |
Enforced by the semantic model or the source, not by the report — check it still holds (powerbi-security-rls) |
Migrate a representative sample first — the longest report, the one with subreports, and the
one with the most parameters. Those three find most of the problems.
Related skills
| Need |
Skill |
| Interactive report instead |
powerbi-create-pbi-report, powerbi-report-design |
| Workspace / item deploy plumbing |
powerbi-fabric-cli |
| DAX in the dataset |
powerbi-dax-mastery, powerbi-dax-performance |
| Cost of a scheduled export run |
powerbi-fabric-capacity |
| RLS behaviour under a paginated report |
powerbi-security-rls |
| Delivery and UAT of the output |
powerbi-testing-validation |
1---2name: powerbi-paginated-reports3description: "Author, validate, deploy and export Power BI paginated reports (RDL) — Report Builder, RDL structure, datasets and parameters, pixel-perfect pagination for print and regulatory output, deployment to a Fabric or Power BI workspace, and the Export To File REST API for scheduled PDF/Excel delivery. Use when the user mentions: paginated report, RDL, .rdl, Report Builder, SSRS report, pixel perfect, print-ready report, invoice or statement report, multi-page table, export to PDF, export to file API, RDL parameters, tablix, subreport, migrate SSRS to Power BI."4license: MIT5metadata:6 source: https://skillmd.com/skills/santoshkanthety/powerbi-paginated-reports7---89# Paginated reports (RDL)1011Paginated reports are the right answer to a narrow but unavoidable set of requirements:12output that must paginate predictably, print to a fixed layout, carry a regulatory format, or13leave the platform as a PDF or Excel file on a schedule. An interactive Power BI report cannot14do those things well, and trying to make it do them is how teams end up with a report nobody15trusts and a page that prints across four sheets.1617Decide the format before building anything:1819| Requirement | Build |20|---|---|21| Explore, filter, cross-highlight, drill | interactive report — `powerbi-create-pbi-report` |22| Print to a fixed page size; page headers/footers; page breaks you control | paginated (RDL) |23| A table of thousands of rows the user will read or export in full | paginated |24| Invoice, statement, remittance, compliance filing, regulator submission | paginated |25| Scheduled PDF or XLSX to an inbox or a file share | paginated + Export To File API |26| Both — a dashboard that drills to a printable detail | interactive, with a paginated report as the drillthrough target |2728Say this out loud when a user asks for "a report that prints properly". The format choice is29the decision that determines whether the rest of the work succeeds.3031## Prerequisites3233| Requirement | Notes |34|---|---|35| **Power BI Report Builder** | Windows. The authoring tool. [Download](https://www.microsoft.com/download/details.aspx?id=58158) — also the source of the TOM and ADOMD assemblies `pbi-agent` uses for Desktop work |36| Workspace on **Fabric capacity or Premium / PPU** | Paginated reports do not run in a Pro-only workspace |37| Build permission on the data source | Semantic model, SQL, or whatever the dataset queries |38| `fab` CLI | For deploy, export and workspace plumbing — `powerbi-fabric-cli` |3940## RDL structure4142An `.rdl` file is XML. That matters: it is diffable, scriptable and reviewable, so paginated43reports belong in source control alongside the PBIP projects. The parts that carry the design:4445| Element | What it is | Where people go wrong |46|---|---|---|47| **DataSource** | the connection | hardcoded server/workspace that breaks on deploy — parameterise or rebind at deploy time |48| **DataSet** | one query + its field list | one giant dataset feeding every region of the page; split by region so a slow query does not block the whole render |49| **ReportParameters** | user or caller input | no default and no available-values list, so the report cannot render unattended or be exported by API |50| **Tablix** | table / matrix / list | the single most common source of pagination defects — see below |51| **PageHeader / PageFooter** | repeats per physical page | referencing a dataset field (not allowed outside the body) instead of a report variable or parameter |52| **Report page setup** | size, orientation, margins | body width wider than page width minus margins — the cause of blank alternating pages |53| **Subreport** | another RDL rendered inline | executed once *per row* when placed in a detail group; a reliable way to make a report take ten minutes |5455### Pagination defects, and their causes5657These account for most "the report prints wrong" tickets:5859- **Blank pages between every page.** Body width exceeds page width minus left and right60 margins. Shrink the body, not the margins, and check after any column width change.61- **Headers that do not repeat.** `RepeatColumnHeaders` alone is not enough on a tablix —62 the static row in the row-group hierarchy needs `KeepWithGroup` and `RepeatOnNewPage` set.63- **Page breaks in the wrong place.** Set the break on the *group*, not on the tablix, and64 decide explicitly whether the page number resets.65- **Totals on the wrong grain.** A tablix total aggregates the dataset rows in scope; pass the66 scope explicitly in the aggregate rather than relying on the default.67- **Interactive sort that does nothing in PDF.** Expected — interactive features do not survive68 a static render. Sort in the dataset query.6970## Datasets and parameters7172- **Push work to the source.** Filter in the dataset query, not in the tablix filter. A tablix73 filter retrieves every row and then discards it, so the query cost is unchanged and the74 render cost grows.75- **Against a semantic model, write DAX, not a wrapped SQL query.** `powerbi-dax-mastery`76 applies unchanged. Bound the result — a paginated report over an unbounded `EVALUATE` on a77 real fact table is a capacity incident, not a slow report.78- **Every parameter needs a default and a valid-values source** if the report will ever be79 exported by API or scheduled. A parameter with no default blocks unattended rendering.80- **Parameterise the data source** for dev → test → prod, or rebind at deploy. Never ship an81 RDL whose connection points at a developer's workspace.82- **Multi-value parameters** need the query to handle an empty selection, which is the case83 nobody tests.8485## Deploy8687```bash88# Upload / overwrite an RDL into a workspace89fab import "<workspace>.Workspace/<report-name>.PaginatedReport" -i ./reports/Statement.rdl -f9091# Confirm it landed, and what it is bound to92fab ls "<workspace>.Workspace"93fab get "<workspace>.Workspace/<report-name>.PaginatedReport"94```9596Confirm the exact item type and import flags with `fab import --help` for the installed `fab`97version before a first deploy — item type names have changed across releases. Create any98output directory before an export: `fab export` does not create intermediate directories.99100Deploy rules:101102- Deploy to a dev workspace first. A paginated report overwrite is immediate and has no103 built-in version history.104- Rebind the data source as part of the deploy, verified — not assumed.105- `-f` suppresses the overwrite prompt. Only use it once you have confirmed what you are106 overwriting, and never when sensitivity labels are in play.107108## Scheduled export (Export To File)109110The Export To File REST API renders a paginated report server-side to PDF, XLSX, DOCX, PPTX,111CSV, XML or an image, with parameter values supplied per call. This is how a monthly statement112run or a regulator submission gets automated.113114The pattern is asynchronous — three calls, and the middle one is a poll:1151161. `POST .../reports/{reportId}/ExportTo` with the format and parameter values → returns an117 export id1182. `GET .../reports/{reportId}/exports/{exportId}` → poll until the status reports success;119 it carries a percent-complete and a retry-after1203. `GET .../reports/{reportId}/exports/{exportId}/file` → download the bytes121122Confirm the current request shape against123[Export To File for paginated reports](https://learn.microsoft.com/power-bi/developer/embedded/export-paginated-report)124before writing the client — the payload has gained options over time.125126Implementation rules that matter more than the endpoint:127128- **Honour the retry-after and cap the poll.** A fixed-interval poll with no deadline either129 hammers the API or hangs forever.130- **Fail loudly.** An export helper that reports success because polling stopped is worse than131 one that raises. Check the terminal status explicitly; `Failed` carries a reason — surface it.132- **Keep the bearer token out of the process list and the logs.** No tokens in command-line133 arguments, no tokens echoed on error. Acquire in-process and pass in the header.134- **Exports consume capacity**, and a month-end run of hundreds of statements is a background135 load smoothed over the following day. Estimate it first — `powerbi-fabric-capacity`.136- **Cap concurrency.** Parallel exports are the fastest way to throttle a capacity that was137 otherwise healthy.138139## Migrating from SSRS140141An on-premises SSRS RDL usually uploads and runs, which makes the real work easy to142underestimate. What actually needs attention:143144| Area | What changes |145|---|---|146| Data sources | Shared data sources and shared datasets do not come across the same way; rebind each report |147| Authentication | Stored credentials and Windows auth give way to Entra ID and, for on-prem sources, a gateway |148| Unsupported features | Custom assemblies and some expression surface do not run in the service — find these by rendering, not by reading |149| Subscriptions | SSRS subscriptions become Power BI subscriptions or an Export To File job; email delivery semantics differ |150| Row-level security | Enforced by the semantic model or the source, not by the report — check it still holds (`powerbi-security-rls`) |151152Migrate a representative sample first — the longest report, the one with subreports, and the153one with the most parameters. Those three find most of the problems.154155## Related skills156157| Need | Skill |158|---|---|159| Interactive report instead | `powerbi-create-pbi-report`, `powerbi-report-design` |160| Workspace / item deploy plumbing | `powerbi-fabric-cli` |161| DAX in the dataset | `powerbi-dax-mastery`, `powerbi-dax-performance` |162| Cost of a scheduled export run | `powerbi-fabric-capacity` |163| RLS behaviour under a paginated report | `powerbi-security-rls` |164| Delivery and UAT of the output | `powerbi-testing-validation` |