> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting — Admin Guide

> Feature: Report Permissions & Export Storage Spec: PF-12 Phase 5 & 6 Last Updated: 2026-03-15

**Feature:** Report Permissions & Export Storage\
**Spec:** PF-12 Phase 5 & 6\
**Last Updated:** 2026-03-15

***

## Overview

This guide covers administrative configuration for the reporting system: permission management, export storage, and operational settings.

## Permission Model

### Four Permission Flags

| Flag           | Description                                     |
| -------------- | ----------------------------------------------- |
| `can_view`     | Read access to report definition and results    |
| `can_run`      | Execute the report with parameters              |
| `can_edit`     | Modify report definition and manage permissions |
| `can_schedule` | Create and manage scheduled report runs         |

### Grant Types

* **User-specific:** Grant permissions to a specific user by UUID
* **Role-based:** Grant permissions to all users with a specific role (org\_admin, staff, site\_admin)

### RLS Enforcement

Permissions are enforced via Row-Level Security using the `pf_is_report_owner_or_admin` SECURITY DEFINER function. Only the report owner or org admins can manage permissions.

## Export & Storage

### Storage Bucket

* **Bucket:** `reports-exports`
* **Path convention:** `{organization_id}/{execution_id}/{filename}.{ext}`
* **Org isolation:** Storage RLS policies ensure users can only access files within their organization

### Signed URLs

* Expiry: **24 hours** from generation
* Generated automatically after export
* Users can re-export or find download links in run history

### Row Limit

All exports are capped at **10,000 rows** (NFR-2). If a report result exceeds this limit, the export button is disabled. Users should apply filters to reduce the result set.

### Export Formats

| Format | Generation                      | Notes                                  |
| ------ | ------------------------------- | -------------------------------------- |
| CSV    | Client-side                     | UTF-8 with BOM for Excel compatibility |
| JSON   | Client-side                     | Pretty-printed, array of objects       |
| Excel  | Edge function (`export-report`) | Uses ExcelJS; styled header row        |
| PDF    | Edge function (`export-report`) | Simple tabular layout                  |

### Execution Record Updates

After export, the `pf_report_executions` row is updated:

* `exported_format` — The format used (csv, excel, pdf, json)
* `exported_file_path` — Storage path to the exported file

## Best Practices

1. **Least privilege** — Grant only the permissions each user/role needs
2. **Audit exports** — Check run history to see who exported what and when
3. **Storage retention** — Exported files persist in storage; consider periodic cleanup
4. **Row limits** — Encourage users to filter reports before exporting large datasets

## Troubleshooting

| Issue                             | Solution                                                                                                             |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| User cannot export                | Verify they have `can_run` permission on the report                                                                  |
| Storage upload fails              | Check `reports-exports` bucket exists and RLS policies are correct                                                   |
| Edge function errors              | Check [Edge Function logs](https://supabase.com/dashboard/project/zkgxozahyczcnzpwhbbf/functions/export-report/logs) |
| Permission changes not reflecting | Permission query has 5-minute stale time; wait or hard refresh                                                       |

## References

* [PF-12 Spec](../../specs/pf/specs/PF-12-reporting-engine.md)
* [PF-12 Phase 5/6 Expansion](../../specs/pf/specs/PF-12-PHASE-5-6-EXPANSION.md)
* [User Guide](reporting-user-guide.md)