Dashboard Data & Expressions
Dashboard Data & Expressions
Section titled “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.
Native Asset Source
Section titled “Native Asset Source”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.
Your Own Requests
Section titled “Your Own Requests”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.
Data Processor Parameters
Section titled “Data Processor Parameters”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 systemEach 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.
Cross-Source Joins
Section titled “Cross-Source Joins”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: trueType 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.
Row Filtering (filter:)
Section titled “Row Filtering (filter:)”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'] -> matchesrows[properties.tier='production' and properties.os_version='Ubuntu 22.04'] -> and: native operator, worksrows[not properties.tier='staging'] -> PARSE ERROR — not a keywordrows[$not(properties.tier='staging')] -> correct: $not() is a functionand/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.
Sorting and Top-N (^(...), slicing)
Section titled “Sorting and Top-N (^(...), slicing)”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, descendingWrap 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.
Count, Sum, and Arithmetic
Section titled “Count, Sum, and Arithmetic”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 rowsettings: metric: "$sum(rows[vendor_tier='high_risk'].totals.amount)" # arithmetic over the join-enriched rowsPer-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.
