Skip to content

Dashboard Tiles

A tile is one panel on a dashboard. This page covers:

  • choosing a type,
  • the fields every tile shares,
  • each tile type’s configuration, the data it produces, and how it renders.

Where a tile’s rows come from (connector or asset), and how JSONata is evaluated against them, is covered in Data & Expressions. Placing tiles on the page is covered under Layout.

Pick the type by what the tile has to show. Variants are options on a type, not separate types.

To show… Use Useful options
One number stat template kpi_badge (with change), progress (toward a target), gauge (on a min–max dial), caption
A state rather than a number (“Ready”) stat template status
A number with context summary_card up to 4 coloured boxes, the most critical item, a button
A trend over time line_chart area, stacked
Categories side by side bar_chart series + stacked, horizontal
A relationship between two measures scatter size, quadrants
Intensity across two categories heatmap value + agg
Share of a whole pie_chart donut, max_slices
Drop-off between ordered stages funnel stages
Rows and columns, or a ranked list table sort_by, limit, per-column type (bar, tag, currency…)
Recent events timeline limit
One record’s details (a company profile, a bank account) detail_card status, masked fields, buttons
A list of things (certificates, deliveries, requests) card_list status, accent, line items, buttons
What needs attention, gathered from several sources attention_list one items entry per source
Notes, headings, links, banners text tone; placeholders filled from data

An option set on a type that doesn’t support it (e.g. donut on a table) is a validation error, not silently ignored.

tiles:
- id: top_vendors # Required, unique within the dashboard
type: table # see the types below
label: "Top Vendors" # Title shown on the tile
description: "Highest approved spend this period" # Optional subtitle
view_roles: ["finance_manager"] # Optional — narrows who sees this tile
data_processor: # One of data_processor / source (text tiles take neither)
source_name: "Vendor Spend SQL"
params: []
# source: { type: asset, category: server }
row_path: "data" # JSONata — where the row array is (connector tiles only)
filter: "amount > 0" # Optional JSONata predicate over the rows
Field Applies to Description
id all Unique identifier, referenced from layout.sections[].grid / .columns. Renaming a tile in Studio updates the layout too.
type all table | stat | bar_chart | scatter | line_chart | pie_chart | funnel | heatmap | timeline | text | summary_card
label all The tile’s title. It also names the sheet in the Excel export and heads the tile in subscription emails. The key is label, not title (title belongs to layout sections). Always set it.
description all Optional subtitle under the title, in the viewer and in emails.
view_roles all Narrows the dashboard’s own view_roles for this tile. Omit it to inherit. Company admins and the dashboard’s creator always see every tile. A viewer who can’t see a tile never receives it at all.
data_processor data tiles A connector data source: source_id or source_name, plus params and join. See Data & Expressions.
source data tiles { type: asset, category: <category> } or { type: asset, categories: [<category>, ...] } — the native asset registry, filtered per viewer. categories is the union of those categories. See Native Asset Source.
row_path data_processor tiles JSONata selecting the row array from the response (see below). Not used with source: asset.
filter data tiles JSONata predicate over the whole row array, applied after row_path and joins, before the type-specific shaping.

Every tile except text needs exactly one of data_processor or source.

The root that row_path sees depends on what the connector returned:

Connector returned JSONata root Typical row_path
A bare list […] {"data": […]} — wrapped for you "data"
A JSON object {…} The object itself, as-is The real key holding the rows, e.g. "records"

REST connectors already normalise their result into {"data": [...]}, so row_path: "data" is the usual value for them too.

Never start from $. It points at the whole root, not at the rows, and fails silently:

  • An inline group-by such as $ {...} returns nothing, so the tile renders empty with no error.
  • Other tile types get the root object as one bogus row.

Start from data (or the real key) instead.

row_path can also build rows, for example by zipping columnar arrays:

row_path: >-
( $d := data.daily; $map($d.time, function($t, $i) {
{"day": $t, "tmax": $d.temperature_2m_max[$i]}
}) )
Context Fields rows available?
Per row — evaluated once per row table.columns[].path, scatter.x/y/size/point_label, line_chart.x/series[].path, bar_chart.x, pie_chart.x, funnel.x, heatmap.x/y/value, timeline.time/headline/detail No — reference fields directly (amount)
Whole set — evaluated once over all rows stat settings.metric/compare_metric/target_metric Yes — $sum(rows.amount)
Per group — evaluated once per x group bar_chart.y/series[].path, pie_chart.y, funnel.y, when agg is not set Yes, the group’s rows only

