Dashboard procedures

The dashboard procedures manage a workspace’s dashboard catalog: dashboard.list, get, searchByName, create, copy, update, configuration.patch, document.check, delete, enable, disable, and reorder. Creating and changing dashboards needs the Editor, Admin, or Owner role; other members get workspace_not_editor, and non-members workspace_no_access. An unknown dashboard ID fails with dashboard_not_found. The steps in the UI are in Create and publish dashboards, and what a dashboard module receives is in the dashboard host contract.

Catalog fields

Field	Value
`id`	UUID; also the name of the source folder `src/dashboards/<id>/`
`name`	`LocalizedString`, 1–100 characters; not unique
`description`	Optional `LocalizedString`, up to 2,000 characters
`icon`	Optional Lucide icon id in kebab case, up to 64 characters, or null for the UI default
`configuration`	Open JSON object for the dashboard module; not localized
`disabledSince`	Soft-disable timestamp; `null` means enabled

The icon is a free-text Lucide id, like the icons of parameters. The configuration may nest objects; the module’s dashboardConfigType describes it. The template chosen at creation is not stored on the dashboard.

State	Effect
Enabled	Listed in the sidebar
Disabled	Hidden from the sidebar; `get`, `update`, `searchByName`, Setup settings, and a direct `/d/$id` URL still work; keeps its catalog place and files
Deleted	Removed; the next `hmi pull` removes `src/dashboards/<id>/`, keeping locally changed files as conflicts

Create

dashboard.create takes workspaceId, name, and optionally description, disabledSince, template (a template ID, empty by default), and configuration. template applies only at creation. The API does not check configuration against the module’s schema when creating; the dashboard checks it when it loads. A document key holds a document, checked on every create and change of any dashboard; see Check a document. To create a document dashboard, pass template: "document" and configuration: { "document": … }.

The Create dashboard list offers five starter templates:

Template	ID	Content
Empty	`empty`	A blank React dashboard for source-based customization (default)
Canvas	`graphics-scaffold`	An empty drawing edited in the browser
Map	`map`	A Google Map of named sites; see maps
Value tiles	`value-tiles`	A board of live values, gauges, trends, and controls; see value tiles
Document	`document`	A document of text, figures, tables, charts and inputs; see documents

templates.dashboard.list and templates.dashboard.get list templates and read one template’s configuration schema; see dashboard templates. For some device models, the assistant can add a dashboard made for that model.

Create from report in Setup creates a dashboard for an existing permanent report, held in configuration.presetId, and copies the report’s description. Deleting the report later leaves the dashboard, which then shows an error notice.

Copy

dashboard.copy with { id, name } copies the latest saved state of a dashboard within the same workspace. The copy keeps the icon, enabled or disabled state, description, configuration, drawings, source files, and published build, so it works without rebuilding. Its name is saved as plain text. The copy appears directly after the original in the catalog. Both dashboards refer to the same parameters and equipment, so a control in the copy writes to the same equipment.

Update

dashboard.update takes the dashboard id with its complete name, description, icon, and configuration. An update that replaces the configuration must include expectedConfiguration from the dashboard.get read it was based on; the whole configuration is compared, and a stale replacement fails with dashboard_configuration_conflict. The optional baseRevision, the dashboard’s revision from that read, makes an update fail with setup_conflict when the dashboard changed since. To change one drawing, use graphics.save, which keeps the rest of the configuration; see dashboard graphics.

Change part of a configuration

dashboard.configuration.patch changes part of any dashboard’s configuration with JSON Patch operations, applied in order. It takes the dashboard’s revision from dashboard.get as baseRevision and fails with setup_conflict when the dashboard changed since.

{
  "id": "4f0f6d8e-6a3b-4c9e-9b39-1c1b8c7f2a10",
  "baseRevision": 7,
  "operations": [
    {
      "op": "replace",
      "path": "/document/pages/0/rows/0/content/0/title",
      "value": "Payback in 4 years"
    },
    {
      "op": "add",
      "path": "/document/variables/rate",
      "value": { "kind": "input", "default": 0.21 }
    }
  ]
}

A patch that cannot be applied fails with dashboard_configuration_patch_failed, the failing operation’s index, and a reason: path_not_found, test_failed, move_into_itself, or too_large for a result over 4 MiB of JSON. When the dashboard’s build is a catalog template’s, it refuses a result with problems against the template’s config.schema.json that the configuration did not have before, with dashboard_configuration_invalid and those problems as JSON pointers; a document key the schema does not declare is one.

Check a document

dashboard.create, dashboard.update, dashboard.configuration.patch and workspace pushes check the document of every configuration that has one. A change is refused with dashboard_document_invalid when it adds errors. Each diagnostic has a code, a severity, a path (a JSON pointer into the configuration, such as /document/variables/total/formula), args, and for a formula the range of the problem. Errors the document already had, such as a reference to a parameter deleted since, do not block other changes, also when an edit moves the block that has them; one more of the same error does. Warnings never block.

dashboard.document.check checks a configuration as saving it would, without saving: it returns every diagnostic and the errors the save would refuse. hmi check checks documents in a pulled workspace the same way, except for device operations and uploaded files, which the push checks on the server.

Delete and reorder

dashboard.delete returns nextDashboardId, the dashboard to show next. dashboard.reorder takes the full list of dashboard IDs in the new order, including disabled ones; a list that is not exactly the current set fails with dashboard_reorder_mismatch. The sidebar and Setup show dashboards in this order.