Skip to main content

​
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.
Permission required: reports:readThis is a UI convenience feature that calls individual report API endpoints and combines the results for export. All underlying reports require reports:read permission.

​
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:
ReportAPI EndpointDate Parameter
Balance Sheet/reports/balance-sheetasOfDate (snapshot date)
Profit & Loss/reports/profit-lossstartDate and endDate (period)
Shares Report/reports/shares-reportasOfDate (snapshot date)
Loans Outstanding/reports/loans-outstandingexpectedDate (arrears calculation date)
See individual report documentation for complete API details:

​
Date Range Configuration

How date ranges map to individual report parameters:
ReportStart DateEnd Date
Balance SheetIgnoredUsed as asOfDate
Profit & LossUsed as startDateUsed as endDate
Shares ReportIgnoredUsed as asOfDate
Loans OutstandingIgnoredUsed 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: 
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: 
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: 
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: 
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: 
// 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:
PresetStart DateEnd Date
Current periodLast period close dateToday
Last monthFirst day of previous monthLast day of previous month
This quarterFirst day of current quarterToday
This yearJanuary 1 of current yearToday
CustomUser-specifiedUser-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

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)

​
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 
# 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)

Balance Sheet

Financial position report

Profit & Loss

Income statement

Shares Report

Member ownership distribution

Loans Outstanding

Portfolio summary