With agg set (sum | avg | count | min | max), the grouped fields above are plain per-row fields, reduced by agg instead.

Rows and columns. Each column can set a display type. With sort_by + limit and a bar column, a table becomes a leaderboard.

- id: top_vendors
type: table
label: "Top 10 vendors by spend"
data_processor: { source_name: "Vendor Spend SQL" }
row_path: "data"
columns:
- { label: "Vendor", path: "vendor.name" }
- { label: "Tier", path: "vendor.tier", type: tag }
- { label: "Total spend", path: "totals.amount", type: bar }
- { label: "Spend (IDR)", path: "totals.amount", type: currency, currency: IDR }
- { label: "Last order", path: "last_order_at", type: relative }
sort_by: "Total spend"
sort_order: desc
limit: 10
Field Required Description
columns Yes Non-empty list of { label, path, type? }. path is per-row JSONata, label becomes the column header, and type sets how the cell is shown (below).
sort_by No A column label. Rows are sorted server-side before limit; empty values go last.
sort_order No desc (default) or asc.
limit No Keep only the first N rows (positive integer).

A column’s type only changes how a cell is shown. Sorting by clicking a header, CSV export and the Excel workbook always use the raw value, so Rp 9.000 still sorts below Rp 10.000 and dates sort chronologically. A value that doesn’t fit the type (e.g. text in a number column) is shown as plain text rather than left blank.

type Shows Example Option
text (default) The value as-is eu-web-01 —
bar The number with a proportional bar 3,200 ████░ max — fixed scale (e.g. 100 for a percentage, which turns it into a progress bar). Without it, bars scale to the largest value in the column.
tag The value as a chip. A list shows one chip per item. approved tag_tones — colours for known values, e.g. { Paid: success, Overdue: error } (tones: success, info, warning, error, neutral). Other values stay neutral.
number Thousands separators, up to 2 decimals 1,234,567.5 —
currency A money amount IDR 1,234,567 currency — 3-letter ISO code in capitals, default USD
percent The value with a % sign. The value is already 0–100. 72.5% —
date The date only 13 Oct 2026 —
datetime Date and time 13 Oct 2026, 14:05 —
relative Time relative to now; the full date shows on hover 3 hours ago —
boolean ✓ or — (true, "yes" and 1 count as true) ✓ —
link A clickable link that opens in a new tab. Only http/https URLs become links; anything else shows as text. Open ↗ link_text — fixed link text. Without it, the URL itself is shown.
masked Only the last characters, e.g. for a bank account or ID number. Masked on the server, so the full value never reaches the browser, the CSV export or an email. •••• 6622 visible — how many trailing characters stay readable, default 4

Number, currency and date formats follow the viewer’s browser locale. max, currency, link_text, visible and tag_tones are only valid on their own column type.

Produces [{ "<column label>": value, ... }, ...]
Viewer A sortable table (click a header). It starts in the server-side order. Object/array values render as compact JSON.
Export CSV per tile, and the dashboard’s Export to Excel writes one sheet per table tile
Email An HTML table of the first 50 rows, with the full data attached as CSV. Column types are applied as text: bars show just the number, tags a comma-separated list, and relative an absolute date and time.

One number, shown as a card. template decides the card, and settings is validated against that template’s own schema.

- id: total_spend
type: stat
label: "Total spend"
template: kpi_badge
data_processor: { source_name: "Vendor Spend SQL" }
row_path: "data"
settings:
layout: badge
format: currency
metric: "totals.amount"
agg: sum
compare_metric: "totals.prior_period_amount"
compare_label: "vs last month"
Field Required Description
template Yes kpi_badge, progress or gauge.
settings Yes Depends on the template (tables below).

Every template shares the same metric rules:

  • metric is whole-set JSONata, e.g. $sum(rows.amount) or $count(rows[status='open']).
  • With agg set, metric is a plain per-row field, reduced by agg instead.

A number, optionally with its change against a comparison value.

Setting Default Description
metric — (required) The headline number.
agg none sum | avg | count | min | max. Also applies to compare_metric.
compare_metric none Same shape as metric, over the same rows (no second query). Enables the change indicator.
compare_label none Text next to the change, e.g. "vs last month".
higher_is_better true false flips the colouring, so a rise renders as bad (e.g. error counts, cost).
format number number | currency | percent
layout inline inline | badge | value_first | historical — presentation only.

