---
title: "Dashboards"
description: "Reports and charts. Store dashboards and widgets as data (KPI, bar, line, pie and table definitions) for a client to render."
canonical: "https://obop.dev/apps/dashboards/"
lang: "en"
---

# Dashboards

## What it is for

Store dashboards and widgets as data (KPI, bar, line, pie and table definitions) for a client to render. The package never runs a query and does not check that the models it names exist.

## What the package does and does not do

Dashboards and their widgets stored as data, for a UI to render. A dashboard has a title and an owner and is private to them (and to dashboards.manager) unless it is shared; its tiles follow it. A widget describes one tile with these fields: kind (kpi, bar, line, pie or table), model_name (the model to read, for example sale_order), measure_field (the field to aggregate; empty for count), aggregate (count or sum; sum needs a number or money measure_field), group_by (field to split by, for bar, line, pie and table; empty for a single kpi value), filter (a JSON object of field names to exact values, for example {"state":"paid"}; empty means all records) and position (order on the dashboard, lowest first). The package only stores the definition; it does not check that the model or fields exist and it computes nothing.

## Module details

- **Version:** `0.3.0`
- **Author:** SpaceCorps
- **Licence:** [AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later.html)
- **Needs core:** `^0.2` (core 0.2.0 is current)
- **Maturity:** Experimental
- **Categories:** Productivity

## Models

### `dashboards_dashboard`

A dashboard: a titled, ordered collection of widgets

Read group: `dashboards.user`. Write group: `dashboards.manager`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `title` | text | `none` | no | `dashboards.user` | in clear | Dashboard title, for example Sales overview |
| `owner` | text | `internal` | yes | `dashboards.user` | masked | User name of the person who owns the dashboard; the person who creates it unless set otherwise |
| `description` | longtext | `none` | no | `dashboards.user` | in clear | What the dashboard shows and for whom |
| `shared` | bool | `none` | no | `dashboards.user` | in clear | Whether everyone who may read dashboards sees it (and its tiles), or only the owner and dashboards.manager; the server enforces it |
| `position` | number | `none` | no | `dashboards.user` | in clear | Order among dashboards, lowest first |

### `dashboards_widget`

One tile on a dashboard, defined by what to read and how to aggregate it

Read group: `dashboards.user`. Write group: `dashboards.manager`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `dashboard_id` | ref → dashboards_dashboard | `none` | no | `dashboards.user` | in clear | The dashboard the widget is on |
| `title` | text | `none` | no | `dashboards.user` | in clear | Tile title, for example Paid orders |
| `kind` | select (kpi, bar, line, pie, table) | `none` | no | `dashboards.user` | in clear | How the tile is drawn: kpi, bar, line, pie, table |
| `model_name` | text | `none` | no | `dashboards.user` | in clear | Model the tile reads, for example sale_order |
| `measure_field` | text | `none` | no | `dashboards.user` | in clear | Field to aggregate: a number or money field of the model; empty when counting |
| `aggregate` | select (count, sum) | `none` | no | `dashboards.user` | in clear | How records are combined: count or sum |
| `group_by` | text | `none` | no | `dashboards.user` | in clear | Field to split the result by (a select, ref or date field); empty for one value |
| `filter` | longtext | `none` | no | `dashboards.user` | in clear | JSON object of field names to exact values that records must match, for example {"state":"paid"}; empty means all records |
| `position` | number | `none` | no | `dashboards.user` | in clear | Order of the tile on the dashboard, lowest first |

## Workflows

This app has no workflow actions; records are created and edited directly.

## Permission groups

Groups used by this app:

- `dashboards.manager`
- `dashboards.user`

## Approval steps

No step in this app needs an approval, apart from deleting records.

## What agents can and cannot do

An agent can read, search, create and update records of this app, and run the actions that need no approval, within the permission groups of its token.

It can only propose these steps, and a person must approve them: `dashboards_dashboard.delete`, `dashboards_widget.delete`.

Personal data is masked as placeholder tokens: `dashboards_dashboard.owner`.

## Dependencies

None.

## Install

Install it from the Customize app (Marketplace), or from the command line:

```bash
obop modules install-from dashboards
```

Needs a database and administrator rights.

## Build your own

[The module guide shows how apps like this one are written](/docs/reference/module-manifest/)