Input and action widgets

Widgets that make a dashboard interactive: form and field_mapping persist typed configuration onto the Job, action dispatches server-executed side effects, task_progress reads run status, and explorer embeds a curated data browser. Shared keys (id, title, width, scope, refresh_interval_seconds) are on the Widgets overview.

form

Typed fields whose values persist as one object under a config_key in the Job's configuration. Tasks read the saved object in JSONata as job_config.<config_key>.

Form fields use the same shape as job template job_config form entries — key (required), label, type (text | number | boolean | select | multi_select), required, default, format (email | url), inline options or a connector-backed options_source, depends_on, and hide_if_expr. The full field and option-source tables are in the job_config schema.

- id: sync_options
  type: form
  config_key: sync_options
  fields:
    - { key: batch_size, label: Batch size, type: number, required: true, default: 100 }
    - { key: notify, type: boolean, default: false }
    - { key: owner_email, type: text, format: email }

Prefer declaring the canonical schema in the job template's top-level job_config: block; a dashboard form is then a customer-facing editor for the same persisted keys.

field_mapping

A two-column mapping editor (left = source field, right = target field). The persisted value is an array of { source_field, target_field, transform? } under config_key.

- id: meeting_map
  type: field_mapping
  title: Salesforce → HubSpot meeting fields
  config_key: meeting_field_map_sf_to_hs
  allow_transform: true
  source:
    options_source:
      connector: salesforce
      method: proxy_list
      args: { resource: describe, query: { object: arguments.sf_object } }
    label_expr: $.label
    value_expr: $.name
    search: { on_frontend: true }
  target:
    options_source:
      connector: hubspot
      method: proxy_list
      args: { resource: properties, query: { objectType: meetings } }
    label_expr: $.label
    value_expr: $.name
    search: { on_frontend: true }

Missing config_key fails with <path>.config_key is required for field_mapping; missing sides fail with <path>.source and .target are required for field_mapping.

action

A declarative button that runs entirely server-side. Viewers submit form values only; the server resolves the action from the stored YAML. Every action opens a confirmation dialog before running.

Action kinds

action.kind must be one of run_task, job_run, or connector_method:

For run_task and connector_method, arguments_expr (JSONata) or a literal args value builds the dispatch arguments. The expression context is { form, job, arguments, job_config, row? } — row is set when an authenticated operator triggers the action from a field_mapping row_action.

- id: invite_user
  type: action
  label: Invite
  form:
    fields:
      - key: email
        type: text
        required: true
        format: email
  action:
    kind: run_task
    task: invite-user
    arguments_expr: '{ "email": form.email, "job_id": job.id }'
  allow_public: true
  cooldown_seconds: 30
  confirm_message: Sends an invite email to this address.
  on_success:
    refresh: [user_mapping]
    message: User invited

Safety: the server deduplicates in-flight executions per widget, applies cooldown_seconds, and records audit rows in dashboard_action_runs.

task_progress

Reads the latest run state for one job task key. No connector call.

- id: migrate_progress
  type: task_progress
  task: migrate_tickets
  refresh_interval_seconds: 5
  stat_expr: run.item_count

Returns the latest run status, item_count, duration_ms, and per-step counts from metrics_summary.

explorer

A curated data browser: the author pins the connector, resource, and a server-enforced base_query; viewers get paging, filtering, sorting, column selection, and export.

- id: errored_tickets
  type: explorer
  data:
    connector: mongo
    resource: zendesk_tickets
    base_query:
      filter: { severity: error }
  default_sort: { updated_at: -1 }
  page_size: 25
  features: [filter, sort, columns, export]
  columns:
    - { field: id, label: ID, sortable: true }
    - { field: subject, format: truncate }

Sort is always applied server-side. Viewers may sort only on columns marked sortable: true — mark only fields backed by an index; sort requests on other columns are ignored and default_sort stays in effect. Export streams all matching rows as CSV or NDJSON server-side, applying the same merged base_query, scope profile, and column allowlist; omitting export from features disables both the button and the export endpoints.

Public execution gates

Interactive widgets are gated twice on the public share surface:

• Input widgets (form, field_mapping): the server kill switch ENVOY_PUBLIC_DASHBOARD_INPUT_ENABLED must be enabled (it defaults off) and the dashboard must set allow_public_input: true.
• Action widgets: the server kill switch ENVOY_PUBLIC_DASHBOARD_ACTIONS_ENABLED=true must be set and the widget must set allow_public: true on a public page. Client-supplied row context is ignored on the public path.

See Authoring dashboards for the full public-share model.

Related

• job_config schema — the schema and stored value shapes input widgets write
• Widgets overview — shared keys and data binding
• Authoring dashboards — public sharing and design guidance