The server computes change_amount, change_pct and change_type (positive/negative/neutral) from metric and compare_metric. They are never written in YAML.

A number toward a target, shown as a progress bar with its percentage.

template: progress
settings:
metric: "totals.amount"
agg: sum
target: 500000 # or target_metric: "$sum(rows.budget)"
format: currency
higher_is_better: false
Setting Default Description
metric — (required) The value.
agg none As above.
target — A fixed target number.
target_metric — The target as JSONata, evaluated like metric (e.g. a budget column).
format number number | currency | percent
higher_is_better true false when going past the target is bad (budget spent). The bar then turns red past 100%.

Set exactly one of target or target_metric. The server adds target and progress_pct to the result.

A number on a half-circle dial between min and max. Use it for bounded scores such as SLA %, satisfaction or utilisation.

template: gauge
settings:
metric: "sla_pct"
agg: avg
min: 90
max: 100
format: percent
Setting Default Description
metric — (required) The value on the dial.
agg none As above.
min 0 Lower end of the dial.
max — (required) Upper end; must be greater than min.
format number number | currency | percent
higher_is_better true Colours the dial green toward the good end, red toward the bad.

A coloured word or short phrase instead of a number — a payment status, an account standing.

template: status
settings:
metric: "$count(rows[allow_out_payment]) > 0 ? 'Ready' : 'On hold'"
tone: "$count(rows[allow_out_payment]) > 0 ? 'success' : 'warning'"
caption: "'Paid to ' & rows[0].bank & ' •••• ' & $substring(rows[0].account, -4)"
Setting Default Description
metric — (required) Whole-set JSONata returning the text shown.
tone neutral Whole-set JSONata returning success, info, warning, error or neutral. Anything else shows neutral.
Setting Description
caption Whole-set JSONata returning the line of text under the value, e.g. "$string($count(rows)) & ' invoices in progress'". Only the result is sent to the viewer.
currency 3-letter ISO code (e.g. IDR) used when format: currency. Default USD.

progress also takes display_metric: whole-set JSONata for the big number when it should differ from the bar — for example credit available as the number while the bar fills with credit used:

template: progress
settings:
format: currency
currency: IDR
metric: "rows[0].credit" # the bar
target_metric: "rows[0].credit_limit"
display_metric: "rows[0].credit_limit - rows[0].credit" # the number
higher_is_better: false
caption: "'Rp ' & $formatNumber(rows[0].credit, '#,##0') & ' used of Rp ' & $formatNumber(rows[0].credit_limit, '#,##0')"

Use $formatNumber(x, '#,##0') for numbers in a caption, and $fromMillis($toMillis(d), '[D01] [MNn,*-3] [Y]', '+0700') for dates — pass your UTC offset as the third argument, since many systems store times in UTC.

Produces { value, template, render_as, settings, … }, plus change_* for kpi_badge and target/progress_pct for progress
Export No CSV (a single value)
Email The formatted value, with its change (kpi_badge) or “x% of target” (progress)

A card with a big number, up to four coloured boxes, the single most important item and a button. Use one per category, for example one card per asset type on an expiry dashboard.

- id: api_tokens_card
type: summary_card
label: "API tokens"
source: { type: asset, category: expiry_item }
filter: "properties.asset_type = 'api_token'"
badge: { metric: "$count(rows)", suffix: "tracked" }
headline:
metric: "$count(rows[$toMillis(properties.expires_at) < $toMillis($controls.period_to) + 86400000])"
caption: "expiring in the selected period"
breakdown:
- label: "Owner left the company"
metric: "$count(rows[properties.issue = 'owner_left'])"
tones: { error: 1 }
- label: "Unused 90+ days"
metric: "$count(rows[properties.issue = 'unused'])"
tones: { warning: 1 }
highlight:
title: "Most critical"
sort_by: "properties.expires_at"
name: "name"
detail: "properties.note"
tag:
value: "$round(($toMillis(properties.expires_at) - $millis()) / 86400000)"
suffix: "days"
tones: { error_below: 7, warning_below: 30 }
link: asset
action:
label: "Review API tokens"
href: "/activities?tab=assets&category=expiry_item&q=API%20token"
Field Required Description
headline Yes { metric, caption? } — the big number and the text next to it. On a summary_card, headline is an object; on a timeline it’s a per-row expression.
badge No { metric, suffix? } — a small figure in the top-right corner, e.g. “86 tracked”.
breakdown No Up to 4 boxes, each { label, metric, tones? }.
highlight No The most important row (below).
action No { label, href } — the button at the bottom.

