Building Dashboard Metrics
Build the figures and charts your dashboards show
A metric widget is a figure you build yourself — a total, an average, a breakdown, a chart, a table, or one number divided by another. This article walks the builder field by field. For dashboards themselves — arranging them, assigning them, exporting them — see Using the Dashboard App.
You need the Manage Dashboard app permission to build one.
Opening the builder
Edit the dashboard, choose Add widget, then A metric. To change an existing one, click the pencil on its tile.
The builder is two panels: the questions on the left, a live preview on the right. Click Preview any time to see what you've built so far with real data, before saving anything.
1. What should this be called?
The title on the tile. Name it the way you'd say it out loud — "Total donations this cycle" beats "Sum of amount".
2. What are you measuring?
Contacts or Activity. This decides which fields and which views the rest of the form offers you. Changing it later resets the calculation, because a contacts field means nothing on an activity record.
3. Which records?
Every metric is built on a saved view — that's what makes a widget mean something specific ("donors this cycle") rather than "everything". Pick one from the list.
If you don't have a suitable view yet, there are two doors out:
- Import a saved grid view — pulls in one of the views you've already built in the Contacts or Activity grid.
- On a workspace with no views at all, a button offers to create a view of all contacts (or all activity) to get you started.
The toggle underneath, Also show this view in the grid's view list, is off by default. Leave it off for a view that only exists to feed a tile; turn it on when it's a view you'd genuinely want to open in the grid.
4. What should it show?
Three shapes:
- A number or chart — calculate something from the records. This is the common case.
- A table of records — the matching people or activity, listed, with the columns you choose. Not a calculation: a call sheet.
- One number divided by another — a ratio. See below.
5. Based on which field?
For a number or chart, choose the field being measured. The list holds your workspace's own custom fields plus the built-in ones — Date added, Last contacted, Tags and Contact type on contacts; Activity date, Date added, Activity type and Person (author) on activity. A custom field you create tomorrow appears here with no further setup.
Leave it on Just count the records to count matching records without measuring any field at all.
6. What calculation?
The operations offered depend on the field's type, because not every calculation makes sense on every field — you'll never be offered the total of a text field, and you'll never be told "no" after saving.
| Calculation | What it does | Offered on |
|---|---|---|
| Total of | Adds the values together — total raised. | Number |
| Average of | The average value — average gift size. | Number |
| Earliest / lowest | The smallest value, or the earliest date. | Number, Date |
| Latest / highest | The largest value, or the most recent date. | Number, Date |
| Number of records | How many records match, regardless of any field. | Any field, and with no field at all |
| Number of different values in | How many distinct values appear — how many donors. | Any field |
| Breakdown by | How many records fall into each value — good for a chart or table. | Choice, Multiple choice, Yes/No, User |
| Grouped over time by | How many records fall into each time period. | Date |
| Percent marked Yes | The share of records where a Yes/No field is Yes — percent of thank-yous sent. | Yes/No |
Changing the field resets the calculation, since the previous one may not be legal for the new field's type.
7. Group by date
Any calculation can be broken out over time: pick a date field, then a period — Day, Week, Month, Quarter or Year. That turns a single total into a series, which is what a line or bar chart draws.
Grouping isn't offered for a breakdown (that's already a second dimension), for a percent-yes, or for a ratio.
8. Compared to
A comparison adds a change indicator to the figure — the delta against a baseline. Choose:
- The period before this one
- The same period last year
- A specific date range
Then name the date field the comparison runs on, and the window being reported: This period starts / and ends. Every mode needs that window, including "the period before this one" — the earlier period is defined relative to this one. Choosing "a specific date range" adds a second pair of dates for the baseline itself.
Comparisons aren't offered on a percent-yes or a ratio, which have no delta to draw.
9. How should it look?
Only the visualizations that can actually render your result are offered:
- Single number — for one figure: a total, an average, a count, a ratio.
- Progress bar — a percent-yes, drawn as a filled track under the number.
- Bar chart or Line chart — anything grouped over time; bar also for a breakdown.
- Pie chart — a breakdown, but not a compared one: a pie shows one distribution summing to a whole.
- Table — a breakdown, a time series, or a comparison of both.
This is why a plain total doesn't offer you a pie chart, and a monthly series doesn't offer you a single number. The pairings left out are the ones that would render a plausible, wrong-looking tile.
Ratios: one number divided by another
Choose One number divided by another and you get two boxes — Top number (the amount being divided, e.g. total raised) and Bottom number (what it's divided by, e.g. the number of donors). Each side is its own small calculation:
- Which records? — "the same records as this widget", or a view of its own. That second option is what makes "donations raised per person contacted" expressible: two different populations, one figure.
- Based on which field? and What calculation? — narrowed to operations that produce a number, since a breakdown or a date can't be divided.
A ratio is exactly two calculations and one division — not a formula language. It can't be grouped over time or compared, and it can't contain another ratio. If the bottom number is zero, the widget shows no value rather than a misleading one.
If a ratio was built outside this editor (through the API or by an agent) using something the builder can't express, the panel says so and keeps the division exactly as it was — you can still rename the widget, change which records it covers, and change how it looks.
Tables of records
Choose A table of records and you get a column picker instead of a calculation. Tick the columns you want; leave everything unticked to use the collection's defaults.
Saving
Save widget needs a title and a view. The widget lands on the dashboard, where you can drag it wherever it belongs.
What the numbers mean
Two things are true of every metric, and worth saying to whoever reads your dashboard:
- Figures are calculated when the dashboard opens, not stored. There's no stale cache to refresh.
- Every figure is calculated under the viewing person's own permissions. A widget over records someone can't read shows "not available to you" for them, and the correct number for you. That's also why an exported report carries a generation date — it's an "as of", not a fixed truth.
Related
- Using the Dashboard App
- Custom Fields
- Managing, Filtering and Viewing Contacts

