Paginated Reports: Development Techniques

Report Naming: [Department][ReportType][Description]_v[Version] Example: Finance_Invoice_CustomerInvoice_v2.rdl

Parameter Naming: Use descriptive names with prefixes

• pm_StartDate (pm = parameter)
• ds_Customers (ds = dataset)
• sp_GetOrderDetails (sp = stored procedure)

Shared Dataset Naming: [Source]_[Entity] Example: SQL_Customers, SQL_Orders, Azure_SalesData

Folder Structure in Power BI Service: /Reports/Finance/

• Invoices
• Financial Statements
• Budget Reports /Reports/Operations/
• Inventory Reports
• Fulfillment Reports /Shared Datasets/
• Finance Datasets
• Operations Datasets

### Version Control

```text
RDL Version Control with Git:

1. Export .rdl files from Power BI Report Builder
   File → Save As → Local directory in Git repo

2. Commit changes with meaningful messages
   git add Finance_Invoice_CustomerInvoice_v2.rdl
   git commit -m "Added customer tier discount column"

3. Use branches for development
   git checkout -b feature/add-tax-column
   
4. Merge to main branch after testing
   git checkout main
   git merge feature/add-tax-column

5. Tag releases
   git tag -a v2.0 -m "Release version 2.0"

6. Deploy from version control
   - Use Azure DevOps or GitHub Actions
   - Automate deployment to Dev/Test/Prod workspaces

Security Best Practices

☑ Dataset Security:
  ☐ Use shared datasets with RLS applied
  ☐ Never embed credentials in RDL files
  ☐ Use gateway connections for on-premises data
  ☐ Implement least-privilege database accounts

☑ Report Access:
  ☐ Assign reports to appropriate workspaces
  ☐ Use workspace roles (Admin, Member, Contributor, Viewer)
  ☐ Leverage Azure AD groups instead of individual users
  ☐ Audit report access regularly

☑ Parameter Security:
  ☐ Validate parameter inputs to prevent SQL injection
  ☐ Use parameterized queries (not dynamic SQL)
  ☐ Hide sensitive parameters (e.g., internal IDs)
  ☐ Implement parameter defaults that are secure

Change Management

Report Change Process:

1. Request
   - User submits change request
   - Business analyst reviews and approves

2. Development
   - Developer creates feature branch
   - Implements changes in Report Builder
   - Tests with sample data

3. Testing
   - QA tests report in Dev workspace
   - Validates parameters, layout, data accuracy
   - Performance testing with production data volumes

4. Approval
   - Business owner reviews test output
   - Approves for production deployment

5. Deployment
   - Publish to Production workspace
   - Update subscriptions if parameters changed
   - Notify users of changes

6. Monitoring
   - Monitor execution logs for errors
   - Collect user feedback
   - Address issues promptly

Troubleshooting Guide

Issue 1: Slow Report Rendering

Symptoms:

• Report takes minutes to load
• Timeout errors

Diagnosis:

-- Check dataset execution time
SELECT 
```text
DataSetName,
AVG(DataRetrievalDurationMS) AS AvgQueryTime,
MAX(DataRetrievalDurationMS) AS MaxQueryTime```
FROM ExecutionLog
WHERE ReportName = 'SlowReport'
GROUP BY DataSetName;

Common Causes:

• Large unfiltered datasets (> 50,000 rows)
• Subreports in detail rows
• Complex expressions evaluated per row
• Missing indexes on filtered columns

Resolution:

• Add parameters to filter data at source
• Replace subreports with JOINs
• Move calculations to SQL query
• Add indexes: CREATE INDEX IX_Orders_OrderDate ON Orders(OrderDate)

Issue 2: Page Breaks Not Working

Symptoms:

• Report renders as single page
• Page breaks ignored

Resolution:

1. Check row group properties: Right-click group → Group Properties → Page Breaks
2. Enable "Between each instance of a group"
3. Ensure interactive rendering respects page breaks: Report Properties → Page Setup → "Enable page breaks for interactive rendering"
4. Test in PDF export (page breaks more reliable in printed formats)

Issue 3: Subscription Failures

Symptoms:

• Email not received
• Subscription shows "Failed" status

Diagnosis:

## Check subscription status via API
$subscriptions = Invoke-PowerBIRestMethod `
```text
-Url "groups/$workspaceId/reports/$reportId/subscriptions" `
-Method Get | ConvertFrom-Json

$subscriptions.value | Where-Object { $_.state -eq "Failed" } | Format-List

**Common Causes**:

- Invalid parameter values
- Report execution timeout
- Missing permissions
- Capacity overload


**Resolution**:

- Validate parameter defaults
- Increase timeout in Premium capacity settings
- Ensure service principal has permissions
- Schedule during off-peak hours


## Issue 4: Export Format Issues

