Skip to main content

Analytics

Analytics dashboards are embedded directly in the Energyworx platform UI so business users can explore their data without leaving Energyworx. They are built in the Analytics dashboard builder (Apache Superset), which Energyworx hosts for your environment. This page explains how to register an Analytics dashboard so it appears in the UI, and how access is controlled.

Analytics dashboards can be registered in two places. A namespace-level dashboard appears in the Analytics menu and covers the whole namespace, configured through a Dashboard configuration (type Superset). A dashboard registered on a datasource classifier instead opens on every datasource of that classifier and scopes itself to the datasource you opened.

Prerequisites​

  • Analytics must be enabled for your environment. This is an environment-level setting configured by Energyworx during deployment — if the Analytics menu is missing, contact Energyworx support to have it enabled.
  • You build the dashboard itself in the builder (https://superset.<env>.energyworx.net); Energyworx only stores a reference to it (the dashboard's embedded UUID) plus access rules.

Getting a dashboard's embedded UUID​

Energyworx references a dashboard by its embedded UUID, which is created when you turn on embedding in the builder — it is not the UUID shown in the dashboard's normal URL.

  1. Open the dashboard in the builder.
  2. Open the ⋯ (three-dot) menu → Embed dashboard.
  3. Add the Energyworx UI origin (https://<env>.energyworx.net) as an allowed domain.
  4. Copy the UUID shown in that dialog. This is the value Energyworx needs.

If you skip this step, registration will look fine but the embed will fail to load — Energyworx can only render dashboards that have embedding enabled.

Registering a dashboard (Analytics menu)​

Namespace-level dashboards apply to the whole namespace and appear in the Analytics menu.

  1. Go to Analytics in the main menu and choose Create (requires the create dashboard permission).
  2. Set the type to Superset and paste the embedded UUID.
  3. Save. The dashboard now appears in the Analytics menu for users with the read dashboard permission.

Dashboards on a datasource classifier​

A dashboard registered on a datasource classifier opens on every datasource of that classifier, next to its charts and data — you do not build or register one dashboard per datasource.

  1. Open the datasource classifier and find its Superset Dashboards section.
  2. Add a dashboard with its Embed UUID (the same embedded UUID as above — not the UUID in the dashboard's normal URL).
  3. Optionally give it a display name, which is what users see on the datasource.

Scoping charts to the opened datasource​

One dashboard serves every datasource of the classifier, so its charts have to narrow themselves to whichever datasource was opened. Energyworx passes the datasource through as the datasource_id URL parameter; filter the dashboard's SQL dataset on it in the builder:

SELECT *
FROM `<project>.<namespace>.timeseries`
WHERE datasource_id = '{{ url_param('datasource_id') }}'

Without that filter the charts return the namespace's rows for every datasource, which is usually not what you want on a datasource page.

A row-level security (RLS) clause can be set per dashboard as an alternative way to constrain what it returns. It is optional; the datasource_id filter above is the usual approach.

Moving them between namespaces​

ewx-cli config upload carries a classifier's dashboards with the rest of its configuration, and config download includes them, so they round-trip. See ewx-cli for the configuration block and an important caveat: an upload replaces the classifier's complete dashboard set, so re-uploading an older configuration can remove dashboards attached since through the console.

Access & isolation​

  • Who can see embedded dashboards. Viewing requires the relevant permission (read dashboard). Building or editing dashboard configurations requires the create/update dashboard permission.

  • How tenant isolation works. Energyworx mints a short-lived, per-namespace guest token for every embed. Two things keep that embed inside one namespace:

    • Resource restriction. The token is minted for one specific dashboard UUID. A user can only load the dashboards registered for their namespace; the token will not render any other dashboard.
    • Per-namespace datasets. A dashboard's charts query that namespace's own BigQuery dataset (FROM <project>.<namespace>.…), so they can only return that namespace's rows.

    Because isolation comes from the dataset a dashboard is built on, always build a namespace's dashboards against that namespace's own datasets — never register a dashboard whose datasets read another namespace's tables.

  • Dashboard authors. Users who open the builder to build dashboards (interactive login, not an embed) are provisioned a Dashboard Builder role scoped to their own namespace on first sign-in. This governs what authors see in the builder itself; it is separate from the guest-token embed path above.

Tenant onboarding (new namespace)​

When a new namespace is created, the builder side requires no manual dashboard wiring:

  • The environment already has a shared BigQuery database connection in the builder, so datasets can query the namespace's tables.
  • A user's builder role is created automatically the first time someone from that namespace opens the builder to build dashboards. (Embeds isolate via the per-namespace dataset and the dashboard-scoped guest token, as described in Access & isolation.)

To make dashboards appear for the new namespace, register them as described above. See also How to bootstrap a namespace.