Every metric is a whole-set expression over the tile’s rows, after filter, e.g. $count(rows[...]) or $sum(rows.amount).

A box or tag is coloured from its value. Rules are checked in the order error → warning → success, and the first match wins. No match, or a non-number, is neutral grey.

Rule Meaning
error: 3 Red when the value is ≥ 3
warning: 1 Amber when ≥ 1
success: 10 Green when ≥ 10
error_below: 7 Red when the value is < 7 (e.g. days left)
warning_below: 30 Amber when < 30
success_below: n Green when < n

Colours are a fixed set that works in light and dark mode. Custom colour codes aren’t supported.

The highlight takes the rows, sorts them by sort_by (sort_order: asc by default) and shows the first one.

Field Required Description
title No Small heading, e.g. “Most critical”.
sort_by Yes Per-row expression to sort by. Rows where it is empty or null are skipped, so you can exclude rows with a condition, e.g. status != 'closed' ? expires_at : null.
sort_order No asc (default) or desc.
name Yes Per-row text shown as the item’s name.
detail No Per-row text shown under the name.
tag No { value, suffix?, tones? } — a coloured tag next to the name, e.g. “3 days”.
link No asset — the name opens that asset. Only on source: asset tiles.
href No A link for the name instead of link. {{field}} placeholders take values from the highlighted row, e.g. /activities?tab=assets&asset={{uuid}}.

action.href and highlight.href must be one of:

  • an app path starting with /, which opens inside Aptiwise, or
  • an http(s) URL, which opens in a new tab.

Anything else is a validation error. Placeholder values are URL-encoded, so row data can’t change where a link points. Useful app paths:

Link to Path
The asset list filtered to a category, schema and/or text /activities?tab=assets&category=<category>&schema_id=<id>&q=<text>. schema_id selects that asset schema. q matches an asset’s name or any of its property values. The same query works on /admin/assets.
One asset link: asset, or /activities?tab=assets&asset={{uuid}}
Produces { badge, headline, breakdown[{label, value, tone}], highlight, action }
Export No CSV (a summary, not rows)
Email The number and caption, the boxes as coloured text, the highlighted item and the button as links

Compare categories. Rows are grouped by x, and each group gets one value per series.

- id: spend_by_region
type: bar_chart
label: "Spend by region"
data_processor: { source_name: "Vendor Spend SQL" }
row_path: "data"
x: "vendor.region" # per-row grouping key
y: "totals.amount" # plain field, reduced by agg
agg: sum

Several series per category, stacked and laid out horizontally:

- id: cost_by_region
type: bar_chart
label: "Cost by region and environment"
x: "region"
agg: sum
series:
- { label: "Production", path: "env = 'production' ? cost : 0" }
- { label: "Staging", path: "env = 'staging' ? cost : 0" }
stacked: true
horizontal: true
Field Required Description
x Yes Per-row grouping key, which becomes the category axis.
y Yes, unless series The value per group. A plain field with agg, or whole-group JSONata without agg, e.g. $sum(rows.amount) - $sum(rows.refund).
agg No sum | avg | count | min | max
series No [{ label, path }] instead of y. Each path is computed per group the same way y is. Never set both.
stacked No Stack the series instead of drawing them side by side (needs series).
horizontal No Bars run left to right, which reads better with long category names.
Produces [{x, y}], or [{x, "<series label>": value, …}] with series
Email A data table (mail clients strip chart graphics)

A trend over time: one or more series sharing one x. There is no grouping: each row is one point.

- id: approvals_trend
type: line_chart
label: "Approved vs rejected, by day"
data_processor: { source_name: "Approvals per day" } # one row per day, already aggregated
row_path: "data"
x: "day"
series:
- { label: "Approved", path: "approved" }
- { label: "Rejected", path: "rejected" }
area: true
Field Required Description
x Yes Per-row x value, shared by every series.
series Yes At least one { label, path }. A row missing a series field leaves a gap in that line.
area No Fill under each line.
stacked No Stack the series on top of each other (drawn as areas).

