Concept

How Report Builder Works

A conceptual overview of the ideas behind the Report Builder service, and how they fit together. This explains the mental model, not the steps. For exact parameters, see the API reference; for operating the service, see the release runbook.

This is a technical writing sample. It is a conceptual ("explanation") document for the same representative service shown in the API reference and runbook samples, and is not tied to any real system.

The problem it solves

Most teams build the same report over and over: someone opens a data source, pulls the numbers, formats them, and sends the result, every week, by hand. It is slow, easy to get wrong, and it stops the moment that person is out.

Report Builder removes the manual step. You describe a report once, point it at a data source, and optionally give it a schedule. After that, the service produces the report whenever it is asked, or automatically on the cadence you set. The work of defining the report is done a single time; the work of running it disappears.

The core concepts

Three ideas do most of the work. Understanding how they relate is enough to understand the whole service.

Data source where the numbers live

A data source is the system the numbers come from. Report Builder reads from it but never changes it. One data source can feed many different reports, so connecting a source once makes it available everywhere.

Report a saved definition

A report is not a one-time export. It is a saved object with its own ID, a name, the data source it draws from, and an optional schedule. Because it is a durable object, a report can be retrieved later, paused and resumed, and audited. It has a lifecycle, not just a moment of existence.

Schedule when it runs

A schedule is an optional rule that tells Report Builder when to generate a report on its own, written as a cron expression. A report with no schedule is generated only when something asks for it. A report with a schedule is also generated automatically on that cadence. The schedule is a property of the report, which is why one report can be paused without touching the data source or any other report.

How a report comes to life

Whether it runs on a schedule or on demand, every report follows the same path. Keeping a single path means a report behaves identically no matter how it was triggered.

Data sourcewhere the numbers live

Report definitionname, source, optional schedule

Generationon a schedule or on demand

Outputdelivered or stored

The same definition always produces a comparable report, so re-running one is safe and predictable.

Why it is designed this way

A few deliberate choices explain most of how the service behaves.

Reports are separate from data sources. Keeping them apart means one source can power many reports, and a report can be re-pointed at a new source without being rebuilt. Each concept stays simple because it does one job.
A report is a durable object, not a fire-and-forget export. Giving every report an ID and a status (active or paused) is what makes scheduling, pausing, auditing, and later retrieval possible. The features fall out of treating the report as a real thing that persists.
Scheduling uses cron. Recurring time is a solved problem, so the service uses the widely understood cron standard rather than inventing its own syntax. Anyone who has scheduled a job before already knows how to read it.
On-demand and scheduled runs share one path. Because both trigger the same generation step, a report produced manually and one produced on a schedule are the same in every way that matters. There is no second code path to drift out of sync.

The one idea to take away: a report is a durable, named definition that links a data source to an optional schedule. Almost everything the service does follows from treating the report as a first-class object rather than a one-time action.

Where to go next

This page is the mental model. The companion documents cover the specifics:

API Reference: the exact endpoints, parameters, and responses for creating and managing reports.
Release Runbook: how the service itself is deployed, verified, and rolled back.