Documentation / Reporting & Data

Dashboards

Compose Nexus reports into shareable, live dashboards that read straight from your connected systems inside your own Azure tenant — no data warehouse, no nightly copy, no stale snapshots.

A Nexus dashboard is a hosted page that lays out one or more reports and renders them live against your connected systems. Each panel runs its report at view time, so the numbers are current the moment the page loads. This page is for analysts and admins who want to turn Nexus reports into something a team can open and read, and for the security reviewer who needs to know exactly what a dashboard can and cannot touch.

What a dashboard is

A dashboard is a Site — a small set of static assets (HTML, CSS, JavaScript) that Nexus hosts at a clean URL inside your tenant. The page itself holds no data and no credentials. It calls the Nexus API as the person viewing it, runs the reports that person is allowed to run, and draws the results. Because every panel reads through your existing reports and bridges, there is no separate warehouse to fill and nothing to keep in sync.

Property	How a Nexus dashboard works
Data freshness	Live — each panel executes its report on load
Storage	None of its own; reads from your connected systems
Credentials	None in the page; the request is authenticated per viewer
Permissions	Bounded by the viewer's RBAC, enforced server-side on every call
Hosting	Inside your Azure tenant at `/sites/{slug}/`
Authoring	Edit assets; reports are reusable across pages

How it fits together

Dashboard page  ──runReport()──►  Nexus reports engine  ──►  your bridges
   (static assets,                   (RBAC-checked,            (SQL Server, Postgres,
    no credentials)                   pushdown where able)      NetSuite, Monday, ...)

The page never receives a long-lived token or a bridge credential. In the desktop app it renders in a locked-down window and the request is brokered for the signed-in user; in a browser it signs the user in and keeps the access token in memory only. Either way a viewer sees exactly the data their role permits and nothing more — the enforcement is on the server, for every call, not in the page.

Building one

Author the reports the dashboard needs. Each report is a JSON definition with one or more queries, optional joins, group-by aggregation, and parameters. See Reports.
Create a site and add a page that loads the first-party SDK, then calls runReport for each panel and renders the rows. See Building sites.
Publish. The dashboard is live at /sites/{slug}/ for anyone with access.

The SDK handles authentication and routing for you. A minimal panel looks like this:

<!-- index.html -->
<div id="sales"></div>
<script src="/sites/_sdk/nexus-client.js"></script>
<script src="/sites/app.js"></script>

// app.js
const nexus = await Nexus.connect();             // auth handled internally

const rows = await nexus.runReport('sales-by-region', { min_amount: 1000 });

const el = document.getElementById('sales');
el.innerHTML = rows
  .map(r => `<tr><td>${r.region}</td><td>${r.total_sales}</td></tr>`)
  .join('');

runReport(reportId, params) returns the shaped rows from the report — the same result the report would produce anywhere else in Nexus. Pass report parameters as the second argument to drive filters, date ranges, or thresholds from the dashboard. Because the call is just a report execution, everything the report guarantees — pushdown to the source where the adapter supports it, in-engine aggregation where it doesn't, and RBAC on every read — applies unchanged.

Composing multiple reports

A real dashboard is several panels, each its own report, laid out on one page. Because reports are independent and reusable, you compose freely: a KPI strip from one report, a regional breakdown from another, a trend table from a third. Fetch them in parallel and render as each resolves.

const nexus = await Nexus.connect();

const [kpis, byRegion, trend] = await Promise.all([
  nexus.runReport('company-kpis'),
  nexus.runReport('sales-by-region', { region: '*' }),
  nexus.runReport('sales-trend', { months: 12 }),
]);

drawKpis(kpis);
drawTable(byRegion);
drawChart(trend);

Each report carries its own permission surface, so a viewer who can see the KPI report but not the regional one simply gets an error on that panel and the rest of the page still renders — the dashboard degrades to what the viewer is allowed to see rather than failing whole.

Refresh: live-on-load, plus polling and interaction

Panels are live at load time. For a wall-mounted board or an operations view, add a refresh loop; for an interactive view, re-run a report when a control changes.

// Periodic refresh (e.g. an ops board)
async function refresh() {
  const rows = await nexus.runReport('open-incidents');
  draw(rows);
}
setInterval(refresh, 60_000);   // re-read every minute

// Interactive drill-down
async function onRegionChange(region) {
  const rows = await nexus.runReport('sales-by-region', { region });
  draw(rows);
}

Report parameters with a default of "*" act as optional filters — leave them unset to show everything, or pass a value to narrow the view. This lets one report serve both a company-wide panel and a filtered drill-down on the same page, with no backend code. There is no push/streaming channel: freshness comes from re-running the report, so choose a poll interval that suits the source system's cost and the number the panel shows.

Embedding via Sites

Because a dashboard is a Site, it inherits the Sites security and hosting model rather than being a bolt-on:

Same-tenant hosting. The page is served from /sites/{slug}/ inside your own Azure subscription. Dashboard data never transits a Stingray-hosted plane.
Per-viewer identity. Every runReport call is authenticated as the viewer and RBAC-checked server-side. A page cannot exceed the viewer's permissions, and it holds no standing credential to steal.
Strict content security policy. Sites set a strict CSP, which constrains what the page can load and where it can send data — a meaningful control when the page renders business figures.
Versioned assets. Site assets are version-controlled like the rest of your Nexus content, so a dashboard change is a reviewable, revertible commit.

For the full hosting model, authoring flow, and the page-level security details, see Sites and Building sites.

Why live beats a warehouse copy

Traditional BI dashboards read from a warehouse that someone has to load on a schedule, so the figures lag and the copy is one more place data can leak. Nexus dashboards read the source systems directly at view time:

No nightly ETL job to build or babysit.
No stale snapshot — what you see is what the system holds now.
No second copy of sensitive data to secure or to reason about in an audit.
One report definition powers a dashboard panel, an export, a sync, and an ad-hoc query.

Where the underlying adapter supports it, the reports engine pushes filtering and aggregation down to the source database, so panels stay fast even over large tables. Where a source is slow or rate-limited — a REST API with no pushdown, for instance — the better pattern is to land the data into the internal workspace on a schedule and point the dashboard's report at the workspace. That keeps the page live-on-load while offloading the expensive read to an overnight data sync.

Access and governance

Dashboards inherit the Nexus permission model. A viewer only ever loads reports and bridges their role allows, enforced on the server for every call the page makes — there is no way for a page to exceed the viewer's permissions. Sites are created and published by users with the site-management permission, and everything runs inside your own Azure subscription, so dashboard data never leaves your tenant boundary. Every panel load is a report execution and is captured in the audit log like any other read.

Limits & guarantees

Freshness is pull, not push. Panels are current on load and on each re-run; there is no live-streaming channel. Use polling for continuously-updating boards.
A panel is only as fast as its report. Over a pushdown-capable source, panels stay fast; over a no-pushdown API, prefer the workspace-serving pattern.
Per-viewer RBAC, always server-side. The page cannot see or do more than the viewer's role permits; a forbidden panel errors without breaking the rest of the page.
No credentials in the page. The dashboard holds no bridge secret and no durable token.