Report Scheduling Guide

​

Overview

​

Features

​

Schedule Types

• Daily: Run at specified time every day
• Weekly: Run on specific day of week
• Monthly: Run on specific day of month
• Custom: Define custom cron expression

​

Output Formats

• PDF: Professional formatted reports (requires additional library)
• CSV: Spreadsheet-compatible data export
• Excel: Native .xlsx format (requires additional library)

​

Delivery Options

• Email to multiple recipients
• Include summary section
• Timezone-aware scheduling
• Retry on failure

​

Usage

​

Creating a Schedule

import { useReportSchedules } from '@/platform/reports/hooks/useReportSchedules';

function ReportScheduling() {
  const { createSchedule } = useReportSchedules(organizationId);

  const handleCreate = () => {
    createSchedule.mutate({
      report_id: reportId,
      organization_id: organizationId,
      name: 'Monthly Financial Summary',
      schedule_type: 'monthly',
      day_of_month: 1,
      run_time: '08:00:00',
      timezone: 'America/New_York',
      output_format: 'pdf',
      recipients: [
        { email: 'cfo@example.com', name: 'Jane Doe' },
        { email: 'controller@example.com', name: 'John Smith' },
      ],
      enabled: true,
    });
  };
}

​

Schedule Management Page

import { ReportSchedulesPage } from '@/platform/reports/pages/ReportSchedulesPage';

// Add to router
<Route path="/reports/schedules" element={<ReportSchedulesPage />} />

​

Schedule Form Component

import { ReportScheduleForm } from '@/platform/reports/components/ReportScheduleForm';

<ReportScheduleForm
  onSubmit={handleSubmit}
  defaultValues={schedule}
  isSubmitting={isSubmitting}
/>

​

Schedule Configuration

​

Time Settings

• Run Time: 24-hour format (HH:MM:SS)
• Timezone: IANA timezone identifier
• Next Run: Automatically calculated by trigger

​

Recipients

• Email address (required)
• Display name (optional)

[
  {"email": "user@example.com", "name": "John Doe"},
  {"email": "manager@example.com", "name": "Jane Smith"}
]

​

State Tracking

• next_run_at - Next execution time
• last_run_at - Last execution time
• last_run_status - success | partial | failed
• last_run_error - Error message if failed
• run_count - Total executions

​

Cron Expressions

​

Presets

• Daily at 8am: 0 8 * * *
• Weekly Monday 8am: 0 8 * * 1
• Monthly 1st 8am: 0 8 1 * *
• Monthly 15th 8am: 0 8 15 * *

​

Custom Cron Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

• Every weekday 9am: 0 9 * * 1-5
• Every 6 hours: 0 */6 * * *
• Last day of month: 0 8 L * * (custom schedule type)

​

Execution Flow

​

Automated Execution

1. Edge function runs every 15 minutes
2. Queries schedules where next_run_at <= now()
3. Executes report SQL with parameters
4. Generates output in requested format
5. Sends email to all recipients
6. Updates schedule status and calculates next run

​

Manual Execution

const { data } = await supabase.functions.invoke('execute-scheduled-reports', {
  body: { scheduleId: 'specific-schedule-id' }
});

​

Error Handling

​

Retry Logic

• Failed executions: Automatic retry (3 attempts)
• Exponential backoff: 5min, 15min, 1hr
• Permanent failure after 3 attempts
• Error message logged in last_run_error

​

Failure Notifications

• Error message and details (sanitized to prevent sensitive information exposure)
• Troubleshooting suggestions
• Link to reports page

​

Recovery

1. Review error in last_run_error
2. Fix underlying issue (report SQL, permissions)
3. Enable schedule again
4. Next run calculated automatically

​

Email Delivery

​

Branded Email Templates

• Branded Encore OS header with gradient
• Report details card with name and description
• Statistics row (generated date, row count, format, file size)
• Prominent download button with 7-day signed URL
• Next scheduled run indicator
• Mobile-responsive design

​

Email Template Localization

• Templates use translation keys via locale parameter
• Default: English (en)
• Infrastructure ready for Spanish (es), French (fr), and more
• Per-organization locale settings planned for future releases

​

Customizing Email Content

{
  include_summary: true,
  // Email will show: "Columns: name, amount, date, +5 more"
}

​

Pre-Rendered HTML Support

await supabase.functions.invoke('send-email-notification', {
  body: {
    notificationId,
    recipientEmail: 'user@example.com',
    subject: 'Custom Report',
    html: customHtmlContent,
    skipTemplate: true,
  },
});

​

Best Practices

​

Performance

• Limit report data (use date ranges)
• Add indexes on frequently queried columns
• Test report SQL independently first
• Monitor execution time in logs

​

Scheduling

• Avoid peak hours for heavy reports
• Stagger multiple reports (avoid all at same time)
• Consider timezone of recipients
• Use off-hours for resource-intensive reports

​

Recipients

• Use distribution lists for large teams
• Keep recipient list under 50 people
• Include only stakeholders who need the report
• Update email addresses regularly

​

Output Format

• CSV: Best for data analysis (Excel, Google Sheets)
• PDF: Best for presentations and archived records
• Excel: Best for formatted spreadsheets with formulas

​

Monitoring

​

Schedule Health

• enabled = true and next_run_at populated
• last_run_status = 'success'
• No recent last_run_error
• run_count incrementing

​

Edge Function Logs

supabase functions logs execute-scheduled-reports

• Schedules processed
• Execution errors
• Email delivery failures

​

Delivery Confirmation

• First scheduled report
• Changed reports (after modifications)
• Critical financial reports

​

Troubleshooting

​

Schedule Not Running

1. Check enabled = true
2. Verify next_run_at is in the past
3. Review edge function logs
4. Confirm organization has access to report

​

Report Fails to Generate

1. Test report SQL independently
2. Check report parameters are valid
3. Verify user has permissions
4. Review RLS policies on data tables

​

Email Not Delivered

1. Check recipient email addresses
2. Verify Entra/Gmail provider configuration and required secrets
3. Review email delivery logs
4. Check spam folders
5. Confirm sender identity/domain is properly configured in the selected provider

​

Incorrect Schedule Time

1. Verify timezone setting
2. Check cron expression format
3. Ensure run_time is valid (HH:MM:SS)
4. Review calculated next_run_at

​

Advanced Features

​

Conditional Scheduling

-- Only run if data exists
SELECT * FROM fa_transactions
WHERE transaction_date >= current_date - interval '1 month'
AND EXISTS (SELECT 1 FROM fa_transactions LIMIT 1)

​

Parameterized Reports

{
  report_id: reportId,
  parameters: {
    start_date: '2025-01-01',
    end_date: '2025-01-31',
    fund_id: 'specific-fund-uuid'
  }
}

​

Multi-Format Delivery

• PDF to executives
• CSV to analysts
• Excel to department heads

​

Related Documentation

• Reporting Engine
• Email Notifications
• Report Visualizations