Scheduled Reports

Scheduled Reports are the same report you build in Reports but running by itself: every Monday, every day at 8am, the first of the month. They get generated as PDF or Excel, delivered by email or WhatsApp to the list you define, and the execution history is auditable.

Executive summary

The game changer: the weekly maintenance report lands in the manager's inbox without anyone remembering to generate it.

What is it for?

• Recurring maintenance reports — weekly for management, monthly for directors.
• Consolidated invoices for maintenance service clients.
• KPI dashboards a supervisor prints for the Monday standup.
• Internal audits — monthly snapshot of plant state for compliance archive.

How it works

flowchart LR
  S[Cloud Scheduler<br/>every 15 min] --> C{Any report<br/>due?}
  C -- yes --> G[Generate PDF/Excel<br/>with branding_id]
  G --> D{channel}
  D -- email --> E[Postmark SMTP]
  D -- whatsapp --> W[Evolution API]
  G --> H[Log<br/>execution]
  C -- no --> W1[wait]

The run-scheduled-reports job (Cloud Scheduler every 15 min) walks the active scheduled reports collection and evaluates whether each one is due (frequency + hour + day) and hasn't run yet in that window. If so, it renders the file with the defined structure, applies the branding and delivers it.

Every execution logs to _scheduled_report_executions with:

• timestamp
• generated file size
• status (ok / delivery_failed / generation_failed)
• effective recipients
• signed URL of the PDF/Excel in GCS

Config parameters

How to use it

Create a scheduled report

1. Go to Data → Scheduled Reports → New.
2. Give it a name ("Weekly Maintenance — North Plant").
3. Pick frequency (weekly, Mondays at 7am UTC = 2am EST).
4. Pick delivery channel and select the account/number (verified email account or connected WhatsApp number).
5. Add recipients (emails or phones, comma-separated).
6. Select the saved branding (or leave blank for the default).
7. Define the report structure — same block editor as on-demand reports.
8. Save and activate.

Next Monday at 7am UTC the system generates the PDF and sends it.

Run manually (without waiting)

During setup it's useful to test the run before activating:

1. On the scheduled report detail, click Run now.
2. The job fires immediately. The PDF/Excel is generated and delivered to the listed recipients.
3. The execution is logged with triggered_by=manual.

This does not alter the next scheduled run.

REST endpoints

POST   /api/v1/scheduled-reports                   # create
GET    /api/v1/scheduled-reports                   # list
GET    /api/v1/scheduled-reports/{id}              # detail
PATCH  /api/v1/scheduled-reports/{id}              # update
DELETE /api/v1/scheduled-reports/{id}              # delete
POST   /api/v1/scheduled-reports/{id}/execute      # run manually
GET    /api/v1/scheduled-reports/{id}/executions   # history
GET    /api/v1/scheduled-reports/{id}/executions/{exec_id}

Use cases

1 · Weekly maintenance report (manufacturing plant). weekly, Mondays 7am UTC (2am local). PDF with 8 blocks: header with plant logo, last week's task table, critical alarms table, KPIs (availability, MTTR, MTBF). Recipients: 3 emails from leadership. Lands before the Monday standup starts, zero human work.

2 · Monthly report for external client (service provider). monthly, day 5 at 14:00 UTC. PDF with the client's branding (logo + colors + "Confidential" footer). Table of last month's interventions with times, assigned technician and cost. The client receives their exec report without asking. The service is invoiced the same day.

3 · Daily HACCP compliance report (food safety). daily, 6am UTC. WhatsApp channel to the supervisor group. Compact PDF with the previous day's readings: cold-room temperatures, out-of-range alarms, pending corrective actions. Meets the documentary compliance without anyone having to remember.

Limits and assumptions

• Minimum execution resolution: 15 minutes. A report with hour=8 may fire between 08:00 and 08:15 UTC.
• day_of_month is capped at 1-28. No "last day of month" support; schedule day 28 with a note in the report if needed.
• If the delivery account (email or WhatsApp number) is disabled, the execution silently fails (logged as delivery_failed). The report is not auto-retried — manually re-run after fixing the connection.
• No conditional execution: the report runs even if there's no new data. "Only run if critical alarms this month" is a WhatsApp agent with a report-generation tool, not a scheduled report.
• Generated PDFs consume GCS storage. Tenants with many scheduled reports + many executions can accumulate space; the retention policy is configurable per tenant.

Key benefits

• Recurring reports in 0 human minutes → frees the coordinator from repetitive work.
• Complete execution history for audit (what was generated, when, to whom, size).
• Consistent corporate branding — change the logo in one place and all future reports use it.
• Same block structure as on-demand reports — no double work if you already had a template.
• Reliable delivery via Postmark (email) or Evolution API (WhatsApp) — no outbound queues backing up.