Documentation / Integrations

Excel Add-in

An Office.js task-pane add-in that queries governed Nexus data from spreadsheet cells with =STINGRAY.QUERY(), =STINGRAY.REPORT(), and =STINGRAY.DISCOVER() — routed through the desktop Connected Apps proxy so Excel never holds a credential and every request runs under the user's own RBAC.

This page is for finance, FP&A, and operations teams who live in Excel and for the platform engineers who have to sign off on letting a spreadsheet touch production systems. It covers what the add-in is, how it connects without ever holding a credential, the exact custom functions and their signatures, and the governance boundary that makes it safe to deploy.

The Excel Add-in is an Office.js task-pane app (React + TypeScript) that lets analysts pull live, governed data through Nexus without leaving their workbook. It is also a deliberate proof point: an external team built it in about two hours on top of the platform, because the hard parts — identity, data access, schema discovery, and governance — are already provided by Nexus. If you want that build story, see An Excel Add-in Built in Two Hours. This page is the reference for the shipped add-in itself.

What it is, precisely

The add-in runs inside Excel as two cooperating surfaces:

A task pane — the side panel with tabs for bridges, a visual query builder, a schema browser, saved reports, pipelines, data sync, and an AI chat.
A custom-functions runtime — a separate Office.js runtime that registers the STINGRAY.* worksheet functions so a cell can recalculate against live data.

Both surfaces talk to the same place: a local proxy inside the Nexus Desktop app, never directly to a Nexus server or a database. That single fact is what makes the security story clean, and it is worth understanding before anything else.

How it connects — no credentials in Excel

The add-in holds no platform credentials, no tokens, and no connection strings. It reaches Nexus exclusively through the desktop app's Connected Apps proxy, a loopback HTTPS listener on 127.0.0.1:8443 running on the user's own machine.

The flow is a one-time pairing followed by signed local requests:

The first time you open the panel it displays a short pairing code.
You approve that code once, in the Nexus Desktop app, while signed in as yourself.
From then on every request from Excel is HMAC-signed and sent to the loopback proxy. The desktop app attaches your identity and forwards the request to your tenant's Nexus server; the response comes back the same way.

The consequences are the point:

Excel never sees a bearer token, a secret, or a database connection string.
Every query executes as you — the same Microsoft Entra identity and the same role-based permissions you have everywhere else in Nexus.
Traffic flows over loopback on your own device to the desktop app, then out from the desktop app to your tenant. There is no third-party relay and no Stingray-hosted data plane.
Revocation is centralized: change a user's role or unpair the app and Excel's access changes with it. There is nothing separate to provision or de-provision in the spreadsheet.

If the desktop proxy is unavailable, the add-in can fall back to a direct Microsoft Entra sign-in (MSAL) against the tenant server; the paired-proxy path is the primary and recommended mode because it keeps the token entirely out of the browser sandbox and inside the OS-native desktop app.

For the identity model this inherits from, see Identity; for what a bridge connection is, see Connections & Bridges.

The custom functions

Three core functions write their results directly into the worksheet. They are registered under the STINGRAY namespace, so you call them as =STINGRAY.QUERY(...), =STINGRAY.REPORT(...), and =STINGRAY.DISCOVER(...). A single aggregated value lands in one cell; a table result spills into a full grid with headers that you can sort, chart, or reference like any other range.

`=STINGRAY.QUERY(...)` — read from a bridge

Runs a governed read against one connected source.

Argument	Required	Meaning
`bridgeName`	yes	The bridge to query (e.g. `"mysql-dev"`, `"monday"`)
`container`	yes	SQL: database/schema. API: board or workspace ID
`collection`	yes	SQL: table. API: object/board
`fields`	no	Comma-separated field list, or empty for all
`where`	no	Filter as a matrix — each row is `[field, operator, value]`; pass a cell range or an inline array
`limit`	no	Max rows (default 100)
`offset`	no	Rows to skip (default 0)
`aggregate`	no	`sum`, `avg`, `count`, `min`, `max`, or `list`
`aggregateColumn`	no	Which column to aggregate (0-indexed)

The where argument is a matrix precisely so you can drive it from the sheet: keep your filter conditions in cells and the query re-runs when they change. A concrete example, pulling open invoices for one region using an inline filter:

=STINGRAY.QUERY("finance", "public", "invoices", "id,customer,amount,status",
  {"region","$eq","West";"status","$eq","open"}, 200)

Or drive the same filter from a range A2:C3 where each row holds a field, an operator, and a value:

=STINGRAY.QUERY("finance", "public", "invoices", "id,customer,amount,status", A2:C3, 200)

The operators ($eq, $gt, $in, $between, $contains, …) are the same UQL operators used everywhere else in Nexus, and whether a given filter is pushed down to the source or applied in-engine depends on the adapter's declared capabilities. See the Operators Reference and UQL Syntax for the full set and the pushdown semantics.

`=STINGRAY.REPORT(...)` — run a saved report

Executes a report your team already defined and governs in Nexus, returning either a single value or a grid.

Argument	Required	Meaning
`reportId`	yes	The saved report's ID
`args…`	no	Repeating `"paramName", value` pairs. Reserved keys: `"aggregation"`, `"headers"` (true/false), `"columns"` (name or comma list)

=STINGRAY.REPORT("monthly-revenue", "since", "2026-06-01", "region", "EU", "headers", TRUE)

Because the report definition lives in Nexus — versioned, RBAC-bounded, and reusable — the spreadsheet only supplies parameters. The heavy logic (cross-system joins, group-by, pushdown) stays on the server where it can be reviewed and audited. See Reports.

`=STINGRAY.DISCOVER(...)` — inspect a source's schema

Returns the collections and fields available on a bridge, so you can build the right QUERY without leaving Excel.

=STINGRAY.DISCOVER("finance")

Working in the task pane

Most people start in the panel rather than typing functions.

Bridges — list the sources wired into your tenant that your role can see.
Schema browser — expand a bridge to see its containers, collections, and columns (backed by discover_schema).
Query builder — pick a source, columns, filters, and a limit, then either write results to the sheet or have the panel generate the matching =STINGRAY.QUERY() formula so the cell refreshes on its own.
Reports — browse and run saved reports, feeding them parameters.
Pipelines — trigger and monitor pipeline runs, including a "Use Selection" flow that hands an Excel range to a pipeline.
AI chat — describe what you need in plain language; the assistant uses Nexus tools to discover schema, run queries, and place data for you. This is the same MCP tool surface an agent would use, so the chat is bounded by the same permissions as everything else.

What this does — and does not — do

Does: put live, governed numbers into a familiar tool; inherit the user's exact RBAC on every call; keep all credentials and secrets in the tenant; give admins one place to revoke access.
Does not: grant any access the user does not already have; hold or cache a long-lived platform credential in the browser; move data through a Stingray-operated service; bypass the audit trail — every read and write from Excel is logged like any other access to the tenant. See Audit & Telemetry.
Depends on: the Nexus Desktop app running and paired on the same machine for the primary (proxy) path.

Why it matters

Spreadsheets stay the workspace your team already knows, but the numbers become live and governed instead of stale CSV exports. And because the add-in is one example of building on Nexus rather than a bespoke feature, the pattern it demonstrates — pair through Connected Apps, query through the platform, inherit governance for free — is exactly the pattern any team in your tenant can reuse for the next custom tool.