Saved Layout Format

Your dashboard layout is stored as a single JSON document on your tenant. You do not need to read or write it to use KvantumCI: the editor described in Building Your Own Dashboard maintains it for you. It is documented here because the same structure is accepted by the API, so a layout can be scripted, backed up or copied between tenants.

Structure

The document has three fields at the top level.

Field	Type	Meaning
`templates`	array	The dashboard tabs, in the order they appear in the tab bar.
`activeTemplateId`	string	The `id` of the tab that opens first.
`version`	integer	Format version of the layout document.

Each entry in templates is one tab:

Field	Type	Meaning
`id`	string	Unique identifier for the tab.
`name`	string	The tab label shown in the tab bar.
`icon`	string	The name of the icon shown on the tab.
`rows`	array	The rows of the tab, top to bottom.

Each entry in rows is one row:

Field	Type	Meaning
`id`	string	Unique identifier for the row.
`columns`	integer	How many columns the row is split into. The editor offers 1, 2, 3 and 4.
`cells`	array	The cells of the row, left to right.

Each entry in cells is one cell:

Field	Type	Meaning
`id`	string	Unique identifier for the cell.
`widgets`	array of strings	The widget identifiers placed in this cell, top to bottom.

The strings in widgets are the widget identifiers listed in the Widget Reference, for example kpi-projects, severity-pie or top-risk-projects. The editor keeps each cell to a single large widget, or a stack of up to four small ones. The API does not enforce that rule, so a hand-written layout should follow it too, otherwise the result may not render as you expect.

Example

A one-tab layout with a three-card top row and a single chart below it:

{
  "templates": [
    {
      "id": "template-overview",
      "name": "Overview",
      "icon": "LayoutDashboard",
      "rows": [
        {
          "id": "row-kpis",
          "columns": 3,
          "cells": [
            { "id": "row-kpis-cell-0", "widgets": ["kpi-projects"] },
            { "id": "row-kpis-cell-1", "widgets": ["kpi-repositories"] },
            { "id": "row-kpis-cell-2", "widgets": ["kpi-runs"] }
          ]
        },
        {
          "id": "row-severity",
          "columns": 1,
          "cells": [
            { "id": "row-severity-cell-0", "widgets": ["severity-bar-chart"] }
          ]
        }
      ]
    }
  ],
  "activeTemplateId": "template-overview",
  "version": 1
}

Saving a layout through the API

The layout is written with a POST to /dashboard/grid, with your tenant identifier in the tenant header. The request body wraps the layout document in two fields:

Field	Type	Meaning
`data`	object	The layout document described above.
`type`	string	Either `dashboard` for your main dashboards, or `analytics` for the per-project analytics dashboards.

The two types are stored independently on your tenant, so saving one never affects the other. The request requires the dashboard:read permission; see Roles and Permissions.

Identifiers in the document only need to be unique within it. They are yours to choose, and the editor generates them automatically when you build a layout through the interface.

Structure​

Example​

Saving a layout through the API​

Structure

Example

Saving a layout through the API