Aggregate in the query or in row_path, not here. A line chart has no agg.

Produces [{x, "<series label>": value, …}]
Email A data table

Each row is one point. Use it to show the relationship between two measures, optionally with sized bubbles and quadrant lines.

- id: cpu_vs_cost
type: scatter
label: "CPU vs cost"
source: { type: asset, category: server }
x: "properties.cpu_utilization"
y: "properties.monthly_cost"
size: "properties.monthly_cost"
point_label: "name"
quadrants:
x_threshold: 70
y_threshold: 1500
labels: { high_high: "Right-size first", low_low: "Fine" }
Field Required Description
x, y Yes Per-row values.
size No Per-row bubble size; a missing value gets a default size.
point_label No Per-point tooltip text. It is not label, which is always the tile title.
quadrants No x_threshold, y_threshold, and labels with any of high_high, high_x_low_y, low_x_high_y, low_low.
Produces [{x, y, size, label}]
Email A data table

Share of a whole. Grouping works exactly like bar_chart with a single y.

- id: requests_by_status
type: pie_chart
label: "Requests by status"
x: "status"
y: "id"
agg: count
donut: true
max_slices: 6
Field Required Description
x Yes Per-row category, one slice each.
y Yes Value per slice. A plain field with agg, or whole-group JSONata. No series.
agg No As in bar_chart.
donut No Cut out the centre.
max_slices No At least 2. Slices beyond it merge into one “Other” slice.
Produces [{x, y}], largest first
Viewer Slices with percentage labels (hidden under 5%) and a legend
Email A data table

Drop-off between ordered stages.

- id: approval_funnel
type: funnel
label: "Request pipeline"
x: "stage"
y: "id"
agg: count
stages: ["submitted", "reviewed", "approved", "paid"]
Field Required Description
x Yes Per-row stage name.
y Yes Value per stage, grouped like bar_chart.
agg No As in bar_chart.
stages No Explicit stage order. x values not listed are left out. Without it, stages appear in first-seen order.
Produces [{x, y, pct_of_first, pct_of_prev}]
Viewer Centred bars sized against the largest step, with each step’s % of the first and conversion from the previous
Email A table with the % of the first step

Each row counts toward one stage. For a cumulative funnel (“reached at least stage N”), build the stage rows in row_path instead, e.g. with $count(...) per threshold.

Intensity across two categories, such as day × hour or region × environment.

- id: servers_by_region_env
type: heatmap
label: "Servers by region × environment"
source: { type: asset, category: server }
x: "properties.region"
y: "properties.environment"
# value: "properties.monthly_cost"
# agg: sum
Field Required Description
x Yes Per-row category, which becomes the grid columns.
y Yes Per-row category, which becomes the grid rows.
value No Per-row number reduced by agg per cell. Without it, each cell is the row count.
agg No Used with value; default sum.
Produces [{x, y, value}]
Viewer A grid whose cell colour intensity scales to the largest value. Axes keep first-seen order.
Email A data table

Recent events, newest first.

- id: recent_requests
type: timeline
label: "Latest purchase requests"
source: { type: asset, category: purchase_request }
time: "properties.submitted_at"
headline: "name & ' — ' & properties.department"
detail: "properties.requester & ' · ' & properties.stage"
limit: 10
Field Required Description
time Yes Per-row date or datetime; sorts the feed newest first. Rows without one go last.
headline Yes Per-row main text.
detail No Per-row secondary text.
limit No Maximum events; default 20.
Produces [{time, headline, detail}]
Viewer A vertical feed with relative times (“3h ago”, “2d ago”) for the last week, dates beyond that
Email A table of time, event and detail

One record shown as label/value pairs, with a status pill in the header and buttons underneath — a company profile or a bank account. It reads the first row after filter.

