Skip to content

Dashboard Data & Expressions

Every data-backed tile gets its rows either from a connector (data_processor) or from the native asset registry (source: { type: asset }). This page covers both sources, how params and joins feed them, and the JSONata expressions used to filter, sort and aggregate the rows.

A tile can read your company’s asset registry directly — no connector needed. Use source instead of data_processor. Asset tiles take no params; to filter one by a control, read the control in its filter as $controls.<name> (see Control values in expressions).

- id: server_baselines
type: table
source:
type: asset # replaces data_processor entirely for this tile
category: server # one category; or categories: [server, laptop] to union several
filter: "properties.tier = 'production' and properties.os_version = 'Ubuntu 22.04'"
columns:
- { label: "Name", path: "name" }
- { label: "OS Version", path: "properties.os_version" }

Visibility is per viewer: a tile only shows the assets the person looking at it can see in the Assets page (assets they own, or whose view_roles match their roles). Two people can see different rows on the same tile.

Each row is { uuid, name, properties }, so expressions read name and properties.<field>, and uuid identifies the asset for links. Asset tiles take no row_path. Set category for one category, or categories (a non-empty list) to read the union of several. Use one of those keys, not both. Visibility is the same either way.

source: { type: workflow_instances } lists the viewer’s own workflow requests, newest first — never anyone else’s. Use it for a “Requests” list on a portal:

- id: my_requests
type: card_list
label: "Requests"
source:
type: workflow_instances
requested_by: viewer # the only option
workflows: ["Supplier Change Request", "Certificate Renewal"] # optional: only these workflows
headline: "workflow"
detail: "reference & ' · ' & status_label"
status: { text: "status_label", tone: "status = 'approved' ? 'success' : 'info'" }
actions:
- { label: "Open", href: "/approvals/{{uuid}}" }

Each row has uuid, reference (e.g. REQ-1042), workflow, title, status (draft, in_progress, approved, rejected, cancelled, error), status_label (e.g. “In review”), current_step, submitted_at, decided_at, data (the request’s own form fields) and href. There is no row_path.

Tile data_processor.params[] uses the same format as workflow data steps, plus two dashboard-only sources:

data_processor:
source_name: "Vendor Spend SQL"
params:
- name: date_from
from_control: date_from # reads a Dashboard control's resolved value
- name: cursor
from_asset: sync-checkpoint
property: $.last_cursor
- name: api_version
value: "v3"
- name: member_email
from_viewer: email # the person viewing the dashboard: employee_id or email
- name: partner_id
from_viewer: external_ids.odoo # that person's id in another system

Each param entry requires exactly one source: from_control, from_viewer, from_asset (+ optional property), or value.

A multi-value select resolves to a list. When that list goes into a REST URL, write the placeholder in the data source as {{name:csv}} so it arrives as a,b (e.g. daily={{daily:csv}}). Without the suffix, the list renders as ['a', 'b'], which most HTTP APIs reject. In a JSON request body the list is sent as a real array either way. The full list of suffixes is under “Typed Placeholders” in the ApprovalML Syntax Reference.

from_control can also target a range control’s derived keys: <name>_from / <name>_to for a date_range_preset, and <name>_min / <name>_max for a number_range.

from_field is not valid on a dashboard tile. It reads a workflow request’s form fields, and a dashboard has no form, so the param would never be sent. The dashboard validator rejects it; use from_control for a user-chosen value or from_viewer for the current user instead.

The reverse also holds: from_control and from_viewer are only valid on dashboard tiles. A workflow step has no controls and no viewer, so the workflow validator rejects both.

from_viewer: external_ids.<system> reads the viewer’s id in another system — the value an administrator entered under People Management → Edit Person → External IDs for that system (for example odoo). This is how a supplier or customer portal works: one dashboard is shared with every partner, and each connector tile filters its source by the viewer’s partner id. If the viewer has no id for that system, the tile shows an access error instead of loading — it is never run without the filter.

from_viewer personalizes a data_processor tile per viewer — e.g. “rows where I am a member” — the same effect an asset tile gets automatically (see “Native Asset Source” above). It resolves to the person viewing the dashboard, and in a scheduled subscription to each employee recipient in turn. A recipient added by bare email address (no employee record) never receives a from_viewer tile.

data_processor.join[] enriches each row with fields from a second source, the same way a workflow data step’s join does: the ids from every row are collected and fetched in one call, matched by on, and the picked fields are copied onto each matching row. Rows with no match are left as they are rather than causing an error. See the ApprovalML Syntax Reference — Inline Join for details.

Dashboards extend it with source_type, to join against the asset registry instead of an external connector:

