Dashboards · Domino

Define an analytics dashboard in code from catalog metrics, deploy it, check its numbers and promote it to live.

A dashboard is a page of analytics panels that your project code defines. Each panel reads one metric from Domino's catalog, so its numbers match domino analytics query. You deploy a dashboard in test, check it with domino dashboards get, and promote it to live like any other definition.

For the model behind this guide, read Analytics. To choose metrics from a project's goals and explain a dashboard's numbers with an agent, see the analytics reference.

Define a dashboard

Choose the metrics

Run domino analytics metrics to list the catalog. Each metric names the breakdowns, filters and charts it accepts, and whether it needs a point ledger.

Write the definition

Default-export defineDashboard from a file anywhere in your project:

// dashboards/growth.ts
import { defineDashboard } from "@domino-sdk/relay/authoring"

export default defineDashboard({
  key: "growth",
  title: "Growth",
  description: "Sign-ups, quest completions and points.",
  defaultRange: "30d",
  position: 1,
  sections: [
    {
      panels: [
        { key: "sign-ups", title: "Sign-ups", metric: "members.signUps", chart: "number" },
        { key: "xp", title: "XP awarded", metric: "points.awarded", ledger: "xp", chart: "line" },
        {
          key: "completions",
          title: "Completions by quest",
          metric: "quests.completions",
          breakdown: "quest",
          chart: "bar",
          width: 4,
        },
      ],
    },
    {
      title: "VIPs",
      panels: [
        {
          key: "vip-rejections",
          title: "Why VIP attempts are rejected",
          metric: "quests.rejections",
          breakdown: "reason",
          filter: { group: "vip" },
          chart: "table",
        },
      ],
    },
  ],
})

The types only accept the breakdowns, filters and charts the panel's metric allows. A ledger, or a filter key, can be a key or a handle from defineLedger, defineQuest and the other define… functions.

List it in relay.json

"dashboards": [{ "entry": "dashboards/growth.ts" }]

Add exportName when the file exports several dashboards.

Deploy and check it

Run domino deploy. The preview lists each dashboard and whether publishing creates it, updates it, or leaves it unchanged. Then read it back:

domino dashboards get growth --range 7d

It prints every panel's numbers, or the panel's error, as an operator would see them. Add --json for the full read.

What a dashboard holds

Part	Fields
Dashboard	`key`, `title`, optional `description`, optional `defaultRange` (`7d`, `30d`, `90d` or `all`; default `30d`), optional `position`, and `sections`
Section	Optional `title` and its `panels`, in order
Panel	`key`, `title`, optional `description`, `metric`, optional `breakdown`, optional `filter`, `ledger` for points metrics, `chart`, and optional `width`

Panels sit on a 4-column grid. width is 1 to 4, and defaults by chart:

Chart	Breakdown	Default width
`number`	Not allowed	1
`line`	Optional	2
`bar`	Optional	2
`table`	Required	4

A broken-down line or bar panel reads the top 8 rows, with the rest summed into Other. A table reads up to 100 rows.

What a deployment refuses

A deployment fails with a coded error, and publishes nothing, when a dashboard has:

Code	Cause
`unknown-metric`	A metric the catalog doesn't have
`breakdown-not-accepted`	A breakdown the metric doesn't take, or a `number` panel with a breakdown
`breakdown-required`	A `table` panel without a breakdown
`filter-not-accepted`	A filter the metric doesn't take
`chart-not-accepted`	A chart the metric can't draw, such as a rate as `bar`
`ledger-required`, `ledger-not-accepted`	A points metric without `ledger`, or `ledger` on another metric
`unknown-reference`	A quest, tracker, ledger, offer, referral program or leaderboard key this environment doesn't have
`referral-program-required`	A referral metric in a project with no referral program
`duplicate-key`	Two dashboards with one key, or two panels with one key in a dashboard
`too-many-panels`	More than 24 panels in a dashboard
`too-many-dashboards`	More than 20 dashboards that aren't archived in the project

Archived quests, ledgers and other resources are valid references: their history keeps counting. Groups are checked when a panel is read, not at deploy.

Read a dashboard

Command	Management client	Returns
`domino dashboards list [--include-archived]`	`dashboards.list({ includeArchived })`	Each dashboard's key, title, description, position, archive time and last update, by position (those without one last), then title
`domino dashboards get KEY [--range R]`	`dashboards.read({ key, range })`	The definition, the range read, and each panel's result or error

Both need read permission. A read uses the dashboard's defaultRange unless you pass one. Each panel's result is what domino analytics query returns for the same metric, breakdown and filters.

A panel that fails carries its own error while the other panels still have results:

Error	Cause
`group-not-found`	The panel filters on a group this environment doesn't have
`panel-timeout`	The panel's query took too long; try a shorter range
`panel-failed`	The panel couldn't be read for another reason; read the dashboard again

Change, archive and promote

Change it in code. Deploying a changed definition publishes a new version. Deploying an identical one publishes nothing.
Removing it from relay.json doesn't delete it. Archive it instead: domino dashboards archive KEY --reason "…", or dashboards.archive(key, { reason }) with the management client. Restore it with unarchive, unless the project already has 20 dashboards that aren't archived (too-many-dashboards). Both need publish permission, work in test only, and are recorded in the audit log with the reason.
An archived dashboard stays readable. It leaves dashboards list unless you pass --include-archived, and deploying its code again leaves it archived.
Live gets dashboards by promotion. A promotion carries each dashboard to live by key, archive state included. Groups aren't copied, so a panel filtered on a group live doesn't have reads group-not-found there.

View dashboards in Console

Open Analytics and pick a dashboard in the switcher beside the range. The switcher lists Project analytics first, then the dashboards that aren't archived, in dashboards list order. A dashboard has its own address, /analytics/KEY.

Range. A dashboard opens at its defaultRange. Choose 7 days, 30 days, 90 days or All time to read it over another range.
Panels. Sections and panels follow the definition on a 4-column grid at each panel's width, in one column on a narrow screen. A number panel shows the total and the change against the previous range, a line or bar panel the series (one line or stacked bar per row, top 8 and Other, when broken down), and a table panel each row's total and change. Archived quests, offers and programs are labelled Archived.
States. A panel with nothing in the range says No activity in this range. A rate below its minimum shows —; hover it for the minimum. A panel that failed shows its error, with Retry for panel-timeout and panel-failed, and the other panels still show.
Archive. In test, people with publish permission can choose Archive dashboard and give a reason. An archived dashboard's address still opens it, with an Archived banner and Unarchive dashboard. Live has neither action: dashboards reach live by promotion.

Dashboards change in code; Console can't edit them.

Give a sponsor, client or partner the Viewer role to show them the project's dashboards and nothing else. Viewers see no members, evidence, quests or settings, and dashboards show only totals, never individual members.

Invite them to your organization: Settings → Access → Team → Manage members.
Under Project permissions, choose them, check Viewer, and check the environments whose dashboards they see, usually Live.
To end their access on its own, such as 30 days after an event, pick the day under Access ends (UTC, optional).
Choose Save project access.

When they sign in, Console shows them only Analytics, opened on the project's first dashboard, with the switcher listing the others. Project analytics isn't theirs: it can show individual members. A project with no dashboards in that environment shows No dashboards yet. After the end date their access stops, and the grant stays listed as Expired.