![Issue 4: Export Format Issues](/images/articles/power-bi/2025-08-18-paginated-reports-development-techniques-ctx-2.svg)

**Symptoms**:





- Excel export has misaligned columns
- PDF has cut-off text
- CSV missing data


**Resolution**:

**For Excel**:

- Avoid merged cells in tablix
- Set specific column widths
- Use simple table layouts (not complex matrices)


**For PDF**:

- Set page size explicitly: Report Properties → Page Setup → Paper Size
- Check margins: ensure content fits within printable area
- Test with different content lengths


**For CSV**:

- CSV exports detail rows only (no grouping/aggregation preserved)
- Use "IncludeHeaders" option in rendering settings
- Consider exporting from Excel format for more control


## Best Practices Summary


> **Architecture Overview:** ☑ Design:


## Architecture Decision and Tradeoffs

![Architecture Decision and Tradeoffs](/images/articles/power-bi/2025-08-18-paginated-reports-development-techniques-ctx-3.svg)

When designing business intelligence solutions with Power BI, consider these key architectural trade-offs:

| Approach | Best For | Tradeoff |
|----------|----------|----------|
| Managed / platform service | Rapid delivery, reduced ops burden | Less customisation, potential vendor lock-in |
| Custom / self-hosted | Full control, advanced tuning | Higher operational overhead and cost |

> **Recommendation:** Start with the managed approach for most workloads and move to custom only when specific requirements demand it.

## Validation and Versioning

- Last validated: April 2026
- Validate examples against your tenant, region, and SKU constraints before production rollout.
- Keep module, CLI, and SDK versions pinned in automation pipelines and review quarterly.

## Security and Governance Considerations

- Apply least-privilege access using RBAC roles and just-in-time elevation for admin tasks.
- Store secrets in managed secret stores and avoid embedding credentials in scripts or source files.
- Enable audit logging, data protection policies, and periodic access reviews for regulated workloads.

## Cost and Performance Notes

- Define budgets and alerts, then monitor usage and cost trends continuously after go-live.
- Baseline performance with synthetic and real-user checks before and after major changes.
- Scale resources with measured thresholds and revisit sizing after usage pattern changes.

## Official Microsoft References

- https://learn.microsoft.com/power-bi/
- https://learn.microsoft.com/power-bi/guidance/
- https://learn.microsoft.com/fabric/

## Public Examples from Official Sources

- These examples are sourced from official public Microsoft documentation and sample repositories.
- Documentation examples: https://learn.microsoft.com/power-bi/
- Sample repositories: https://github.com/microsoft/PowerBI-Developer-Samples
- Prefer adapting these examples to your tenant, subscriptions, and governance requirements before production use.

## Key Takeaways

- **Paginated reports excel at operational reporting** (invoices, statements, detailed listings) where pixel-perfect layouts and printing are required
- **Use stored procedures** for dataset optimization, caching, and maintainability
- **Cascading parameters** provide intuitive user experience while reducing query scope
- **Subreports are expensive** when used in detail rows; prefer JOINs or single-query approaches
- **Test with production data volumes** to identify performance issues before deployment
- **Shared datasets improve performance** via caching and provide consistency across reports
- **Version control RDL files** in Git for change tracking and deployment automation
- **Subscriptions require careful scheduling** to avoid capacity overload and ensure timely delivery
- **Export formats have different fidelity**: PDF preserves layout, Excel for data analysis, CSV for integration
- **Embedding in applications** requires Premium capacity and proper token management






## Next Steps

1. Install Power BI Report Builder from Microsoft website
2. Design first paginated report with parameters and stored procedure dataset
3. Test report with production-like data volumes
4. Configure email subscription for automated delivery
5. Publish to Premium workspace and assign permissions
6. Monitor execution logs for performance issues
7. Implement version control for .rdl files
8. Create shared datasets for frequently used queries
9. Document report parameters and data sources
10. Train end users on parameter usage and export options


## Additional Resources

- [Power BI Paginated Reports Overview](https://learn.microsoft.com/power-bi/paginated-reports/paginated-reports-overview)
- [Report Builder Tutorial](https://learn.microsoft.com/power-bi/paginated-reports/paginated-reports-quickstart-aw)
- [RDL Expression Reference](https://learn.microsoft.com/sql/reporting-services/report-design/expression-reference-report-builder)
- [Paginated Reports Best Practices](https://learn.microsoft.com/power-bi/guidance/report-paginated-best-practices)
- [Power BI REST API for Paginated Reports](https://learn.microsoft.com/rest/api/power-bi/reports)
- [Embedding Paginated Reports](https://learn.microsoft.com/power-bi/developer/embedded/embed-paginated-reports)
- [SSRS Migration to Power BI](https://learn.microsoft.com/power-bi/guidance/migrate-ssrs-reports-to-power-bi)


---

*Precision. Performance. Production.*