# Dashboard schema and widgets

> Source: https://docs.clonepartner.com/reference/dashboards/

Dashboards are YAML-defined views attached to jobs. They execute authored read queries, display run or business data, edit approved job configuration, and dispatch confirmed actions.

## Top-level schema

```yaml
dashboard:
  title: Migration status
  description: Track progress and review errors
  refresh_interval_seconds: 30
  allow_public_input: false
  default_scope: production

  scope:
    production: |
      { "environment": "production" }

  shared_queries: {}

  pages:
    - id: overview
      title: Overview
      public: true
      widgets: []
```

Common fields:

- `title`, `description`;
- `refresh_interval_seconds`;
- `navbar_ctas`;
- `scope` and `default_scope`;
- `shared_queries`;
- `allow_public_input`;
- `pages[]`.

A legacy top-level `widgets` list is normalized as one main page. Widget IDs must be unique across the complete dashboard.

## Page schema

Each page has:

- `id` — stable URL identity;
- `title` — navigation label;
- `widgets` — ordered widget list;
- `public` — set `false` to exclude the page from a share.

## Layout

Widgets use a responsive grid. `width` controls relative span. Keep related controls together, put headings before sections, and verify narrow screens.

## Display widgets

### `heading`

Displays a heading, descriptive Markdown, or callout. Use it for instructions and section structure.

### `stat`

Displays one value and optional label, comparison, or formatting. Feed it a bounded count or aggregate.

### `progress`

Displays current and total values. Define behavior for zero or missing totals.

### Charts

`bar_chart`, `line_chart`, and `pie_chart` render bounded datasets. Aggregate at the connector and provide explicit label and value fields.

### `table`

Displays a fixed, bounded result with declared columns and formatting. Use `explorer` for large or interactive collections.

### `steps`

Shows authored process stages and their status.

### `people`

Displays role or contact records.

### `task_progress`

Reads the latest run state for one job task key:

```yaml
type: task_progress
task: migrate_tickets
refresh_interval_seconds: 5
```

## Data access

A data widget names a connector method and authored arguments. Read calls run server-side through the job's connector mapping.

Use `shared_queries` when several widgets need the same call. A query is resolved once per refresh, then each widget can derive its value with JSONata.

Queries must remain read-only and bounded.

## `explorer`

Explorer supports server-side paging, filtering, sorting, projection, and streaming export:

```yaml
type: explorer
data:
  connector: staging
  resource: migration_errors
  base_query:
    filter:
      migration_id: fixed-scope
columns:
  - { field: source_id, label: Source ID, sortable: true }
  - { field: message, label: Error }
default_sort:
  updated_at: -1
page_size: 25
features: [filter, sort, columns, export]
```

Viewer filters are combined with `base_query` and cannot remove it. Declared columns form the viewer field allowlist. Mark only supported indexed fields sortable.

## Input widgets

### `form`

Edits one object in job configuration using typed text, number, boolean, select, or multiselect fields.

### `field_mapping`

Edits source-to-target mapping rows with optional transforms. Option sources must be read-only and pageable for large lists.

The canonical configuration schema should live in job-template `job_config`.

## `action`

```yaml
type: action
label: Run validation
confirm_message: Run validation now?
cooldown_seconds: 30
allow_public: false
action:
  kind: job_run
  tasks: [validate]
  skip_deps: false
```

Action kinds are `run_task`, `job_run`, and `connector_method`. Actions require confirmation, prevent duplicate in-flight execution per widget, apply cooldown, and create audit records.

Public execution requires additional gates. See [Public dashboard widget execution](/guides/public-dashboard-widget-execution).

## Authoring guidance

See [Author an operational dashboard](/guides/dashboard-authoring) for design and testing and [Job configuration reference](/reference/job-config) for input schemas.