agentleFS
santoshkanthetysantoshkanthety/powerbi-agent/skills/powerbi-paginated-reports/SKILL.md

powerbi-paginated-reports

Skill3 starsChanged 7 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every parameter needs a default and a valid-values source: if the report will ever be exported by API or scheduled.

    line 76
  2. Distinctive:

    Keep the bearer token out of the process list and the logs: No tokens in command-line arguments, no tokens echoed on error.

    line 130

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

RequirementBuild
Explore, filter, cross-highlight, drillinteractive report — powerbi-create-pbi-report
Print to a fixed page size; page headers/footers; page breaks you controlpaginated (RDL)
A table of thousands of rows the user will read or export in fullpaginated
Invoice, statement, remittance, compliance filing, regulator submissionpaginated
Scheduled PDF or XLSX to an inbox or a file sharepaginated + Export To File API
Both — a dashboard that drills to a printable detailinteractive, 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

RequirementNotes
Power BI Report BuilderWindows. 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 / PPUPaginated reports do not run in a Pro-only workspace
Build permission on the data sourceSemantic model, SQL, or whatever the dataset queries
fab CLIFor 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:

ElementWhat it isWhere people go wrong
DataSourcethe connectionhardcoded server/workspace that breaks on deploy — parameterise or rebind at deploy time
DataSetone query + its field listone giant dataset feeding every region of the page; split by region so a slow query does not block the whole render
ReportParametersuser or caller inputno default and no available-values list, so the report cannot render unattended or be exported by API
Tablixtable / matrix / listthe single most common source of pagination defects — see below
PageHeader / PageFooterrepeats per physical pagereferencing a dataset field (not allowed outside the body) instead of a report variable or parameter
Report page setupsize, orientation, marginsbody width wider than page width minus margins — the cause of blank alternating pages
Subreportanother RDL rendered inlineexecuted 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:

  1. POST .../reports/{reportId}/ExportTo with the format and parameter values → returns an export id
  2. GET .../reports/{reportId}/exports/{exportId} → poll until the status reports success; it carries a percent-complete and a retry-after
  3. 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:

AreaWhat changes
Data sourcesShared data sources and shared datasets do not come across the same way; rebind each report
AuthenticationStored credentials and Windows auth give way to Entra ID and, for on-prem sources, a gateway
Unsupported featuresCustom assemblies and some expression surface do not run in the service — find these by rendering, not by reading
SubscriptionsSSRS subscriptions become Power BI subscriptions or an Export To File job; email delivery semantics differ
Row-level securityEnforced 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

NeedSkill
Interactive report insteadpowerbi-create-pbi-report, powerbi-report-design
Workspace / item deploy plumbingpowerbi-fabric-cli
DAX in the datasetpowerbi-dax-mastery, powerbi-dax-performance
Cost of a scheduled export runpowerbi-fabric-capacity
RLS behaviour under a paginated reportpowerbi-security-rls
Delivery and UAT of the outputpowerbi-testing-validation

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.