---
title: "Custom Dashboards"
section: "API Reference"
route: /apidashboardview
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Custom Dashboards

Custom Dashboards are pages of charts, tables and embedded views that summarise your Entity data. They are managed in Operator and can be opened in Navigator, either from a bookmark or on their own.

A Dashboard is a grid of cells. Each cell loads a component that we provide, and most components read their data from a DataLab query, so the Dashboard stays up to date as the data changes.

This article will cover how to manage Dashboard records and descriptions about each of the cell components.

## Data model

Below is the core data model for a Dashboard. You can manage a record without populating the settings.

```typescript
interface IDashboardView {
    // Unique ID for the Dashboard.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the Dashboard is for.
    Description?: string;
    // The Dashboard content.
    // See the grid layout section below for the structure.
    Settings?: IDashboardSettings;
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

## Grid layout

The Dashboard settings hold a single list of cells. Cells are placed on a grid that is 12 columns wide and grows downwards as needed.

Each cell sets its own position and size in grid units, and all four grid values should be set on every cell. Cells should not overlap. If they do, the applications will push the later cell down until it fits.

```typescript
interface IDashboardSettings {
    // The cells that make up the Dashboard.
    grid: ICellItem[];
}

interface ICellItem {
    // Indicates what component should be loaded.
    // See the sections below for each component's params.
    component: "NUMBER_CHART" | "NUMBER_SERIES_CHART" | "ENTITY_TABLE" | "ENTITY_PLOT_2D" | "IFRAME" |
               "CESIUM_3D_MAP_VIEW" | "WORKFLOW_TABLE" | "WORKFLOW_METRICS";
    // Params are based on the component type.
    params: any;

