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.
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.
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.
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.
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.
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.
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.
Requesting records
You can request a list of all Dashboards or an individual one. Both include the settings JSON.
Get a list of Dashboards
Get Dashboard by ID
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
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
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.
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.
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.
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.
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.
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.
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.
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.