- id: bank_card
type: detail_card
label: "Bank account"
data_processor:
source_name: "Partner Bank Accounts"
params:
- { name: partner_id, from_viewer: external_ids.odoo }
row_path: "data"
status:
text: "allow_out_payment ? 'Verified' : 'Pending verification'"
tone: "allow_out_payment ? 'success' : 'warning'"
fields:
- { label: "Bank", path: "bank_id[1]" }
- { label: "Account number", path: "acc_number", type: masked }
- { label: "Account holder", path: "acc_holder_name" }
actions:
- { label: "Request a change", workflow: "Supplier Change Request" }
Field Required Description
fields Yes Same shape as table columns — label, path (per row), optional type and its option.
status No { text, tone }, both per-row JSONata.
actions No Buttons — see Buttons.
empty_text No Shown when there is no row.
Produces { record: { "<label>": value } | null, status, actions }
Email The status and the label/value pairs as text; buttons are left out.

One card per row — certificates, deliveries, addresses, requests. Each card has a title, an optional meta line and status pill, label/value fields, line items, a note and buttons.

- id: deliveries
type: card_list
label: "Incoming"
data_processor:
source_name: "Customer Deliveries"
params:
- { name: partner_id, from_viewer: external_ids.odoo }
join:
- { field: move_ids, source_name: "Stock Moves by IDs", param: ids, on: id, pick: { lines: "$" }, as_array: true }
row_path: "data"
sort_by: "scheduled_date"
headline: "name"
status:
text: "state = 'in_transit' ? 'On the way' : 'Scheduled'"
tone: "state = 'in_transit' ? 'info' : 'neutral'"
accent: "state = 'in_transit' ? 'info' : null"
fields:
- { label: "Expected", path: "scheduled_date", type: datetime }
- { label: "To", path: "partner_id[1]" }
items: { path: "lines", label: "product_id[1]", value: "product_uom_qty", unit: "pcs" }
note: "driver ? null : 'Driver and plate appear here when the truck leaves.'"
actions:
- { label: "Verify delivery", workflow: "Customer Delivery Verification", prefill: { picking_id: "id" }, style: primary }
Field Required Description
headline Yes Per-row JSONata: the card’s title.
detail No Per-row JSONata: a meta line under the title.
status No { text, tone }, per row.
accent No Per-row JSONata returning a tone — a coloured left border for cards that need a look. null for none.
fields No Label/value pairs, same shape as table columns.
items No Line items: path (per row, a list), label and value (JSONata per list item), unit (fixed text).
note No Per-row JSONata: a line of text at the bottom of the card.
actions No Buttons per card — see Buttons.
sort_by / sort_order No Per-row JSONata to sort by; asc (default) or desc. Empty values go last.
limit No Keep the first N cards.
empty_text No Shown when there are no rows.
Produces [{ headline, detail, status, accent, fields, items, note, actions }, ...]
Export No CSV
Email One block per card (first 50); buttons are left out.

A to-do list gathered from several sources — an expiring certificate, a delivery to check, an overdue invoice. The tile has no data source of its own: each entry in items reads its own, and every row its filter keeps becomes one entry, in item order.

- id: attention
type: attention_list
label: "Needs your attention"
items:
- source: { type: asset, category: supplier_certificate }
filter: "$toMillis(properties.expires_at) - $millis() < 60 * 86400000"
title: "properties.title & ' expires soon'"
detail: "'Upload the renewed certificate to keep receiving purchase orders.'"
tone: warning
action: { label: "Open", tab: certifications }
- data_processor:
source_name: "Open Customer Invoices"
params:
- { name: partner_id, from_viewer: external_ids.odoo }
row_path: "data"
filter: "$toMillis(invoice_date_due) < $millis()"
title: "name & ' is overdue'"
tone: error
Item field Required Description
data_processor or source One of them Where this kind of entry comes from.
row_path, filter No As on any tile.
title Yes Per-row JSONata. A row whose title is empty is skipped.
detail No Per-row JSONata.
tone No info (default), success, warning, error or neutral — the entry’s coloured border.
action No One button — see Buttons.

The tile also takes limit and empty_text. If one item’s source fails to load, its entries are left out and the others still show. Put a section badge on it (see Layout) to show the count on its tab.

detail_card and card_list take actions (buttons per record/card), an attention_list item takes one action, and every tile can show header_actions in its header. Each button needs exactly one target:

Target What happens
workflow: <workflow name> Opens that workflow’s request form. prefill: { <form field>: <per-row JSONata> } fills fields from the row. The form is only filled in — the person reviews and submits it themselves.
href: "/path/{{field}}" Opens an app page (path starting with /) or an http(s) URL. {{field}} takes a value from the row.
tab: <section id> Switches to that section of a tabs layout (or scrolls to it).

