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

# Report Export Builder

> Batch export multiple financial reports for meetings and audits

## Overview

The **Report Export Builder** is a frontend UI feature that allows you to generate multiple financial reports at once with consistent date ranges, making it easy to create comprehensive report packages for board meetings, audits, or stakeholder reviews.

<Note>
  **Permission required**: `reports:read`

  This is a UI convenience feature that calls individual report API endpoints and combines the results for export. All underlying reports require `reports:read` permission.
</Note>

***

## How It Works

The Report Export Builder:

1. **Accepts selections** from the user (which reports, date range, format)
2. **Calls individual report APIs** in parallel:
   * `GET /reports/balance-sheet?asOfDate={date}`
   * `GET /reports/profit-loss?startDate={date}&endDate={date}`
   * `GET /reports/shares-report?asOfDate={date}`
   * `GET /reports/loans-outstanding?expectedDate={date}`
3. **Combines results** into requested format (PDF or CSV)
4. **Downloads** to user's browser

**No dedicated backend endpoint** - this feature orchestrates existing report APIs.

***

## Available Reports

You can export any combination of these reports:

| Report                | API Endpoint                 | Date Parameter                            |
| --------------------- | ---------------------------- | ----------------------------------------- |
| **Balance Sheet**     | `/reports/balance-sheet`     | `asOfDate` (snapshot date)                |
| **Profit & Loss**     | `/reports/profit-loss`       | `startDate` and `endDate` (period)        |
| **Shares Report**     | `/reports/shares-report`     | `asOfDate` (snapshot date)                |
| **Loans Outstanding** | `/reports/loans-outstanding` | `expectedDate` (arrears calculation date) |

See individual report documentation for complete API details:

* [Balance Sheet](/tontines/reports/balance-sheet)
* [Profit & Loss](/tontines/reports/profit-and-loss)
* [Shares Report](/tontines/reports/shares-report)
* [Loans Outstanding](/tontines/reports/loans-outstanding)

***

## Date Range Configuration

**How date ranges map to individual report parameters:**

| Report            | Start Date          | End Date               |
| ----------------- | ------------------- | ---------------------- |
| Balance Sheet     | Ignored             | Used as `asOfDate`     |
| Profit & Loss     | Used as `startDate` | Used as `endDate`      |
| Shares Report     | Ignored             | Used as `asOfDate`     |
| Loans Outstanding | Ignored             | Used as `expectedDate` |

**Example**:

* Select range: **June 1 - June 30, 2026**
* Balance Sheet API call: `GET /reports/balance-sheet?asOfDate=2026-06-30`
* Profit & Loss API call: `GET /reports/profit-loss?startDate=2026-06-01&endDate=2026-06-30`
* Shares Report API call: `GET /reports/shares-report?asOfDate=2026-06-30`
* Loans Outstanding API call: `GET /reports/loans-outstanding?expectedDate=2026-06-30`

***

## Common Export Scenarios

### Monthly Board Meeting Package

**Reports to include:**

* ✅ Balance Sheet (financial position as of month-end)
* ✅ Profit & Loss (monthly performance)
* ✅ Loans Outstanding (portfolio health)

**API calls made:**

```http theme={null}
GET /reports/balance-sheet?asOfDate=2026-06-30
GET /reports/profit-loss?startDate=2026-06-01&endDate=2026-06-30
GET /reports/loans-outstanding?expectedDate=2026-06-30
```

**Date range**: "Last month" (e.g., June 1 - June 30)

**Result**: Combined report showing complete monthly financial snapshot

***

### Quarterly Member Meeting

**Reports to include:**

* ✅ Balance Sheet (assets and equity position)
* ✅ Profit & Loss (quarterly profit/loss)
* ✅ Shares Report (member ownership distribution)

**API calls made:**

```http theme={null}
GET /reports/balance-sheet?asOfDate=2026-06-30
GET /reports/profit-loss?startDate=2026-04-01&endDate=2026-06-30
GET /reports/shares-report?asOfDate=2026-06-30
```

**Date range**: "This quarter" (e.g., Apr 1 - Jun 30)

**Result**: Comprehensive quarterly performance and ownership report

***

### Annual Audit Package

**Reports to include:**

* ✅ Balance Sheet
* ✅ Profit & Loss
* ✅ Shares Report
* ✅ Loans Outstanding

