Dashboard YAML

Dashboards are YAML-defined widget pages bound to Jobs. Definitions are authored on dashboard templates attached to a Job Template and snapshotted onto each Job's dashboards rows at job creation, with ${VAR} substitution from the job's arguments. parseDashboardYaml in src/dashboard-parser.ts enforces this schema; the document may start with a top-level dashboard: key or be a bare dashboard object.

This page covers the document structure. Widget configuration lives in the Widgets overview and its group pages; the authoring guide is Authoring dashboards.

Top-level keys

pages

Prefer pages[] for multi-section dashboards. Each page:

dashboard:
  title: Ops console
  refresh_interval_seconds: 60
  pages:
    - id: overview
      title: Overview
      widgets:
        - id: intro
          type: heading
          title: Status
    - id: data
      title: Data
      public: false
      widgets:
        - id: tickets
          type: explorer
          data:
            connector: mongo
            resource: tickets

Widget ids must be unique across the whole document, not just within a page. A document cannot declare both pages and top-level widgets.

Widget types

Fourteen widget types are registered. Their per-type configuration is documented on three group pages:

Keys shared by every widget (id, title, width, scope, refresh_interval_seconds, and data binding) are documented once on the Widgets overview.

scope and default_scope

Scope profiles inject read-only filters into widget connector calls, so one dashboard definition can serve different data slices:

dashboard:
  default_scope: source
  scope:
    source: |
      {
        "mongo": {
          "job_id": arguments.job_id
        }
      }

• A widget without a scope key uses default_scope.
• scope: <name> on a widget selects a specific profile; scope: null opts the widget out of injection.
• default_scope must name a defined profile; otherwise parsing fails with default_scope "<name>" is not defined in scope.

Scope is merged into read-only connector calls (Mongo filter, aggregate $match prefix, Truto top-level args). SQLite select does not auto-inject scope because raw SQL is opaque.

shared_queries

Named read-only connector calls resolved once per refresh and cached. Widgets reference an entry with shared_query: <name> and derive their value with a JSONata expression; the shared result is bound as data in the widget's expression context.

dashboard:
  shared_queries:
    tickets_facet:
      connector: mongo
      method: aggregate
      args:
        collection: zendesk_tickets
        pipeline:
          - "$facet":
              total: [{ "$count": "count" }]
              migrated:
                - { "$match": { "status": "migrated" } }
                - { "$count": "count" }
  widgets:
    - id: tickets_total
      type: stat
      shared_query: tickets_facet
      value_expr: "$exists(data[0].total[0]) ? data[0].total[0].count : 0"

navbar_ctas

Optional action group rendered in the public dashboard header:

navbar_ctas:
  - label: Support
    variant: button
    icon: mail
    href: mailto:[email protected]
    text: [email protected]

Attachment and sharing model

• Dashboard templates belong to a Job Template; Dashboards belong to a Job. Creating a Job snapshots each active dashboard template onto a dashboards row.
• A per-dashboard share token (POST /api/dashboards/:id/share) exposes a public read-only view. The public payload is sanitized: connector call configs, shared_queries, scope, and action dispatch internals are stripped; pages with public: false and actions without allow_public: true are omitted.
• allow_public_input: true allows input widgets to be edited through the share link, and only when the server-side kill switch ENVOY_PUBLIC_DASHBOARD_INPUT_ENABLED is also enabled.

Validation errors

Related

• Widgets overview — the 14 widget types and shared widget keys
• Authoring dashboards — design, testing, and public-share guidance
• job_config schema — the values input widgets read and write