Optional: style: primary (filled button) and enabled_when (per-row JSONata; when false the button is shown disabled). Header buttons have no row, so they take neither prefill nor enabled_when.

A dashboard never changes data itself: a change someone asks for is always a workflow request, reviewed through that workflow’s own steps. Because the person can edit prefilled values before submitting, a workflow should look up anything that matters for access (such as their partner id) itself rather than trust a prefilled field.

Notes, headings and links. Without a data source nothing is fetched.

- id: intro
type: text
label: "How to read this dashboard"
content: |
Spend is **approved** spend only. See the [policy](https://example.com/policy).
- Figures refresh on every load
- Click a column header to re-sort
Field Required Description
content Yes A markdown subset (below).

Supported markdown:

  • # / ## / ### headings
  • **bold**, *italic*, `code`
  • [links](https://…) — http, https and mailto only
  • - and 1. lists
  • Paragraphs separated by a blank line

Raw HTML is shown as plain text, never rendered. In emails the content is sent as plain paragraphs.

Set tone: info | success | warning | error to show the text as a tinted banner.

Give a text tile one data_processor or source and its content can contain {{ expression }} placeholders — whole-set JSONata over the rows, like a stat’s metric. show_if (whole-set JSONata) hides the tile while it is false, so a warning only appears when there is something to warn about:

- id: overdue_banner
type: text
tone: warning
data_processor: { source_name: "Open Customer Invoices", params: [ { name: partner_id, from_viewer: external_ids.odoo } ] }
row_path: "data"
filter: "$toMillis(invoice_date_due) < $millis()"
show_if: "$count(rows) > 0"
content: "You have **{{ $count(rows) }}** overdue invoices totalling Rp {{ $formatNumber($sum(rows.amount_residual), '#,##0') }}."

Values inserted by a placeholder are plain text: markdown characters in your data (brackets, asterisks) are shown as typed and never turn into links or formatting. Placeholders in a text tile without a data source are shown as typed.

The dashboard validator rejects these when the dashboard is saved:

  • A tile without exactly one of data_processor / source, except text (neither, or one when it is filled from data) and attention_list (sources go on each item).
  • A card_list without headline, a detail_card without fields, an attention_list without items or with an item that has no source or title.
  • A button with not exactly one of workflow / href / tab, an href that isn’t an app path or http(s) URL, a tab that isn’t a layout section, a workflow that doesn’t exist or isn’t active, or prefill / enabled_when on a header button.
  • A tone that isn’t success, info, warning, error or neutral; show_if on a text tile without a data source.
  • A summary_card without headline, with more than 4 breakdown boxes, with a link that isn’t an app path or http(s) URL, or with link: asset on a tile that doesn’t use source: asset.
  • A $controls.<name> that isn’t a control on the dashboard.
  • Missing required fields for the type, e.g. x/y, columns, series, time/headline, content.
  • An option on a type that doesn’t support it.
  • sort_by that isn’t one of the table’s column labels.
  • An unknown column type, or max / currency / link_text / visible / tag_tones on a column of another type, or a currency that isn’t a 3-letter ISO code.
  • y and series both set on a bar chart.
  • limit / max_slices that aren’t positive integers.
  • An unknown stat template, or settings that don’t match the template.
  • JSONata that doesn’t parse, in any expression field.
  • A from_control naming a control that doesn’t exist. Derived keys such as period_from and price_min count as existing.

Validate in Dashboard Studio also lists suggestions above the YAML editor. A dashboard with suggestions is still valid and can be saved; each one points at something that probably isn’t what you want:

Suggestion Why it matters
A line_chart whose x doesn’t look like a date Line charts show change over time; for categories a bar_chart reads better.
A vertical bar_chart whose x looks like a date A line_chart usually shows a trend more clearly.
A table with limit but no sort_by Without sorting, “the first N rows” is arbitrary rather than a real top N.
A scatter without point_label Points have no name when hovered.
A control that no tile reads It shows on the dashboard but changes nothing.
A control without a default that a tile reads That tile stays empty until the viewer picks a value.
A grid row with more than 4 tiles Only 4 fit side by side; the rest wrap to the next line.
A tile that isn’t in any layout section It is saved but never shown.

When a dashboard is generated with AI, the same suggestions appear in the AI chat. They are joined by advice based on your asset data, for example a pie chart over a field with dozens of different values.