What this section is for
Use this section to define a formula over the variables exposed by the product and choose how its result is formatted. Report templates can combine metrics, charts, tables and text. In the current version, report runs are started manually; schedule and recipient fields are stored but do not send reports automatically.
When to use
- When the team needs a metric that can be calculated from available data but has no built-in card.
- When you want a reusable layout for a report you run manually.
- When you need one metric expressed consistently across several teams.
Quick start
- 1Create a metric, choose its data type and unit, and write the formula.
- 2Watch the live preview โ it evaluates against sample data and will tell you when parentheses are unbalanced or a variable does not exist.
- 3Build a report template, add sections (metrics, chart, table, free text), and pick a chart type where it helps.
- 4Run the template manually and review its status in the run history.
Key settings
| Setting | What it does | How to use it | Common mistake |
|---|---|---|---|
| Formula | Defines how the metric is computed from available variables. | Give the formula a clear name and describe what the result means. Check it with a simple example. | Forgetting that the divisor may be zero in a period without activity. |
| Data type and unit | Controls how the value is formatted and charted. | Set the unit so readers know whether a value means hours, a count or a percentage. | Marking a ratio as a number, so the report shows 0.87 where everyone expected 87%. |
| Default period | Sets the calculation period when no other dates are selected. | Match it to the period you normally use for manual report runs. | A 7-day default on a metric that appears in a monthly report, which produces two different numbers for the same name. |
| Schedule and recipients | Stores schedule and recipient fields on the template; automatic sending is not implemented. | Run reports manually and share the exported results yourself. | Assuming that saving a schedule creates background runs or sends email in the current version. |
Usage example
Scenario: The team wants a reusable pull-request merge-rate metric.
- 1Create a percentage metric using merged and opened pull-request variables, with a guard for zero opened pull requests.
- 2Check the live preview and confirm the percentage unit.
- 3Add the metric to a report template and start a manual run.
What this shows: The same formula and layout can be reused whenever the team runs the report.
FAQ
Why does the preview show an error?
Check matching parentheses, variable names and division by zero. Available variables are listed next to the editor.
Do schedules and recipients send reports automatically?
No. Those fields are stored on the template, but report generation and delivery are manual in the current version.
How is this different from Reports?
Reports produces a fixed sprint summary. Custom Metrics is for formulas and report layouts you control and run manually.
Tips
- Calculations use the selected team, dates, repository and user. Missing values and division by zero produce errors rather than zero results.
- Completed runs save the formulas and calculated values. Download JSON or CSV, or print to PDF. Chart sections currently export as tables of values.
- Repeat older runs that have no saved results. When changing a formula, record what changed so different calculations are not compared as the same metric.