Dashboards

Functions for folder custom dashboards: read configuration, enable an empty dashboard, add KPI/chart widgets, and update existing widgets backed by workspace tables.

MVP: Higento walks you through widget options with ask-user (one question per turn), then calls dashboard-add-widget. There is no inline chart preview in chat yet — open the folder in the UI to see widgets.

Tables must live in the folder tree (folder + subfolders). Use dashboard-read to list available tables and saved views.

---

dashboard-read

Read a folder's custom dashboard state and datasource pickers.

Input

Field	Type	Required	Description
folderId	string	No	Folder id (dir_…). Omit when Higento is opened inside that folder.

Output

Field	Type	Description
enabled	boolean	Whether a version-2 dashboard config exists.
widgetCount	number	Number of widgets on the dashboard.
widgets	array	Each: id, type, title, tableId, tableName.
tables	array	Tables in the folder tree: id, name, views[] (id, name).
folderId	string	Folder id.
folderName	string	Folder display name.

---

dashboard-enable

Enable an empty custom dashboard on a folder. Idempotent if already enabled.

Input

Field	Type	Required	Description
folderId	string	No	Folder id. Omit when scoped to that folder.

Output

Field	Type	Description
alreadyEnabled	boolean	true if the dashboard was already on.
widgetCount	number	Current widget count (0 when newly enabled).

---

dashboard-add-widget

Append one widget to a folder dashboard after the user confirmed the wizard.

Input

Field	Type	Required	Description
folderId	string	No	Target folder.
type	string	Yes	kpi, bar, line, pie, or timeseries.
title	string	Yes	Widget title on the dashboard.
tableId	string	Yes	Table id from dashboard-read.tables.
op	string	Yes	count, sum, or avg.
viewId	string	No	Saved view id (AND-merged filter).
extraFilter	object	No	TableRecordFilter (same as table-read-rows).
valueField	string	No	Column for sum/avg.
groupBy	string	No	Category column for bar/line/pie.
timeField	string	No	Date column for timeseries.
bucket	string	No	hour, day, week, or month (timeseries; default day).

Output

Field	Type	Description
widgetId	string	New widget id (wid_…).
widgetType	string	Visualization type.
widgetTitle	string	Title stored on the widget.
widgetCount	number	Total widgets on the dashboard after add.

Widget types

type	Required fields
kpi	op (count needs no valueField; sum/avg need valueField)
bar, line, pie	groupBy, op, optional valueField
timeseries	timeField, op, optional bucket, optional valueField

---

dashboard-update-widget

Update an existing widget on a folder dashboard. Same input shape as dashboard-add-widget, plus widgetId from dashboard-read.widgets. Grid layout for that widget is preserved.

Input

Field	Type	Required	Description
widgetId	string	Yes	Widget id (wid_…) from dashboard-read.
folderId	string	No	Target folder.
type	string	Yes	kpi, bar, line, pie, or timeseries.
title	string	Yes	Widget title on the dashboard.
tableId	string	Yes	Table id from dashboard-read.tables.
op	string	Yes	count, sum, or avg.
viewId	string	No	Saved view id (AND-merged filter).
extraFilter	object	No	TableRecordFilter (omit when no filter — do not pass {}).
valueField	string	No	Column for sum/avg.
groupBy	string	No	Category column for bar/line/pie.
timeField	string	No	Date column for timeseries.
bucket	string	No	hour, day, week, or month (timeseries; default day).

Output

Field	Type	Description
widgetId	string	Updated widget id (unchanged).
widgetType	string	Visualization type.
widgetTitle	string	Title stored on the widget.
widgetCount	number	Total widgets on the dashboard.

Call table-read for the target table before updating metrics or filters. Never guess column names.

---

Recommended wizard (ask-user)

1. Widget type (KPI / bar / line / pie / time series)
2. Table (from dashboard-read.tables)
3. Filter (all rows / view / custom)
4. Metrics (op, groupBy, timeField, … — one ask-user topic at a time)
5. Title
6. Confirm → dashboard-add-widget

See Folder dashboards use case for a full example flow.