**API calls made:**

```http theme={null}
GET /reports/balance-sheet?asOfDate=2025-12-31
GET /reports/profit-loss?startDate=2025-01-01&endDate=2025-12-31
GET /reports/shares-report?asOfDate=2025-12-31
GET /reports/loans-outstanding?expectedDate=2025-12-31
```

**Date range**: Custom (Jan 1 - Dec 31, 2025)

**Result**: Complete annual financial statements package

***

### Loan Committee Review

**Reports to include:**

* ✅ Loans Outstanding (current portfolio status)

**API calls made:**

```http theme={null}
GET /reports/loans-outstanding?expectedDate=2026-06-12
```

**Date range**: "Current" (today)

**Result**: Current loan portfolio details for decision-making

***

## Export Format Options

### PDF Export

**Implementation**: Frontend generates PDF from API response data

**Advantages:**

* Professional formatted reports
* Includes organization branding
* Easy to print and distribute
* Suitable for presentations

**Options:**

* **Merged PDF**: All reports in single file (recommended for meetings)
* **Separate PDFs**: Each report in individual file (for selective distribution)

**File naming convention:**

* Merged: `agatabo-[organization]-reports-[date].pdf`
* Separate: `agatabo-[organization]-[report-name]-[date].pdf`

***

### CSV Export

**Implementation**: Frontend converts API response to CSV format

**Advantages:**

* Import into Excel for custom analysis
* Create pivot tables
* Generate custom charts
* Combine with other data sources

**Format**: Always separate files (one CSV per report)

**File naming convention:**

* `agatabo-[organization]-[report-name]-[date].csv`

***

## Using the Export Builder

**Typical workflow:**

1. **Navigate to Reports** section in UI
2. **Select reports** to include (check boxes)
3. **Choose date range**:
   * Current period
   * Last month
   * This quarter
   * This year
   * Custom (specify exact dates)
4. **Select format**: PDF or CSV
5. **Configure PDF options** (if PDF selected):
   * Merged (single file)
   * Separate (individual files)
6. **Click Generate/Download**
7. **Wait for API calls** to complete
8. **Download** generated file(s)

**Browser behavior:**

* Files download to default download folder
* Multiple files (separate PDFs/CSVs) download sequentially
* Large reports may take several seconds to generate

***

## API Implementation

If building a custom export feature, call the report endpoints directly:

```typescript theme={null}
// Example: Monthly board package
const organizationId = 'org-abc123';
const asOfDate = '2026-06-30';
const startDate = '2026-06-01';
const endDate = '2026-06-30';

// Parallel API calls
const [balanceSheet, profitLoss, loansOutstanding] = await Promise.all([
  fetch(`/reports/balance-sheet?asOfDate=${asOfDate}`, {
    headers: { 'x-organization-id': organizationId }
  }),
  fetch(`/reports/profit-loss?startDate=${startDate}&endDate=${endDate}`, {
    headers: { 'x-organization-id': organizationId }
  }),
  fetch(`/reports/loans-outstanding?expectedDate=${asOfDate}`, {
    headers: { 'x-organization-id': organizationId }
  })
]);

// Process responses
const balanceSheetData = await balanceSheet.json();
const profitLossData = await profitLoss.json();
const loansOutstandingData = await loansOutstanding.json();

// Generate PDF or CSV from combined data
// (implementation depends on PDF/CSV library used)
```

***

## Date Range Presets

**Common preset mappings:**

| Preset             | Start Date                   | End Date                   |
| ------------------ | ---------------------------- | -------------------------- |
| **Current period** | Last period close date       | Today                      |
| **Last month**     | First day of previous month  | Last day of previous month |
| **This quarter**   | First day of current quarter | Today                      |
| **This year**      | January 1 of current year    | Today                      |
| **Custom**         | User-specified               | User-specified             |

**Example (today = June 12, 2026):**

* Last month: June 1, 2026 → June 30, 2026
* This quarter: April 1, 2026 → June 12, 2026
* This year: January 1, 2026 → June 12, 2026

***

## Best Practices

