Skip to main content
A Report template is the reusable definition of a report. It binds together the data sources, output formats, narrative configuration, default destinations, and ownership metadata. One template can power many schedules.
Templates can be created, previewed, and run on demand regardless of whether the background cron is wired. The Run Now button and the POST /api/v1/reports/templates/[id]/run-now API execute the full pipeline (sources → narrative → formats → delivery) immediately without depending on AWS EventBridge or any external scheduler.Templates only rely on the cron when they’re attached to a schedule and you want the schedule to fire automatically. See EventBridge Setup (optional during pilot).

​
Schema

model ReportTemplate {
  id           String   @id @default(uuid())
  tenantId     String
  name         String
  description  String   @default("")
  ownerUserId  String?
  dataSources  Json     @default("[]")
  sections     Json     @default("[]")
  formats      Json     @default("[\"pdf\"]")
  narrative    Json     @default("{\"enabled\":true}")
  filters      Json     @default("{}")
  enabled      Boolean  @default(true)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}

​
dataSources

Ordered array. Each entry references a registered data source by key: 
[
  { "sourceKey": "offer_performance", "params": { "days": 7, "limit": 20 } },
  { "sourceKey": "channel_effectiveness", "params": { "days": 7 } }
]
Parameters are Zod-validated by the adapter at run time. Invalid parameters surface as a single-row error section rather than aborting the run.

​
sections

Optional presentation metadata keyed by dataSourceIndex. Use this to override the auto-generated section title or provide an id that is referenced by the narrator: 
[
  { "id": "perf", "title": "Offer performance this week", "dataSourceIndex": 0 },
  { "id": "ch",   "title": "Channel breakdown",          "dataSourceIndex": 1 }
]
When omitted, sections auto-generate with ids s1, s2, … and titles derived from the source’s label field.

​
formats

Array of format keys. Each produces one artifact per run. Supported in the current release:
  • pdf
  • csv
  • markdown
  • html

​
narrative

{
  "enabled": true,
  "prompt": "Call out retention risks; ignore synthetic test tenants.",
  "modelOverride": "claude-sonnet-4-5-20250929"
}
  • enabled: when false, the narrator is skipped entirely.
  • prompt: optional addendum appended to the system prompt.
  • modelOverride: provider-specific model name. Falls back to the tenant default when omitted.

​
filters

Arbitrary Json used for cross-section filtering. Currently recognised:
  • filters.destinations: array of notification-provider UUIDs used as fallback destinations when a run is triggered via /run-now without a schedule.
Future versions will add report-wide time windows, segment filters, and global parameter overrides here.

​
Running a template

Two unconditional invocation paths:
  • Preview — POST /api/v1/reports/templates/[id]/preview runs every data source + narrator and returns the rendered result without persisting a ReportRun or dispatching to destinations. Used by the /settings/reports live-preview pane.
  • Run Now — POST /api/v1/reports/templates/[id]/run-now executes the full pipeline (persist ReportRun, dispatch to every configured destination). Works independently of the cron.
For automated scheduled firing, attach the template to a ReportSchedule and wire the cron — see EventBridge Setup.

​
API

See the Reports API reference for the full route table.