- id: billing_with_server_tier
type: table
data_processor:
source_name: "Billing Export SQL"
join:
- field: server_name
source_type: asset # data_source (default) | asset
category: server # optional, narrows the candidate set
on: name # assets are matched by name
pick: { tier: properties.tier, owner: properties.owner_name }
row_path: "data"
Field Required Default Description
field Yes — FK field name on each primary row — a single id or a list of ids (e.g. an order’s order_line: [123, 456]); every id in the list is looked up.
source_type No data_source data_source | asset.
source_id / source_name One required, unless source_type: asset — Which second data source to fetch. Must be absent when source_type: asset.
category No — Narrows the asset candidate set — only meaningful when source_type: asset.
on No "id" Key field to match against on the joined records (assets: typically "name").
pick No "name" Single field, or {output_field: source_field, ...} for several at once.
as Required if pick is a string — Output field name.
param No "ids" Param name the collected IDs are sent as (data-source joins only).
separator No ", " Joiner when a row has multiple matches.
as_array No false Return a list instead of a joined string.

field/on/pick are shallow dotted paths, not JSONata: properties.tier walks into a nested object, and a purely-numeric segment indexes into a list — product_id.1 reads the display-name half of a connector’s [id, name] pair for a relational field (e.g. Odoo many2one), product_id.0 reads the id half. Picking a field like that without an index (pick: product_id) returns the raw pair stringified as one value (e.g. "[2778, 'Widget']") rather than the name — index into it instead. This dotted-path/list-index behavior is dashboard-specific; the workflow join linked above only reads flat top-level field names.

Whole-record pick. pick: "$" (or {output_field: "$"} inside a dict pick) attaches each matched record as-is instead of extracting one field — use it to pull in every joined field at once rather than listing them one by one:

join:
- field: order_line
source_id: src_...
on: id
pick: { lines: "$" } # every field of each matched order line
as_array: true

Type preservation. With as_array: true, picked values keep their original type from the source record — a numeric field stays a number so $sum(rows.lines.price_total)-style arithmetic works downstream without casting. Without as_array (the default), multiple matches are joined into a single string via separator, which necessarily stringifies each value first — that’s the only case where a picked value becomes text.

Available on every tile type — not just table. A JSONata predicate evaluated against the whole rows array, applied once, after row extraction and join enrichment, before any tile-type-specific processing:

filter: "properties.tier = 'production' and properties.os_version = 'Ubuntu 22.04'"
rows[properties.tier='production'] -> matches
rows[properties.tier='production' and properties.os_version='Ubuntu 22.04'] -> and: native operator, works
rows[not properties.tier='staging'] -> PARSE ERROR — not a keyword
rows[$not(properties.tier='staging')] -> correct: $not() is a function

and/or work as keywords; negation is not a not keyword — it’s the $not(...) function. The dashboard validator checks every expression when you save, so a not mistake is reported then rather than when the tile runs.

Sort with ^(<field) (ascending) / ^(>field) (descending). To then take the first N rows, the range operator (..) only parses as an array literal — it is not a valid index predicate directly against an expression:

rows ^(>amount) [0..4] -> PARSE ERROR — "Expected ], got .."
rows ^(>amount) [[0..4]] -> correct: top 5 rows by amount, descending

Wrap the range in its own brackets: the inner [0..4] builds the index array [0,1,2,3,4], and the outer [...] applies it against the sorted array. This differs from some other JSONata implementations, where single-bracket expr[0..4] slicing is valid.

For a ranked list in a table tile, the simpler option is usually the tile’s own sort_by + limit — see Dashboard Tiles.

stat metrics, and the grouped values of bar_chart/pie_chart/funnel when agg: is omitted, are evaluated as a single JSONata expression against the whole row array — {"rows": [...]} — not per row:

$sum(rows.amount) -> 1600
$count(rows) -> 3
$average(rows.amount) -> 533.33...
$count(rows[status="error"]) -> 2 (filtered count)
(1 - $count(rows[status="error"]) / $count(rows)) * 100 -> 33.33 (ratio / health-score style)
$sum(rows.amount) + $sum(rows[status="error"].amount) -> 2300 (combined sum)
rows{region: $sum(amount)} -> {"US": 700, "EU": 900} (group-by)

JSONata’s aggregate functions ($sum, $count, $average, $max, $min), arithmetic operators, predicate filtering and object grouping cover count, sum, ratio, combined sums and group-by. agg: sum|avg|count|min|max is optional shorthand for the common single-field case: with it, the field is a plain path reduced by the named function.

Combined with a join — since join enrichment runs before metric/y evaluation, an arithmetic expression can reference a field a join just attached:

data_processor:
source_name: "Vendor Spend SQL"
join:
- field: vendor_id
source_name: "Vendor Master"
on: id
pick: { vendor_tier: risk_tier } # attaches vendor_tier to each row
settings:
metric: "$sum(rows[vendor_tier='high_risk'].totals.amount)" # arithmetic over the join-enriched rows

Per-row vs. whole-set context — which fields see one row and which see all rows is listed per tile type in Dashboard Tiles — Per-row vs whole-set expressions.