<Note>
  **Using the export builder effectively:**

  **Report selection:**

  * ✅ Include Balance Sheet + Profit & Loss for complete financial picture
  * ✅ Add Shares Report for member-facing communications
  * ✅ Include Loans Outstanding for portfolio management
  * ✅ Avoid exporting unnecessary reports (wastes time)

  **Date ranges:**

  * ✅ Use consistent periods for comparative analysis
  * ✅ Choose "Last month" after month-end closing
  * ✅ Use "This year" for year-to-date analysis
  * ✅ Verify date range before generating (double-check start/end)

  **Export formats:**

  * ✅ Use PDF for presentations and official distribution
  * ✅ Use CSV for custom analysis in Excel
  * ✅ Export both formats for audit packages (PDF for review, CSV for analysis)
  * ✅ Use merged PDF for single-recipient distribution (easier)

  **File management:**

  * ✅ Save exports to organized folders (e.g., `Financial Reports/2026/Q2/`)
  * ✅ Keep exported filenames (auto-generated names include key metadata)
  * ✅ Archive exports for historical reference
  * ✅ Don't modify exported files (regenerate if data changes)

  **Performance:**

  * ✅ Expect 3-10 seconds for multi-report exports
  * ✅ Be patient - API calls run in parallel but still take time
  * ✅ Don't click generate multiple times (creates duplicate requests)
</Note>

***

## Troubleshooting

**Q: Export takes a long time**

A: Multiple API calls are being made. Time depends on:

* Number of reports selected (1-4)
* Amount of data in each report
* Server load
* Network speed

Typical: 3-10 seconds for all 4 reports.

**Q: Export fails or shows errors**

A: Check:

* Do you have `reports:read` permission?
* Is organization selected (if multi-org access)?
* Is date range valid (start \< end)?
* Are there transactions in selected period?
* Check browser console for API error messages

**Q: PDF/CSV format doesn't look right**

A: This depends on frontend PDF/CSV generation library. Check:

* Browser compatibility (modern browsers recommended)
* PDF viewer (Adobe Reader, Chrome PDF viewer)
* CSV import settings in Excel (delimiter, encoding)

**Q: Can I export with different date ranges per report?**

A: Not with the UI builder. For different date ranges, either:

* Run export builder multiple times with different dates
* Call individual report APIs directly with custom parameters
* Navigate to each report page and export individually

**Q: Where do files download?**

A: Browser's default download folder:

* Windows: `C:\Users\[YourName]\Downloads\`
* Mac: `~/Downloads/`
* Linux: `~/Downloads/`

Check browser download settings to change location.

**Q: Can I schedule automatic exports?**

A: Export builder is manual UI feature only. For automated exports:

* Build custom script calling report APIs
* Use cron job or scheduled task
* Generate and email reports automatically

***

## Alternative: Individual Report Exports

If you need **different date ranges** for each report:

**Option 1: Call APIs directly**

```bash theme={null}
# Balance Sheet (as of month-end)
curl -X GET "/reports/balance-sheet?asOfDate=2026-06-30" \
  -H "x-organization-id: org-abc123"

# Profit & Loss (for quarter)
curl -X GET "/reports/profit-loss?startDate=2026-04-01&endDate=2026-06-30" \
  -H "x-organization-id: org-abc123"

# Shares Report (as of today)
curl -X GET "/reports/shares-report?asOfDate=2026-06-12" \
  -H "x-organization-id: org-abc123"
```

**Option 2: Navigate to individual report pages**

1. Reports → Balance Sheet
2. Select custom date
3. Export that report
4. Repeat for other reports

***

## Permissions

**Required permission**: `reports:read` (organization-level scope)

**Users who can use export builder:**

* Administrators (full access)
* Accountants (full access)
* Treasurers (full access)
* Board Members (if granted `reports:read`)

**Users who cannot:**

* Regular members (unless specifically granted permission)
* Users with `ledger:read` only (different permission)

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Balance Sheet" icon="scale-balanced" href="/tontines/reports/balance-sheet">
    Financial position report
  </Card>

  <Card title="Profit & Loss" icon="chart-line" href="/tontines/reports/profit-and-loss">
    Income statement
  </Card>

  <Card title="Shares Report" icon="users" href="/tontines/reports/shares-report">
    Member ownership distribution
  </Card>

  <Card title="Loans Outstanding" icon="money-bill-trend-up" href="/tontines/reports/loans-outstanding">
    Portfolio summary
  </Card>
</CardGroup>