Dashboard Tiles
Dashboard Tiles
Section titled “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.
Choosing a tile type
Section titled “Choosing a tile type”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.
Common fields
Section titled “Common fields”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.
row_path and the response root
Section titled “row_path and the response root”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]} }) )Per-row vs whole-set expressions
Section titled “Per-row vs whole-set expressions”| 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). |
Column types
Section titled “Column types”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 |
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:
metricis whole-set JSONata, e.g.$sum(rows.amount)or$count(rows[status='open']).- With
aggset,metricis a plain per-row field, reduced byagginstead.
Template kpi_badge
Section titled “Template kpi_badge”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.
Template progress
Section titled “Template progress”A number toward a target, shown as a progress bar with its percentage.
template: progresssettings: 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.
Template gauge
Section titled “Template gauge”A number on a half-circle dial between min and max. Use it for bounded scores such as SLA %, satisfaction or utilisation.
template: gaugesettings: 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. |
Template status
Section titled “Template status”A coloured word or short phrase instead of a number — a payment status, an account standing.
template: statussettings: 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. |
Settings every template takes
Section titled “Settings every template takes”| 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: progresssettings: 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) |
| The formatted value, with its change (kpi_badge) or “x% of target” (progress) |
summary_card
Section titled “summary_card”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).
Colours (tones)
Section titled “Colours (tones)”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.
Highlight
Section titled “Highlight”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) |
| The number and caption, the boxes as coloured text, the highlighted item and the button as links |
bar_chart
Section titled “bar_chart”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: sumSeveral 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 |
| A data table (mail clients strip chart graphics) |
line_chart
Section titled “line_chart”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, …}] |
| A data table |
scatter
Section titled “scatter”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}] |
| A data table |
pie_chart
Section titled “pie_chart”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 |
| A data table |
funnel
Section titled “funnel”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 |
| 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.
heatmap
Section titled “heatmap”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. |
| A data table |
timeline
Section titled “timeline”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 |
| A table of time, event and detail |
detail_card
Section titled “detail_card”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 } |
| The status and the label/value pairs as text; buttons are left out. |
card_list
Section titled “card_list”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 |
| One block per card (first 50); buttons are left out. |
attention_list
Section titled “attention_list”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.
Buttons (actions)
Section titled “Buttons (actions)”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,httpsandmailtoonly-and1.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.
Text filled from data
Section titled “Text filled from data”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.
Validation summary
Section titled “Validation summary”The dashboard validator rejects these when the dashboard is saved:
- A tile without exactly one of
data_processor/source, excepttext(neither, or one when it is filled from data) andattention_list(sources go on each item). - A
card_listwithoutheadline, adetail_cardwithoutfields, anattention_listwithoutitemsor with an item that has no source ortitle. - A button with not exactly one of
workflow/href/tab, anhrefthat isn’t an app path or http(s) URL, atabthat isn’t a layout section, aworkflowthat doesn’t exist or isn’t active, orprefill/enabled_whenon a header button. - A tone that isn’t
success,info,warning,errororneutral;show_ifon a text tile without a data source. - A
summary_cardwithoutheadline, with more than 4breakdownboxes, with a link that isn’t an app path or http(s) URL, or withlink: asseton a tile that doesn’t usesource: 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_bythat isn’t one of the table’s column labels.- An unknown column
type, ormax/currency/link_text/visible/tag_toneson a column of another type, or acurrencythat isn’t a 3-letter ISO code. yandseriesboth set on a bar chart.limit/max_slicesthat aren’t positive integers.- An unknown stat template, or
settingsthat don’t match the template. - JSONata that doesn’t parse, in any expression field.
- A
from_controlnaming a control that doesn’t exist. Derived keys such asperiod_fromandprice_mincount as existing.
Suggestions
Section titled “Suggestions”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.
