Create a custom Report
Tom Azernour avatar
Written by Tom Azernour
Updated over a week ago

Reports are data tables used to list records or aggregated metrics to obtain a more detailed view of your data. Reports allow you to understand granular information while charts, cards, or KPIs provide a more general view.

Add a report to a dashboard

Click on the Add insight button down the dropdown on the top right of any dashboard., then select Report.

Read more about Keypup datasets here.

Select a dataset for your report

Use the Select dataset tab from the navigation menu to choose the type of data you want to report on. Keypup provides access to various datasets based on the applications and projects/repositories you connected.

Select the dataset containing the fields you are willing to use in your chart.

Query your selected dataset for your report

Once you have selected your visualization type (report) and dataset, you can begin building your insight and querying this dataset. From the navigation menu on the left, select the Configure table tab.

The table will include two columns by default: Dimension and Metric.

  • Dimensions are regular fields from the datasets. For example, it could be a merge date, an author, a label, etc.

  • Metrics are numerical values aggregated from a function applied to all records (e.g. COUNT) or to a quantitative field (e.g. SUM lines of code changed) on all records.

In a report, you can add multiple dimensions and metrics.

  • To add them, simply click on the (+) sign button on the right side of the column and select “dimension” or “metric”.

  • To delete dimensions and/or metrics columns, click on the expand (...) button and select the "delete" option.

Depending on how comfortable you are with query building, you can stick to selecting standard dimensions and pre-built aggregators (simpler) and/or use custom formulas to create more elaborate reporting fields.

In both cases, dimensions, metrics, and custom formulas can be selected from the dropdown menu at the top of each column inside the data table.

A simple query using pre-built dimensions and metrics

An advanced query using a custom metric (custom formula):

Apply a filter (recommended)

You can apply AND / OR filters to narrow down the data used in your report. To do so click on the Configure filter button at the top right corner of the insight builder interface.

Configure drilldown for your report

The drilldown feature allows you to explore and analyze data from a particular insight in detail. It is accessed by clicking on specific data points in your insights.

By default, the drilldown table is disabled and must be activated using the activation slider on the right side of the Configure drilldown tab.

When enabled for the first time, a default configuration is applied:

  • A set of recommended columns is added

  • The filters are pre-configured to recover the clicked data point.

You can then apply any customization. Click here to learn more about drilldown configuration.

Customize your report look & feel

Based on your selected visualization, cosmetic customization is automatically suggested from the Customize tab.

It's possible to customize the appearance of your reports by changing the colors, title, columns, and legend.

Document the report

Insight can be complex to understand by others, so having proper documentation is important.

The documentation should explain the purpose of the insight (“Why do we track this metric in the team?”), provide some highlights about its configuration (e.g. “Showing data labeled as a bug over the last 12 months”), and explain the best way to read it (e.g. “More than 15 bugs raised per week would be considered a warning for the team”).

Having proper documentation will guarantee that the insight remains useful and readable to others at all times.

To do so, you can set the following elements:

  • One-liner description (recommended): a short description displayed when browsing insights in collections.

  • Full documentation (recommended): exhaustive documentation regarding the goals, configurations, or reading tips about the insight. The full documentation can be written and formatted using markdown.

The full documentation can also be disabled, in which case the (?) tooltip near the insight title on the dashboard will remain hidden. Even when disabled, the documentation can still be accessed from the insight configuration.

Did this answer your question?