> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/reporting/building-reports.md). # Building Reports ### Getting There Three routes open the report builder: * The **Report Builder** button on the dashboards list page, which starts Quick mode. * The **Add Report** button on a dashboard detail page, which starts Add mode. * Clicking a report card's header on a dashboard, which starts Edit mode. *** ### Modes The builder runs in three modes. * **Quick mode** builds a standalone report, then asks which dashboard to add it to. An "Add to Dashboard" dropdown in the header lists them all. * **Add mode** builds a report that saves to the dashboard you came from. The header carries the report name as an editable field, plus a "Save Report" button. * **Edit mode** updates an existing report's configuration. The header carries the current report name and an "Update Report" button. *** ### Step 1: Choose a Report Type Pick one of two. * **Insight** answers "what does the data look like right now?" It gives a point-in-time snapshot, which suits counts, breakdowns and comparisons. * **Historical** answers "how has the data changed over time?" It shows trends across a date range, which suits growth, seasonality and patterns. *** ### Step 2: Choose a Data Source Pick where the report pulls its data from: * **People**, your contact database * **Any Stack**, one of your custom data tables * **Any List**, the items of one list, with its list attributes available as fields. List sources skip the Target step, and contributing-data CSV export is not available for them. Add filter rules to narrow the records if you want. Click **Add filter** beneath the data source to open the rule builder, build your conditions, then click **Apply** to update the preview. *** ### Step 3: Configure the Report Your configuration options follow the report type you picked. #### Insight Configuration **Metric** sets what you measure. Choose **Count** to count records, or select a numeric field and an aggregation method such as Sum or Average. The full numeric set appears in [Data Sources & Metrics](/docs/reporting/data-sources-and-metrics.md#numeric-fields). With no grouping applied, the result shows as one large number. **Grouped by** breaks the data into groups, say people by country. Adding grouping turns the result into a chart. **Segment by** cross-tabulates results inside each group with a second attribute. Segmentation forces the chart to a Bar chart. **Include empty values** works independently for grouping and for segmentation. **Target** analyses data from a related entity. With a Stack as your data source, you can target the linked People or a related Stack. Selecting a target lets the metric section aggregate fields from the target rather than the source, and you can add filter rules to the target too. #### Historical Configuration **What the timeline counts.** A historical report buckets by each person's or record's **creation date**. "Daily count of People over the last month" means how many people were created each day. A Sum or Average metric aggregates that field over the entities *created* in each bucket. Buckets are calculated in UTC. **Metric** takes **Count**, or a numeric field with an aggregation method such as Sum or Average. See [Data Sources & Metrics](/docs/reporting/data-sources-and-metrics.md#numeric-fields). **Time Range** offers quick presets of **7D**, **1M**, **3M**, **6M** and **12M**. A **Period to date** dropdown adds **Week to date**, **Month to date**, **Quarter to date** and **Year to date**. **Custom** opens a from-and-to picker with date *and* time. **Granularity** divides the range: Hourly, Daily, Weekly or Monthly. Flapjax offers only the granularities that suit your range, and changing the range auto-corrects it. See the [range and granularity table](/docs/reporting/data-sources-and-metrics.md#time-granularity). **Segment by** appears once you choose a granularity. It splits the time series by an attribute, one line per segment value. Segmenting reveals an **Include empty values** toggle, which shows entities with no value for that field as their own "(unknown)" series. *** ### Step 4: Visualisation Options Choose how your data appears. The available chart types follow your configuration. **Insight chart types:** * **Single Metric**, a large number, with no grouping applied * **Bar Chart**, vertical bars, the only option when segmenting * **Line Chart**, smooth curves with data points * **Pie Chart**, full circle segments * **Donut Chart**, ring-shaped segments * **Map Chart**, available when you group by a country field **Historical chart types:** * **Line Chart**, smooth time-series curves, the default * **Bar Chart**, vertical bars over time * **Area Chart**, a line with a gradient fill underneath **Additional options** for Bar and Line charts: * **Show axis labels** turns axis text on or off. * **Show zeros** includes groups with zero values, on Bar charts. * **Stack bars** stacks segmented bars rather than grouping them side by side, on segmented Bar charts. * **Sort order** sorts alphabetically or by amount, ascending or descending, on Bar charts. * **Target line** adds a horizontal reference line at a value you set. *** ### Auto-Preview The preview updates a moment after you change a setting. Filter rules are the exception. They apply when you click **Apply** in the filter panel. *** ### Saving **Quick mode** saves through **Add to Dashboard**, where you pick a dashboard from the dropdown. **Add mode** saves through **Save Report**. **Edit mode** saves through **Update Report**. The save button stays disabled until the report has a name and a valid configuration. Saving returns you to the dashboard.