Data access: the data viewer and native dashboards
How operators look at the records OpenSteward has synced: the data viewer
(browse, search, export, reveal) and native dashboards (charts over those
records). Both work on SQLite and Postgres deployments, and both need
DATA_STORE_MODE=database — in passthrough mode nothing is stored, and every
route answers 409 DATA_STORE_DISABLED.
Who may do what is decided by the permission model; how each field is shown is decided by its field classification.
The three hops and what each one trusts
Section titled “The three hops and what each one trusts”| Hop | Authenticates | Decides |
|---|---|---|
| Browser → admin UI | Signed session cookie; CSRF on every POST | What to offer: nav items and buttons follow the permissions from GET /api/auth/me. A convenience, never the enforcement. |
| admin UI → admin-api | The operator’s JWT | Permissions (data:read, data:read_pii, data:export, dashboards:view, dashboards:edit, dashboards:share_all), the audit rows, and the scope it forwards. |
| admin-api → integration-server | The deployment admin secret (X-Admin-Secret, adminGuard) |
Re-checks every connection’s owner tenant against the forwarded scope and applies masking by classification. |
The browser never talks to admin-api or integration-server. Dashboard charts
fetch the admin UI’s own /dashboards/metric/:id, which proxies admin-api
with the session.
integration-server is the only service that can read the stored records (on
SQLite, resources.db is its file), so it enforces scope and masking itself —
defence in depth: a bug in admin-api’s permission checks cannot turn into a
read of another tenant’s data or of unmasked PII, because the scope header it
must send cannot claim more than the operator holds, and integration-server
masks whatever arrives without revealPii.
The scope header
Section titled “The scope header”admin-api builds the scope from the caller’s resolved access
(buildDataScope in apps/admin-api/src/core/routes/data.ts) and sends it as
JSON in X-OpenSteward-Data-Scope:
{ "tenants": ["acme", "globex"], "tenantVerticals": { "acme": ["crm"], "globex": "*" }, "revealPii": true, "maskFinancial": false}| Field | Source | Effect in integration-server (src/data-access/scope.ts) |
|---|---|---|
tenants |
'*' for an unrestricted user; otherwise the granted tenants |
A connection is visible only when its credentials.owner_tenant_id is listed. A connection with no owner is visible only to '*'. |
tenantVerticals |
The verticals granted within each tenant | A connection must also be in a vertical granted for its tenant. |
revealPii |
Set only on a reveal or a PII export, and only when the caller holds data:read_pii |
PII is unmasked only when this is true and the request says ?reveal=pii. Also lets PII fields be filtered. |
maskFinancial |
Runtime setting data_access.mask_financial (default off) |
Masks financial fields, refuses filters on them, and withholds every metric that reads one (see Native dashboards). |
Anything outside the scope answers 404, never 403, so a scope cannot probe
for ids it may not see. admin-api passes integration-server’s 404,
409 DATA_STORE_DISABLED and 400 FIELD_NOT_SEARCHABLE through with their
codes.
Masking
Section titled “Masking”Every record passes through stripRawPayload (in the store) and then
applyMasking with its vertical’s classification before it leaves
integration-server:
secretfields are removed for everyone;piifields are masked (j***@example.com,[REDACTED], …) unless revealed;financialfields are masked only whendata_access.mask_financialis on;metadata/raw(the upstream payload) count as PII unless classified.
Filters and free-text search are limited to fields the caller could see unmasked: a filter on a masked field would answer the question the mask refuses. A resource type with no classification is treated as all-PII.
admin-api sends records as a pre-serialised body so that its response-wide timestamp rewrite never alters a value inside a stored record.
The data viewer
Section titled “The data viewer”| Admin UI | admin-api | integration-server |
|---|---|---|
/data |
GET /api/data/summary |
GET /admin/data/summary |
/data/connections/:id |
GET /api/data/schema/:vertical/:type, GET /api/data/connections/:id/resources/:type |
/admin/data/schema/…, /admin/data/connections/:id/resources/:type (keyset page()) |
| record view | GET …/resources/:type/:rid |
…/:rid |
| Reveal | POST …/resources/:type/:rid/reveal {reason?} |
…/:rid?reveal=pii with revealPii: true |
| Export | GET …/resources/:type/export?format=csv|ndjson&include_pii= |
…/export (streamed, ≤ 100,000 rows) |
- The table is cursor-paginated (keyset on
(updated_at, pk)); the page carries atrailof earlier cursors so Previous needs no server state. - Columns come from the schema’s top-level fields (a column picker overrides the default six); filter boxes are offered only for searchable fields.
- The record view draws a JSON tree (
public/js/json-view.js) with PII / financial badges, and a field-classification table. - Reveal is a CSRF-protected POST that renders the unmasked record with
Cache-Control: no-store. It is never a GET, so it cannot be prefetched, bookmarked or replayed from history. - Export streams admin-api’s response through the admin UI without
buffering.
include_piineedsdata:read_piiat both the UI and admin-api.
Native dashboards
Section titled “Native dashboards”A dashboard is a list of widgets, each naming a metric from
integration-server’s catalog (src/data-access/metrics/catalog/) plus a
chart type and a width. A dashboard stores no query text: what it can show is
bounded by the catalog.
The metric catalog
Section titled “The metric catalog”A metric is a reviewed definition in catalog/<vertical>.ts (one file per
vertical, plus system.ts; catalog/index.ts only concatenates). Types live
in metrics/types.ts; the shared vocabulary — the 22 chart types, units,
sections, granularities and kinds — in @opensteward/shared
(src/dashboards/charts.ts), so admin-api validates widgets against the same
lists.
Every definition names a vertical, a resourceType, a section (where it
sits in the editor: receivables, risk, workload, …) and a kind, plus:
| Field | Meaning |
|---|---|
dateField |
The range anchor. Required unless snapshot. |
snapshot |
Ignore the dashboard range; evaluate as of now (open AR, open tickets). The result’s range is today. |
filters |
Row predicates: eq ne in not_in in_ci is_null not_null gt gte lt lte and the now-relative before_now after_now older_than_days within_last_days within_next_days. ne / not_in keep records without the field. |
compare |
Row-level left op right over two fields of one record — numbers as numbers, dates by day (paidAt <= dueAt). |
currencyField |
For a count whose records carry a currency: makes the currency parameter apply. Must be a currency-code field (see Guards). |
granularity |
Default bucket of a series over time (day / week / month), used for auto or no parameter; an explicit request still wins. |
coverage |
Fields whose presence is reported as coverage: { eligible, total }. |
thresholds |
{ warn, crit, direction } for number / gauge colouring. |
charts |
Overrides the default chart list; the first entry is the default. |
note |
A caveat shown under the widget. |
A measure is count, sum (money: needs its currencyField), avg
(money when it has a currencyField) or sum_quantity (units). Amounts are
integer minor units unless amountUnit: 'major' (CRM). A group is a
field with optional labels, a fixed order (zero-filled; unknown values
after), numeric bands, unnest (count each element of a string array) and
lookup (below). A ratio part, composition component or DSO/DPO
input may read another resource type of the vertical, and may name its
own currencyField (for a count part; a money measure carries one).
in_ci differs by dialect for non-ASCII text. It compares LOWER() of
the field with lower-cased values: SQLite’s LOWER() folds ASCII only
('ÉTÉ' → 'ÉtÉ'), Postgres folds per the database’s collation (Unicode in
the usual UTF-8 locales: 'ÉTÉ' → 'été'). So 'ÉTÉ' matches 'été' on
Postgres but not on SQLite. Keep in_ci values to ASCII vocabularies, as
CRM’s won / closed won lists are.
| Kind | Computes | How |
|---|---|---|
value |
One number (count, avg, quantity) or one total per currency | SQL |
timeseries |
A series per day / ISO week / month, zero-filled; optional splitBy (top 8 + Other) |
SQL |
breakdown |
Top-N groups (default 12) + Other, with share % | SQL |
ratio |
numerator ÷ denominator as a percent (0–100), optionally over time; parts may read another resource type |
SQL per part |
duration |
to − from in days or hours (to may be now): mean, p25/p50/p75/p90, min/max, a histogram and per-group stats (boxplot) |
fetchValues + TypeScript |
aging |
Records by whole days since (past) or until (future) a date: Current, 1–30, … |
SQL (day bands against today) |
concentration |
Top-k shares, HHI (0–10 000), effective N (1/Σs²), a ranked table with cumulative share | SQL groups + TypeScript |
matrix |
A heatmap of weekday / hour (UTC) / month / a group × another. Counts and sums fill every cell (zeros included); an average omits cells with no values |
SQL |
histogram |
Records by value band; money bands are major units per currency | SQL, one query per currency |
composition |
Signed components and a net (waterfall), per currency | SQL per component |
dso / dpo |
Open balance ÷ sales in the trailing windowDays × windowDays, per currency |
SQL per part |
ccc |
Cash conversion cycle without inventory: DSO − DPO per currency over one window; null for a currency with only one side | SQL per part |
table |
System metrics only | — |
Each kind has default charts (definition.ts defaultCharts): value →
number, table (a money value also bar: one per currency); timeseries → line,
area, bar, calendar (counts), table, number, and stacked bar / area only with
a splitBy; breakdown → bar, hbar, donut, pie, rose, treemap, pareto,
funnel (with an order), radar (≤ 8 groups), table, number; ratio → gauge,
number, line (over time), table; duration → number, histogram, boxplot
(with a group), table; aging → bar, hbar, donut, table; concentration →
gauge, pareto, treemap, hbar, donut, table, number; matrix → heatmap,
table; histogram → histogram, table; composition → waterfall, table;
dso / dpo / ccc → number, gauge, table. Every chart a v1 widget of a
migrated metric could store is still offered (a test pins the pairs).
The store side. Kinds compile to ResourceStore primitives,
parameterised SQL on SQLite and Postgres alike: aggregateV2 (filters,
comparisons, up to three grouping keys — field, unnested array element,
day / week / month / UTC weekday / UTC hour bucket, numeric band, age band —
with count, sum and average), fetchValues (raw values for durations and
percentiles, capped at 50 000 rows; above it a deterministic every-k-th pk
sample chosen before any value is extracted, and a note saying so),
lookupLabels and distinctValues. Paths are validated dotted paths bound
as parameters. Day, week and month buckets use the stored text’s own date (as
the range filter does); weekday and hour are converted to UTC, and a duration
reads an offset-less datetime as UTC too, whatever the host zone.
Impossible dates are NULL, never an error. Postgres casts ISO text only
after a regex admits it: a real calendar day in years 0001–9999 and an offset
of at most ±14:00. SQLite reaches the same verdict with a date() round trip
and a measured offset. So year 0000, 2026-02-30 or +23:59 yield a NULL
weekday / hour / week on both dialects instead of failing the whole metric.
Shaping a result is linear in the rows the store returns (60 000 groups take tens of milliseconds), and only the groups a result shows — top-N plus “Other” — are sent for label lookup.
Currencies
Section titled “Currencies”There is no FX data, so money is never summed, stacked, compared, charted on a shared axis or turned into a share across currencies. Shares, ratios, HHI and DSO are computed within one currency.
- Every money series, total, KPI and table row carries its
currency. A record with none is grouped ascurrency: null(“Unknown currency”) and never merges with a real code. A record with no amount adds no group. - Codes are normalised as they leave the engine (
normaliseCurrencyinkinds.ts): a stored value that trims and upper-cases to three letters is that code (usd,Usd→USD, one group), and anything else — a spelled-out name, markup — is the unknown currency. The?currency=match, the SQL-level filters (duration values, histogram bands, coverage) and/currenciesall use the normalised code, so a raw stored string never reaches the dashboard, which puts codes into HTML. admin-api and the admin UI filter their currency lists to ISO codes again at each hop. currenciesin each result lists every code present in scope and range before the currency filter.?currency=EURkeeps only that currency for money kinds; a count with acurrencyFieldcounts only records in it — and so does every part or component that names one, whatever resource type it reads; other metrics ignore it (currency: nullin the result).- A multi-currency result has no single headline:
valueis null and each currency’s number is a KPI; a moneymatrixneeds one currency and says so innoteotherwise.
Parameters and results
Section titled “Parameters and results”GET /admin/data/metrics/:id takes from / to (days, inclusive; default
the last 30, at most 366), currency (three upper-case letters, else 400 INVALID_QUERY), granularity (auto | day | week | month; auto is the definition’s
default if it has one, else day up to 62 days, week up to 182, month beyond)
and compare=1 (adds previous: the same metric over the prior equal-length
range, for value, timeseries, breakdown, ratio and duration kinds that are
not snapshots).
Two more parameters narrow the connections a metric reads, for a
dashboard’s connection and adapter filter: connection (one connection id,
^[A-Za-z0-9_-]{1,100}$) and platform (an adapter slug,
^[a-z0-9][a-z0-9-]{0,63}$); anything else is 400 INVALID_QUERY, a repeated
parameter included. Both only narrow: they filter the list
connectionsInScope already returned for the scope, so together they mean
AND, and a connection outside the scope (another tenant’s, or one that does
not exist) contributes nothing — the result is empty, never a 404 that would
confirm the id exists. They apply wherever the engine takes its connection
list: the metric’s own records, every ratio part, composition component and
DSO/DPO input, lookup labels (read from the narrowed connections only), the
currencies in the result, and system metrics too, which are per connection
(a filtered sync metric reads jobs per connection, as a restricted scope
does, rather than in one unrestricted pass). A third, vertical
(^[a-z][a-z-]{1,40}$), keeps a connection or platform filter inside one
vertical’s connections: one slug can be an adapter in several verticals
(bexio, bitrix24, dolibarr, …), and system metrics and the currency list read
every vertical, so the dashboards always send it with a filter. Alone it
filters nothing. All three are part of the cache key. The result then carries
filter: { connection, platform, vertical }; with neither connection nor
platform set it has no filter.
The result carries metric (the catalog entry: unit, section, charts,
money, currencyAware, snapshot, granular, comparable,
defaultGranularity), range,
granularity, currency, currencies, value, series, and as the kind
calls for them totals, kpis, table, matrix, stats, previous,
coverage, thresholds and note.
GET /admin/data/currencies returns { data: string[] }: the distinct
currencies across every in-scope money or currency field the catalog reads,
sorted, without null — one UNION ALL + DISTINCT query over all of them.
Same scope rules, and the same connection / platform narrowing; cached
60 s per scope and filter.
Guards
Section titled “Guards”- No PII.
validate.tschecks at boot (and a unit test in CI) every field a definition references — date field, filters, comparisons, currency fields, coverage, measures, groups, split and matrix axes,from/to, aging and histogram fields, every ratio part, composition component and DSO input on the resource type it reads, and each lookup label on the lookup’s type. Each must exist on the schema and be neitherpiinorsecretbyeffectiveFieldClass. It also rejects what the engine could not answer honestly: a money sum without a currency field,unnestwith a sum, stacked charts without asplitBy, unsorted buckets, a ratio of money over counts, agranularityon a kind with no time axis. - Currency rules (design §2), in the validator. Money is only aggregated
where its currency comes with it:
- every
currencyField(metric, measure, histogram, part, component) must be a currency-code field — its Zod type descends fromIso4217Currency, or it is a string whose name ends incurrency/currencyCode(metrics/fields.ts); avgof afinancialfield needs acurrencyField;sum_quantityof afinancialfield is refused (usesumwith itscurrencyField);- a histogram of a
financialfield needs acurrencyField; - a group, split or matrix axis over a
financialfield (bands or raw values) is refused, unless the field is itself a currency code; - in a currency-aware metric, a count (non-money) part or component on
another resource type must name its own
currencyField, so thecurrencyfilter reaches it.
- every
- Scope. A metric aggregates only the connections
connectionsInScopereturns for the caller, and exists only when every resource type it reads is in scope. Alookuplabel (tags.namefortagIds) is read in one batched query from the caller’s own in-scope connections; an id without one falls back to the id, so another tenant’s label can never appear. Aconnection/platformfilter narrows that list and never widens it. - Financial masking. With
data_access.mask_financialon, a metric that reads anyfinancialfield — a measure, filter, comparison, group, histogram field, part or component — returnsmasked: truewith no value, series, totals, KPIs, stats, table, coverage orprevious(also undercompare=1). A verified currency-code field in acurrencyFieldslot is exempt — a count keyed bytotalPrice.currencystays visible — but an amount named there is masked like any amount (and refused by the validator). - Caching. Results are cached for 60 s per (metric, scope, connection and adapter filter, range, currency, granularity, compare, today); operators with different scopes never share an entry, and now-relative filters move with the day.
System metrics: stored records per vertical, sync job outcomes over time
(sync_jobs, any granularity), and data freshness per connection.
Adding a metric: add an entry to its vertical’s catalog/<vertical>.ts,
run pnpm --filter integration-server test -- metrics, and pin its numbers
in tests/data-access/metrics.test.ts. createMetricsEngine({ resourceMetrics }) runs a definition that is not in the catalog yet (it is
validated the same way); valuesCap lowers the raw-value cap to exercise
sampling. A Postgres run of the data-access suite needs
--no-file-parallelism: each file drops public per test.
Follow-ups
Section titled “Follow-ups”Out of scope for the engine today, and the metrics they would unlock:
- FX rates / a base currency — any cross-currency total or share.
- Schema or sync gaps: a payments
Paymentresource; CRM a normalisedoutcome,closed_at,lost_reason, stage history and owner names; supportfirstResponseAt, SLA fields, message sync and a reopen count; logisticsshippedAt, a non-PIIdestinationCountryand exception codes; inventory a demand / movement ledger (DIO, turnover, dead stock) and a stock snapshot store; projectstaskswithcompletedAt; docsignsignersand audit-trail sync; ecommercelineItemsproduct metrics, a channel field and abandoned checkouts. - Engine: joins across resources beyond lookup labels (MRR, inventory value, time to ship), daily snapshots (history of balances and stock), and a permission-gated PII label resolver for customer names in top-N tables.
- Webhook metrics — the delivery store is not wired to the engine.
- Cost of the connection filter.
GET /api/dashboards/connectionslists every connection from integration-server on each call and filters in memory, and a filtered system sync metric reads jobs one connection at a time (up to 500 passes). Both are fine at today’s connection counts; a scoped, paged connection query in the credential store and aconnectionIdsfilter on the sync-job read would remove them.
Dashboards and rendering
Section titled “Dashboards and rendering”Built-in dashboards live in code (apps/admin-api/src/core/dashboards/builtin/):
22 dashboards, in display order:
System health; Accounting, Receivables and payables, Accounting risk; Payments,
Subscriptions and billing, Payments risk; Ecommerce, Ecommerce operations,
Ecommerce risk; CRM, CRM risk; Support, Support risk; Logistics, Logistics risk;
Inventory, Inventory risk; Projects, Projects risk; Document signing, Document
signing risk (ids builtin:overview, builtin:accounting,
builtin:accounting-ar-ap, … builtin:docsign-risk). Each risk dashboard opens
with a strip of number and gauge tiles for its headline risks (concentration,
overdue exposure, DSO and DPO, dispute rate, stuck items) and follows with the
supporting charts. /dashboards groups the cards by vertical.
User dashboards are
rows in admin_store v4’s dashboards table; only the owner or an admin may
edit or delete one.
Widgets. A widget is a metric id, a chart, a width (1–12 of a 12-column grid), an optional title, and three options:
| Option | Values | Applies to |
|---|---|---|
currency |
an ISO 4217 code; absent or null follows the view’s currency filter | metrics marked currencyAware (money, or a count with a currencyField) |
granularity |
auto (or absent), day, week, month |
metrics marked granular (a series over time) |
compare |
boolean | metrics marked comparable: number and gauge show the change against the prior equal-length period; other charts name it under the chart |
layout_json is free-form, so the options needed no migration, and
normaliseWidgets keeps them (a null currency is stored as absent: both mean
“follow the filter”). The UI never sends auto to the engine, so a metric’s
own default granularity applies; an explicit one wins.
Chart validation. The chart vocabulary is CHART_TYPES in
@opensteward/shared (dashboards/charts.ts); admin-api’s DASHBOARD_CHARTS
is that list, so admin-api and the engine cannot disagree on what a chart is.
Create and edit refuse a layout (400) with more than 24 widgets, a metric
outside the caller’s catalog (Unknown metric: …), or a chart that is not one
of its metric’s charts (Chart <chart> does not fit <metric>), checked
against the caller’s own catalog. A stored widget whose chart its metric no
longer lists (the catalog changed after it was saved) is drawn with the
metric’s default chart, and the editor resets it to that default, so a save
never fails on a legacy widget.
The 22 chart types, and what each reads from a result:
| Chart | Reads | Fits |
|---|---|---|
number |
the headline (value, or the one currency’s total), previous, thresholds, secondary kpis |
value, timeseries, breakdown, dso / dpo |
gauge |
the headline on a dial with threshold bands | ratio, concentration, dso / dpo |
table |
table, else the series by bucket |
every kind |
line, area, bar |
series over buckets | timeseries, ratio over time |
stacked_area, stacked_bar |
splitBy series, stacked within one currency |
timeseries with a splitBy |
hbar |
one series of categories | breakdown, aging, concentration |
combo |
bars and lines per each series’ kind, one axis |
series sharing a unit |
pareto |
each group’s share (bars) and the cumulative share (line) on one 0–100 % axis; a concentration’s table supplies both | breakdown, concentration |
pie, donut, rose |
one series of parts; past six, the rest fold into Other | breakdown, aging |
treemap |
one series of parts, in one hue | breakdown, concentration |
funnel |
ordered stages, on the sequential ramp | breakdown whose group has an order |
radar |
one series over at most 8 groups, one scale | breakdown |
histogram |
the band series | histogram, duration |
boxplot |
stats: All first, then one box per group |
duration with a group |
waterfall |
a composition series: components float on the running total, Net (last) stands on zero |
composition |
heatmap |
matrix cells on the sequential ramp |
matrix |
calendar |
a day series as a calendar grid (the widget always asks for day) |
count timeseries |
Currencies in the UI. The view page has a currency select beside the
range: “All currencies (each separately)” plus the codes from GET /api/dashboards/currencies?dashboard=<id> (which proxies
/admin/data/currencies with the caller’s scope narrowed to the dashboard’s
pins). It is the GET parameter currency, carried by the range presets. An
unknown code falls back to every currency; when the list cannot be loaded the
page says so and keeps a well-formed code rather than silently widening the
view. Each widget’s request carries, in order of precedence, its own pinned
currency, else the view’s filter, else none. The edit form offers, per
widget, only the options its metric takes (a currency select “Follow
dashboard filter” / “Only EUR”, a granularity select, a compare checkbox) and
groups the metric picker by vertical, then section (“Accounting ·
Receivables”).
Small multiples. With no currency chosen, a money result may hold several
currencies. dashboard.js then splits it (splitByCurrency) into one part
per currency, with its own series, totals, KPIs, table rows and prior totals,
and its own headline (the ratio, days outstanding, top-1 share or banded
records of that currency). Each part is drawn as a mini chart, number tile or
table section titled with its code, alphabetically, with “Unknown currency”
last. Every part has its own axis: nothing is stacked, shared, summed or
turned into a share across currencies, and a pie, donut, treemap or funnel of
money over several currencies becomes one per currency. A money heatmap is
the one result the engine will not split (one currency per matrix), so the
renderer fetches it once per currency. At most eight parts are drawn; the
footnote names the rest. Counts are not split: a count with a currencyField
adds up across currencies, and the filter narrows it.
Audiences. A user dashboard is private (only the owner), shared with
tenants (anyone whose access includes any listed tenant; an unrestricted
scope matches every list) or shared with everyone (every dashboards:view
holder; setting it needs dashboards:share_all). The owner always sees their
own, and an admin with access to every tenant sees all. The rule lives in one
module, core/dashboards/audience.ts. A caller outside the audience gets
404, never 403, on list, get, edit and metric reads. A restricted editor
may share with, and pin, only tenants in their own access. Tenant ids outside
a non-editor’s access are removed from the audience and pinnedTenants the
API returns. Migration v6 turns an existing shared dashboard into
everyone when its owner is unrestricted, and into the owner’s tenants when
the owner is restricted (none: private), so an upgrade never widens who sees
one. A change to the audience or pins is audited as dashboard.share.
Connection and adapter filter. A dashboard about one vertical — a
built-in, which carries its vertical, or a user dashboard whose non-system
widgets’ metrics all share one — has a filter bar under the range and
currency row, for viewers who hold connections:read as well as
dashboards:view; elsewhere (the system overview, a mixed dashboard) and
without that permission the bar is absent and connection / platform in
the URL are ignored.
| Layer | What it does |
|---|---|
admin-api GET /api/dashboards/connections |
?vertical&platform&search&dashboard&limit, guarded by both dashboards:view and connections:read. Lists the caller’s in-scope connections (tenantAllowed, intersected with a stored dashboard’s pins via narrowAccessScope; 404 for a dashboard the caller cannot see) as { connections: [{ id, label, platform, vertical }], platforms: [{ slug, name, count }], total }. Scope is applied before any filter or count. search is a case-insensitive substring of the id or label (an exact id sorts first); limit defaults to 50, at most 200; platforms counts the vertical’s visible connections per adapter, ignoring search and platform, named from the platform catalog (cached 10 min; the slug when it is unavailable). Never a tenant id, status or credential. |
| admin-api metric and currency routes | Take connection, platform and vertical with the engine’s patterns and forward them only when set; the dashboard pins narrow the scope header first, the engine narrows further. The routes guard dashboards:view, and a request carrying connection or platform also needs connections:read (403 otherwise), so the filter is never reachable with dashboards:view alone. |
Admin UI /dashboards/:id |
An Adapter select (“All adapters” plus each adapter with its count) and a Connection text box with a <datalist> of up to 200 connections, each option’s value the id and its text label · adapter · id, so typing a label or an id fragment narrows the browser’s own suggestions with no script. |
Resolving what was typed (server side, on submit): an exact in-scope id
applies; anything else is a search over ids and labels (within the chosen
adapter) — exactly one match applies that connection, several render a short
Did you mean list of links that set connection=<id>, and none renders a
message and applies nothing. Only the resolved id is carried onward: in the
range presets, the range and currency form (hidden fields), the filter form
(which carries the range and currency back), each widget’s
data-connection / data-platform / data-vertical (the dashboard’s
vertical, sent with any applied filter), dashboard.js‘s metric URL and the
same-origin /dashboards/metric/:id route, which drops all three for a user
without connections:read. A chip shows the applied
connection as label · adapter with a link that clears it, and the currency
select lists the filtered connections’ currencies. An adapter the list does
not offer falls back to every adapter; when admin-api cannot list
connections at all, a well-formed adapter and id are kept as given (no data
rather than silently every connection’s) and the page says so.
System widgets are filtered too. The engine narrows system metrics by the same connection list, so on a vertical dashboard that holds system widgets the filter applies to every widget, and the bar says “Applies to every chart on this dashboard, system charts included.”
When more connections match than the 200 listed, dashboard.js refreshes
the datalist as the user types (debounced, from the same-origin
GET /dashboards/:id/connections, which needs connections:read and works
out the vertical from the dashboard as the view does, ignoring one in the
query; 404 for a dashboard with no single vertical); without script the
first 200 and the server-side search still work.
Pinning. A dashboard may be pinned to tenants. The page passes
?dashboard=<id> to /api/dashboards/metrics/:id, and admin-api narrows the
X-OpenSteward-Data-Scope header to the viewer’s scope ∩ the pins (for an
unrestricted viewer, exactly the pins, which also drops connections with no
owner tenant). Pins only narrow: they are a presentation choice, not a
security boundary, because the viewer’s own scope stays the limit. A pinned
dashboard is hidden from a restricted viewer who holds none of its pins.
Rendering. public/js/dashboard.js (plain ES5, same origin, under the
strict CSP) draws with ECharts, vendored at /vendor/echarts.min.js, in the
design system’s colours. Series take --chart-1…6 in fixed order (a
categorical order validated for colour-vision deficiency, with separate
dark-theme steps; a count’s seventh series folds into Other). Magnitudes
(heatmap, calendar, funnel) take the one-hue sequential ramp
--chart-seq-1…5, whose dark steps flip so the least sits nearest the
surface. Threshold levels take the status tokens, always with a label. There
is never a second value axis. coverage (“based on N of M records”) and
note render as a muted footnote, and a masked result says its values are
withheld. Charts resize with their container (ResizeObserver) and redraw
when the theme changes. Tooltip labels are HTML-escaped, because group labels
are synced third-party data. The pure helpers (the currency split, headlines,
pareto, waterfall and calendar data, the fetch URL) are pinned without a DOM
in apps/admin/tests/unit/dashboard-charts.test.ts.
Embedded Superset (optional, Postgres only)
Section titled “Embedded Superset (optional, Postgres only)”Deployments on the Postgres backend can add Apache Superset for dashboards the native catalog cannot express. Setup and the full security model are in deployment/superset.md; this is how it fits the hops above.
- No Superset login for operators. The page
/dashboards/superset/:idframes Superset’s/embedded/<uuid>through the vendored@superset-ui/embedded-sdk. The SDK asks the admin UI for a guest token (POST /dashboards/superset/:id/guest-token, CSRF-protected), which proxies admin-api’sPOST /api/analytics/superset/guest-tokenwith the session. - Scope travels as row-level security. admin-api builds the token’s RLS
clause from the operator’s scope, narrowed to the dashboard’s pinned tenants
when it has any (
core/analytics/superset-rls.ts,core/dashboards/audience.ts): none for an unrestricted operator on an unpinned dashboard;owner_tenant_id IN (…)plus(owner_tenant_id = … AND vertical IN (…))for tenants granted only some verticals; no token at all (403SCOPE_EMPTY) for an empty scope. Tenant ids and verticals are validated against strict patterns and quoted; a value that cannot be expressed safely is dropped, which only narrows the result. - Only masked data. Superset connects as a read-only SQL principal onto
the
os_analyticsviews, so personal data is masked there exactly as in SQL access, and Postgres enforces the principal’s own scope underneath. Every dataset hasowner_tenant_idandvertical, the columns the RLS clause filters. - Guests cannot write SQL. The guest role (
OpenStewardGuest) holds no SQL Lab or dataset permission; guests reach data only through the charts on the dashboard their token names. - Tokens are short. Guest tokens last 5 minutes and are minted per page
view; the SDK refreshes them. Each mint is audited as
superset.guest_token, at most once per user and dashboard every 10 minutes.
The registry of embeddable dashboards (superset_dashboards, admin_store v5)
is written by the idempotent superset-bootstrap job through
PUT /api/internal/superset/dashboards (service secret). It registers every
Superset dashboard whose slug starts with opensteward-; opensteward-<vertical>-…
lists it only for operators whose scope reaches that vertical.
Each registry entry also carries an audience (tenants or everyone, the
default) and optional pinned tenants, chosen in the admin UI by a
dashboards:share_all holder and never written by the bootstrap job, so a
re-sync keeps them. The same rule as native dashboards filters the list and
the guest-token route (404 outside the audience). Superset authors, who
sign in to Superset directly, still see every tenant’s masked data; that is
unchanged.
Content-Security-Policy
Section titled “Content-Security-Policy”The data and dashboard pages are served with a strict per-route policy
(apps/admin/src/core/csp.ts):
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';img-src 'self' data:; frame-ancestors 'none'; font-src 'self' data:No inline script and no inline event handler runs on these pages. The layout’s
shell behaviour (theme, sidebar, toasts, copy, version footer, data-confirm)
lives in public/js/theme-init.js and public/js/shell.js for that reason.
When Company info configures an external font stylesheet, its origin is added
to style-src and https: to font-src.
The embedded Superset page adds frame-src <Superset origin> (the origin of
SUPERSET_PUBLIC_URL, validated as http(s)); no other page frames anything.
Superset’s own CSP allows only the admin UI origin in frame-ancestors.
| Action | Written by | Detail |
|---|---|---|
data.pii_reveal |
admin-api, before the unmasked record is returned (a failed write fails the request) | {connectionId, resourceType, resourceId, reason}; vertical and target_id columns set |
data.export |
admin-api, once the upstream export has started | {connectionId, resourceType, format, includePii} |
dashboard.create / .update / .delete |
admin-api | {name} |
dashboard.share |
admin-api, when a dashboard’s audience or pinned tenants change (also on create) | {name, from, to, pinnedFrom, pinnedTo}, audiences as {kind, tenants?} |
superset.guest_token |
admin-api, after Superset issued the token; at most once per user and dashboard every 10 minutes | {title, restricted}; target_id is the registry id |
superset.share |
admin-api, when a Superset dashboard’s audience or pinned tenants change | {title, from, to, pinnedFrom, pinnedTo} |
superset.registry_sync |
admin-api, as system, when the bootstrap job registers dashboards |
{created, updated, removed} |
See also
Section titled “See also”- permissions-and-roles.md — what each permission unlocks
- ../security/data-classification.md — classes and masks
- persistence.md — the
resourcestable,changed_at, tombstones - admin-page-map.md — every admin route
- ../deployment/superset.md — embedded Superset setup and security model
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.