    // The column the cell starts at, from 0 to 11.
    gridX?: number;
    // The row the cell starts at, starting from 0.
    gridY?: number;
    // How many columns the cell spans, from 1 to 12.
    gridW?: number;
    // How many rows the cell spans, from 1 to 12.
    gridH?: number;
    // Set to true when the width was chosen by hand.
    // When false the cell grows and shrinks with the other cells in its row.
    gridWFixed?: boolean;
    // Unique ID for the cell within this Dashboard.
    // Optional, used by the editor to follow a cell while it is moved.
    id?: string;
}
```

Every component accepts a "title" and "description" param. The title is shown at the top of the cell and the description underneath it.

Here is a small example with a number chart and a table side by side.

```typescript
{
    DisplayName: "Asset health",
    Description: "Condition overview for the north site.",
    Settings: {
        grid: [
            {
                component: "NUMBER_CHART",
                gridX: 0,
                gridY: 0,
                gridW: 4,
                gridH: 1,
                params: {
                    title: "Average condition",
                    type: "NEEDLE_GAUGE",
                    valueType: "VALUE",
                    dataLabQueryId: 12,
                    valueAttrPath: "condition",
                    minValue: 0,
                    maxValue: 100,
                    textSuffix: "%"
                }
            },
            {
                component: "ENTITY_TABLE",
                gridX: 4,
                gridY: 0,
                gridW: 8,
                gridH: 2,
                params: {
                    title: "Assets",
                    dataLabQueryId: 12
                }
            }
        ]
    }
}
```

## Grid layout: Common layouts

Below are some layouts that work well. Each one shows only the settings, swap in your own Project View, bookmark and DataLab query IDs.

Cells grow to fill the rows they span, so a taller 3D map view or table is made by giving it a larger "gridH".

### 3D view above a table

The bookmark across the full width, with the Entities it shows listed underneath.

```typescript
{
    grid: [
        {
            component: "CESIUM_3D_MAP_VIEW",
            gridX: 0,
            gridY: 0,
            gridW: 12,
            gridH: 2,
            params: {
                projectViewId: "6a224645",
                bookmarkId: "AGQQ4JKG2RZC7FOUQZSC6IM6VY"
            }
        },
        {
            component: "ENTITY_TABLE",
            gridX: 0,
            gridY: 2,
            gridW: 12,
            gridH: 2,
            params: {
                title: "Assets",
                dataLabQueryId: 4,
                layoutMode: "custom",
                attrPaths: [
                    "\"IFC TYPE\"",
                    "\"identity data\"/\"Is Asset\""
                ],
                showEntityTypeCol: false,
                showTagsCol: false
            }
        }
    ]
}
```

### 3D view beside a table

The bookmark and the table split the width evenly. Giving both cells the same "gridH" keeps them the same height.

```typescript
{
    grid: [
        {
            component: "CESIUM_3D_MAP_VIEW",
            gridX: 0,
            gridY: 0,
            gridW: 6,
            gridH: 4,
            params: {
                projectViewId: "d5612b60",
                bookmarkId: "AGQKDJWJ253SJO2PBPMI6FYGEQ"
            }
        },
        {
            component: "ENTITY_TABLE",
            gridX: 6,
            gridY: 0,
            gridW: 6,
            gridH: 4,
            params: {
                title: "Plant",
                dataLabQueryId: 6,
                layoutMode: "custom",
                attrPaths: [
                    "\"metadata\"/\"ComponentClass\"",
                    "\"metadata\"/\"ComponentName\""
                ]
            }
        }
    ]
}
```

### 3D view beside ticket metrics and tickets

The bookmark on the left spans three rows. On the right, the ticket metrics take the first row and the ticket table the two below it, so the column lines up with the bottom of the view.

```typescript
{
    grid: [
        {
            component: "CESIUM_3D_MAP_VIEW",
            gridX: 0,
            gridY: 0,
            gridW: 6,
            gridH: 3,
            params: {
                projectViewId: "9fc05a7d",
                bookmarkId: "AGQK33TSIJYWVDTOCE3YW4CIKI"
            }
        },
        {
            component: "WORKFLOW_METRICS",
            gridX: 6,
            gridY: 0,
            gridW: 6,
            gridH: 1,
            params: {}
        },
        {
            component: "WORKFLOW_TABLE",
            gridX: 6,
            gridY: 1,
            gridW: 6,
            gridH: 2,
            params: {
                title: "Tickets"
            }
        }
    ]
}
```

### 3D view beside number charts, with a table underneath

Four number charts sit in a two by two block beside the bookmark, each half the height of the view. A full width table runs underneath.

Here the charts count the Entities a query returns. With "segmentType" set to "FIXED", a count of 0 shows the first colour and a count of 1 or more shows the second.

```typescript
{
    grid: [
        {
            component: "CESIUM_3D_MAP_VIEW",
            gridX: 0,
            gridY: 0,
            gridW: 6,
            gridH: 2,
            params: {
                projectViewId: "9fc05a7d",
                bookmarkId: "AGQK3SMW7V4ZPONENFA6P2PM7U"
            }
        },
        {
            component: "NUMBER_CHART",
            gridX: 6,
            gridY: 0,
            gridW: 3,
            gridH: 1,
            params: {
                title: "Active warnings",
                description: "Number of alarms flagged as warnings.",
                type: "LARGE_NUMBER",
                valueType: "COUNT",
                dataLabQueryId: 12,
                segmentType: "FIXED",
                colors: [
                    { value: 0, color: "#14b2fc" },
                    { value: 1, color: "rgba(255, 127, 46, 1)" }
                ]
            }
        },
        // The other three charts follow the same shape at
        // (gridX 9, gridY 0), (gridX 6, gridY 1) and (gridX 9, gridY 1).
        {
            component: "ENTITY_TABLE",
            gridX: 0,
            gridY: 2,
            gridW: 12,
            gridH: 3,
            params: {
                title: "Systems and equipment",
                dataLabQueryId: 16
            }
        }
    ]
}
```

## Requesting records

You can request a list of all Dashboards or an individual one. Both include the settings JSON.

### Get a list of Dashboards

```http
GET https://{accountId}.api.nextspace.host/ui.dashboardviews
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
interface IResponse {
    // Array of Dashboard records.
    // See the data model above for the record structure.
    Items: IDashboardView[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.dashboardviews";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get Dashboard by ID

```http
GET https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Dashboard to get. |

**Response**

```typescript
// The response is the Dashboard record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Create and update records

You can create a record by performing a POST request to the same URL as the GET. If you specify the ID as '0' then it'll create a new record and return it. If you specify an existing ID then it'll update the record and return it.

When updating, only the properties you include are changed. Settings are replaced as a whole, so send the full grid rather than only the cells that changed.

### Create or update Dashboard

```http
POST https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Dashboard to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Dashboard JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "DisplayName": "My new Dashboard",
    "Settings": {
        "grid": []
    }
}
```

**Response**

```typescript
// The response is the Dashboard record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "My new Dashboard",
    "Settings": {
        "grid": []
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete a record

We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds.

### Delete Dashboard

```http
DELETE https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Dashboard to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.dashboardview/{view_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Opening in Navigator

A bookmark can show a Dashboard instead of the 3D scene. Set the bookmark's content type to "DASHBOARD" and give it the Dashboard ID. You can read about managing bookmarks in [Project Views and Bookmarks](/apiprojectview).

```typescript
// Bookmark settings that show a Dashboard.
// Camera and scene settings are ignored for this content type.
Settings: {
    contentType: "DASHBOARD",
    dashboardId: 5
}
```

Navigator can also open a Dashboard on its own, without a Project View, at "/dashboard/{view_id}".

## Cell: Number chart

Within this section and the ones below we'll cover what each component's params are and how to use them.

A number chart shows a single value. That value is either an attribute summed across the Entities in a DataLab query, the number of Entities a query returns, or an attribute of one specific Entity.

You can read about creating queries in [DataLab queries](/apidatalabqueries).

```typescript
interface INumberChartParams {
    title?: string;
    description?: string;
    /**
     * The kind of chart to draw.
     *
     * Bar = rectangle that fills up based on the value.
     * Battery = rectangle that fills up based on the value, but has a battery shape.
     * Thermometer = rectangle that fills up based on the value, but has a thermometer shape.
     * Needle Gauge = a gauge that fills up based on the value. Similar look to a speedometer.
     * Large Number = the value as text.
     * On Off Switch = a switch that is off below the second colour threshold and on from there up.
     */
    type?: "BAR" | "BATTERY" | "THERMOMETER" | "NEEDLE_GAUGE" | "LARGE_NUMBER" | "ON_OFF_SWITCH";
    // Where the value comes from.
    // VALUE = the "valueAttrPath" attribute summed across the query's Entities.
    // COUNT = the number of Entities the query returns.
    // ENTITY = the "valueAttrPath" attribute of the Entity in "entityId".
    // Default is "VALUE".
    valueType?: "VALUE" | "COUNT" | "ENTITY";
    // DataLab query ID. Used by the VALUE and COUNT value types.
    dataLabQueryId?: number;
    // Entity ID. Used by the ENTITY value type.
    entityId?: string;
    // Path to the attribute that holds the chart's value.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    valueAttrPath?: string;
    // Default value to use if the attribute is null or not a number.
    value?: number;
    // Static min value. Default is 0.
    minValue?: number;
    // Path to an attribute to use as the min value instead. The lowest value across the Entities is used.
    minValueAttrPath?: string;
    // Static max value. Default is 100.
    maxValue?: number;
    // Path to an attribute to use as the max value instead. The highest value across the Entities is used.
    maxValueAttrPath?: string;
    // Suffix to append to the value. Eg: "%" to turn the number 5 into "5%".
    textSuffix?: string;
    // How the "colors" thresholds are read.
    // PERCENT = each threshold's "percent" is a position between the min and max values.
    // FIXED = each threshold's "value" is compared with the chart's value directly.
    // Default is "PERCENT".
    segmentType?: "PERCENT" | "FIXED";
    // Colours to use for each threshold range.
    colors?: {
        percent?: number;
        value?: number;
        // CSS colour string.
        color: string;
    }[];
    // Used when "colors" is empty. The chart fades from the min colour to the max colour.
    minFillColor?: string;
    maxFillColor?: string;
    // If true then the chart will be a gradient of colours instead of solid colours.
    // Requires at least two colours.
    // Default is false.
    gradient?: boolean;
}
```

## Cell: Number series chart

A number series chart is a line chart of one or more attributes across the Entities in a DataLab query.

When "historic" is set, each line instead shows how the attribute changed over time, using the Entity historic data. You can read about recording it in [Entity historic data](/apientityhistoricdata).

```typescript
interface INumberSeriesChartParams {
    title?: string;
    description?: string;
    // DataLab query ID to load the Entities from.
    dataLabQueryId?: number;
    // Max number of Entities to load from the query.
    // Default is 20.
    pageSize?: number;
    // If true then the chart plots each Entity's history rather than its current value.
    // Default is false.
    historic?: boolean;
    // The lines to draw. A line without a "valueAttrPath" is skipped.
    lines?: INumberSeriesChartLine[];
}

interface INumberSeriesChartLine {
    // Path to the attribute that holds the line's value.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    valueAttrPath?: string;
    // Default value to use if the attribute is null or not a number.
    value?: number;
    // Suffix to append to the value. Eg: "%" to turn the number 5 into "5%".
    textSuffix?: string;
}
```

## Cell: Entity table

An Entity table lists the Entities a DataLab query returns, one row per Entity. The columns can be worked out from the data or picked by hand.

```typescript
interface IEntityTableParams {
    title?: string;
    description?: string;
    // DataLab query ID to load the Entities from.
    dataLabQueryId?: number;
    // auto = columns are worked out from the loaded Entities.
    // custom = columns are the "attrPaths" below.
    // Default is "auto".
    layoutMode?: "auto" | "custom";
    // Attribute paths to show as columns when the layout mode is "custom".
    // Each path is wrapped, Eg: "\"address\"/\"city\"".
    // If you're using the web libraries we recommend using the 'PathUtils' utility to wrap these for you.
    attrPaths?: string[];
    // Tabular View record the columns were picked from.
    // This is only a reference for the editor, the columns themselves are in "attrPaths".
    tabularViewId?: number;
    // Show the Entity Type column. Default is true.
    showEntityTypeCol?: boolean;
    // Show the Tags column. Default is true.
    showTagsCol?: boolean;
}
```

## Cell: Entity 2D plot

An Entity 2D plot draws the geometry of the Entities a DataLab query returns from above, coloured by their Entity Styles. You can read about Styles in [Entity Styles](/apientitystyles).

```typescript
interface IEntityPlot2DParams {
    title?: string;
    description?: string;
    // DataLab query ID to load the Entities from.
    dataLabQueryId?: number;
    // Max number of Entities to load from the query.
    // Default is 250.
    pageSize?: number;
}
```

## Cell: Iframe

An iframe cell embeds another web page. When an Entity ID is given, attribute values from that Entity can be substituted into the URL.

```typescript
interface IIFrameParams {
    title?: string;
    description?: string;
    // URL to load in the iframe.
    // Use ${"your_attribute_path"} to substitute in the attribute value of the Entity.
    url?: string;
    // Entity to read substituted attribute values from.
    entityId?: string;
    // Height of the iframe in pixels.
    height?: number;
}
```

## Cell: 3D map view

A 3D map view shows a Project View bookmark inside the Dashboard, with the same layers and camera as it has in Navigator.

```typescript
interface ICesium3DMapViewParams {
    title?: string;
    description?: string;
    // Project View the bookmark belongs to.
    projectViewId?: string;
    // Bookmark to show.
    bookmarkId?: string;
}
```

## Cell: Ticket table and metrics

The ticket table lists Workflow tickets, and the ticket metrics cell shows counts of them. Both take the same filters, and a filter that is left out does not narrow the list. These filters are the starting point, people viewing the Dashboard can narrow it further.

```typescript
// Shared by the "WORKFLOW_TABLE" and "WORKFLOW_METRICS" components.
interface IWorkflowParams {
    title?: string;
    description?: string;
    // Only show tickets of this Workflow type ID.
    typeId?: number;
    // Only show tickets with this status ID.
    statusId?: number;
    // Only show tickets in this queue ID.
    queueId?: number;
    // Only show tickets assigned to the user viewing the Dashboard.
    assignedToMe?: boolean;
    // Only show tickets created by the user viewing the Dashboard.
    createdByMe?: boolean;
}
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apidashboardview
