Documentation by ClonePartner

Start typing to search.

Job & Dashboard Reference

Widgets overview

View Markdown

Browse all 14 dashboard widget types, the keys every widget shares, and how widgets bind to connector data and shared queries.

Widgets overview

A widget is one block on a dashboard page: a heading, a number, a chart, a data browser, an editable form, or an action button. Every widget is declared in dashboard YAML with a type from the built-in registry (src/dashboard/register-widget-types.ts); the parser dispatches each entry to its type-specific handler. Data widgets execute read-only connector calls server-side through the Job's connector mapping — the browser never holds connector credentials.

The 14 registered types match the DashboardWidgetType union in the UI API client:

Type Purpose
heading Section label or instructional callout.
stat Single numeric result with optional unit and comparison.
progress Current/total ratio bar.
steps Horizontal process stepper.
people Contact cards.
bar_chart Bar chart over an array of records.
line_chart Line chart over an array of records.
pie_chart Pie chart over an array of records.
table Bounded rows with declared columns.
form Typed fields that write a job_config object.
field_mapping Source-to-target mapping editor that writes a job_config array.
action Declarative button that runs a task, job run, or connector method server-side.
task_progress Latest run status for one job task key.
explorer Curated pageable, filterable data browser.

The registry groups behavior three ways: form and field_mapping are input widgets (they persist a value onto the Job's configuration), action is the action widget, and everything else is read-only display.

Common keys

Every widget accepts these base keys in addition to its type-specific configuration:

Key Type Required Description
id string Yes Stable identity, unique across the whole dashboard. Used for data fetches, refresh targets, and row_action references.
type string Yes One of the 14 registered types.
title string No Display title.
description string No Display description.
width number No Relative span in the responsive grid.
scope string or null No Named scope profile to inject into this widget's connector calls, or null to opt out. Omit to use the dashboard's default_scope.
refresh_interval_seconds number No Per-widget polling interval, overriding the dashboard-level value.

Data binding

Data widgets name a connector call in their data (or current/total/compare_to) key:

- id: tickets_total
  type: stat
  title: Tickets
  data:
    connector: mongo
    method: count
    args:
      collection: zendesk_tickets
  • The call shape is { connector, method, args? }. connector is a template connector name resolved through the Job's connector mapping; method must be a read-only method — writes are rejected at widget execution time.
  • Leaf values and whole data blocks may be JSONata strings, evaluated with the dashboard context: arguments, job, job_config, and shared.
  • Widgets that support shared_query reuse a named entry from the dashboard's shared_queries instead of calling the connector directly; the cached result is bound as data in the widget's expressions. Prefer shared queries when several widgets need the same expensive call.

Public share behavior

On the public share surface each widget is sanitized by its registry handler: connector call configs, option sources, and action dispatch internals are stripped, and only display-safe keys (titles, columns, form field labels, and similar) reach the anonymous viewer. See Dashboard YAML for page-level public flags and allow_public_input.