Dashboards and public dashboards

Envoy dashboards are declarative, job-bound applications. They can present status and data to internal operators or through a tokenized public share link.

Dashboard templates and instances

A dashboard template belongs to a job template. When a job is created, the dashboard YAML is snapshotted into a dashboard bound to that job.

This follows the same blueprint/instance model as jobs:

• edit a dashboard template to affect future job instances;
• edit a job's dashboard for an instance-specific change;
• do not assume template edits rewrite existing dashboards.

Dashboard capabilities

Dashboard YAML can define multiple pages and include:

• headings and instructional callouts;
• numeric stats and progress;
• bar, line, and pie charts;
• tables;
• migration steps and contact people;
• task progress;
• curated Data Explorer widgets;
• forms and field mappings backed by job configuration;
• controlled task, job, and connector actions.

For the exact schema, use Dashboards reference. For a production workflow, see Author an operational dashboard.

Create a dashboard

From a job:

1. select Add dashboard;
2. choose an available dashboard template or create the intended instance;
3. review the bound connectors and job configuration;
4. open the dashboard;
5. edit instance YAML only when the job needs to diverge.

Test every page as an authenticated operator before sharing it.

Read-only data safety

Data widgets execute connector methods on the server in read-only mode. Authors choose the connector, resource, base query, scope, and displayed columns.

An Explorer widget's viewer filters are combined with the author's base query; viewers cannot remove the base restriction. Declared columns also act as an allowlist for viewer filters and projections.

For large data, enable only indexed sort fields and use server-streamed export.

Public share links

A public dashboard is addressed by an unguessable share token and does not require a user session. Treat the URL as a bearer credential:

• send it only through approved channels;
• revoke or rotate it when exposure changes;
• do not include secrets in titles, text, or returned rows.

The public API receives a sanitized dashboard definition. Connector call configuration, shared-query internals, scope internals, and private action dispatch details are not returned.

Three public controls

Public behavior is deliberately split:

Control	Effect
ENVOY_PUBLIC_DASHBOARDS_ENABLED	Allows public share-link viewing
ENVOY_PUBLIC_DASHBOARD_INPUT_ENABLED	Allows eligible public form and field-mapping updates
ENVOY_PUBLIC_DASHBOARD_ACTIONS_ENABLED	Allows eligible public action widgets

Inputs additionally require dashboard.allow_public_input: true.

Actions additionally require:

• allow_public: true on the action;
• placement on a public page;
• the server action switch enabled.

Keep input and action switches off unless the use case has been reviewed.

Page visibility

Set public: false on a page to exclude it from share links. Public action widgets on an excluded page are not exposed.

Use this to keep operator diagnostics and remediation tools inside authenticated pages while sharing status or mapping pages.

Forms and field mappings

Input widgets read and write the job's job_config. They are appropriate for:

• field mappings;
• stage or status selections;
• batching and notification options;
• customer-facing choices that tasks read on the next run.

The run snapshots current job configuration, so later edits do not rewrite the configuration recorded for an earlier run.

Actions

Action widgets can:

• run one task;
• run the job;
• call an approved connector method.

Every action displays confirmation. Public actions have additional server gates, per-widget deduplication, optional cooldown, and audit rows.

Avoid broad connector methods or client-controlled raw arguments in a public action. The server should derive sensitive action configuration from stored YAML.

Review checklist

Before sharing:

1. inspect the public version in a private browser session;
2. confirm private pages are absent;
3. verify every table and export is scoped;
4. confirm inputs and actions match server switches;
5. test cooldown and confirmation copy;
6. verify no connector credentials or internal identifiers render;
7. decide how the token will be revoked.