> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboards

> Build a clear KayanOS operational view from approved data sources and filters without turning a dashboard into a permission bypass.

## Start with a decision, not a chart

A KayanOS dashboard turns a defined operational question into a reusable view. It can combine data-aware widgets, manual information, filters, layouts, and versions, but it never grants a viewer access to records they could not otherwise read. Design the decision first, then the data source, filter, widget, and audience.

For the Directorate of Citizen Services, a useful first question is: **“How many Citizen Service Requests were received and closed by Service Centre and week, and where is the queue becoming overdue?”** That question is more useful than “build a chart,” because it tells you what must be counted, grouped, filtered, refreshed, and reviewed.

![KayanOS dashboard configuration for Citizen Service Request workload.](https://kayanos.app/docs-images/en/build/dashboards.png)

## The dashboard model

| Element     | Purpose                                                                                                  | Governance question                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Dashboard   | The named operational view.                                                                              | Who owns its definition and who is allowed to view/edit it?                                          |
| Folder      | Organizes dashboards for a service area or audience.                                                     | Does the folder name help people find the right operational view without exposing sensitive content? |
| Version     | A saved dashboard structure/layout.                                                                      | Which version is reviewed/published for viewers, and what changed?                                   |
| Section     | A visual grouping of widgets.                                                                            | Does each section answer one related operational question?                                           |
| Widget      | A table, number, chart, status, progress, map, calendar, timeline, figure, text/image, or analysis view. | Is the widget type appropriate for the decision and data?                                            |
| Data source | Manual input, entity-backed records, or another released supported source/configuration.                 | Is the source authorized, current enough, and understandable?                                        |
| Filter      | A fixed widget/dashboard constraint or a viewer-controlled control.                                      | Does it narrow the question without hiding an access problem?                                        |
| Viewer      | A person consuming the dashboard.                                                                        | Can they read the underlying data within their roles/scopes?                                         |

Do not make one giant “all services” dashboard. Build small purpose-driven views: intake workload, inspection completion, decision backlog, or service-centre weekly performance.

## Choose a widget by the decision

| Need                      | Useful widget family                                                             | Example                                                                           |
| ------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| A current count or target | KPI / figure                                                                     | Open requests at Central Service Centre; percentage closed within target.         |
| A sortable evidence list  | Table                                                                            | Requests waiting for completeness review with reference, centre, age, and status. |
| Distribution by category  | Bar/column/pie or another chart family                                           | Requests by Service Centre or status category.                                    |
| Change over time          | Line/area chart, timeline, or calendar                                           | Requests received/closed per week.                                                |
| Workflow condition        | Status or progress                                                               | Inspection completion or decision readiness by request group.                     |
| Geographic workload       | Map                                                                              | Requests/inspections grouped by an approved service location.                     |
| Planned/dated work        | Calendar or timeline                                                             | Scheduled inspections and due review dates.                                       |
| Narrative/operating note  | Text, image, or manual figure                                                    | Published service target, contact escalation, or explanation of a metric.         |
| Reviewed analysis         | Analysis widget, where the released capability and organization limits permit it | A manager-oriented summary that is reviewed, not an autonomous decision.          |

Use the smallest visual that supports the decision. A KPI without its denominator or date range can mislead; a map with sensitive case-level locations may be inappropriate even when the source records are visible to a narrow team.

## Build a workload dashboard step by step

### 1. Define the measures in plain language

For the workload dashboard, write down:

* **Received this week:** number of requests whose intake/created date is in the selected week.
* **Closed this week:** number of requests whose approved closed status/date is in the selected week.
* **Open queue:** number of requests not in the closed status group.
* **Inspection completion:** completed inspections divided by the approved expected inspection set, when that denominator is well defined.

Do not label a field “closed” merely because it is non-empty. Agree the exact status/template/date field with the service owner before building the widget.

### 2. Configure the data source deliberately

For entity-backed widgets, select the entity and only the fields required for the visual: `status`, `service_centre`, created/closed date, reference, and a non-sensitive workload indicator. For manual widgets, state the owner, refresh cadence, source-of-truth document, and date of last update. Do not mix manual and entity data in one metric without labeling the distinction.

Where a widget supports grouping, aggregation, sorting, or a row limit, start narrow. A table of the latest 25 waiting requests is easier to validate than an unbounded list. For numeric values, decide whether the widget should count records, sum a field, calculate an average, or show a percentage—then document the denominator.

### 3. Apply fixed filters first

Fixed filters answer the stable question, for example:

```txt theme={null}
entity: service_requests
status: not closed
service_centre: central
```

Use the actual stored keys/option values configured in the entity. Validate a filter against known records before allowing a viewer control to change it. A filter that returns no data can mean a wrong key, an unavailable field, an empty scope, or genuinely no matching records; it is not proof of zero workload.

### 4. Add viewer filters carefully

Viewer filters can let an authorized manager choose a date range, service centre, or approved dimension. KayanOS merges the relevant widget filters with viewer-selected filters. Make the purpose visible:

| Viewer control          | Good use                                                               | Avoid                                                                               |
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Date range              | Compare a week, month, or approved reporting period.                   | Treating a time filter as proof that older data is inaccessible.                    |
| Service Centre selector | Let a regional manager focus on a Centre inside their authorized area. | Offering a selector whose values imply access to Centres the viewer should not see. |
| Status filter           | Focus on received, inspection, or decision queues.                     | Using a hidden/default status filter to obscure a backlog.                          |
| Custom metric filter    | Narrow an approved operational analysis.                               | Building a free-form query surface for unreviewed sensitive data.                   |

Filters narrow the query; they do not expand record permissions. If a viewer lacks source-record access, a widget may show a permission-denied or empty result even when the dashboard itself opens.

### 5. Lay out, version, and publish the view

Group the workload widgets by question: overview KPIs, queue table, time trend, then exception/inspection section. Give each widget a title that states the entity, measure, time basis, and scope—for example, “Open Citizen Service Requests — Central Service Centre — current week.”

Use a versioned change process:

1. Edit a draft/review version with non-production or approved limited data.
2. Compare the visual with a manual count and a known set of source records.
3. Ask the metric owner to confirm labels, filters, status definitions, and audience.
4. Publish/assign the approved version according to the released dashboard workflow.
5. Record a change note when a source field, filter, denominator, or access scope changes.

Changing a widget from manual to entity-backed, adding a field, or widening a filter can be a data-access change as well as a design change.

## Data access and privacy

Dashboard visibility and data visibility are different. A viewer may be allowed to open the dashboard yet have no readable source records for a widget, or may see only the subset allowed by their current role/scope. Treat a permission-denied/empty state as a diagnostic signal, not a reason to duplicate sensitive data into a manual widget.

Before publishing any widget, answer:

1. Which entity/fields are queried or manually entered?
2. Which viewers have underlying read access at which scopes?
3. Does the visual reveal a protected value through a count, label, drill-down/table, map point, export, or analysis prompt?
4. Is the date/aggregation small enough that a single case could be inferred?
5. Who owns accuracy, refresh, and correction when source data is late or wrong?

Use aggregate counts where they answer the question. Limit detail tables to the team that needs operational follow-up. Do not add personal identifiers, files, exact locations, or sensitive decision text to a broad manager dashboard merely because a chart can render them.

## Viewer mode, printing, and exports

Test the dashboard in the same viewer mode and viewport used by its audience. The viewer may use filters, and the dashboard can provide a report/print path that waits for widgets to be ready before printing. A PDF or printed report is a snapshot of what the viewer was authorized to see at that time; it must follow the organization’s handling, distribution, and retention policy.

Before exporting or printing:

* Set the reporting period and visible filters explicitly.
* Wait for all data widgets to load; do not capture a partial loading state as a report.
* Confirm titles, legends, table columns, language, and page breaks are understandable.
* Review the output for protected values, unintended scope, and stale manual figures.
* Store/distribute the resulting document only through an approved channel.

## Test matrix

| Test                  | Expected result                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------- |
| Source correctness    | A known record appears exactly once in the intended widget and not in an unrelated one.     |
| Filter correctness    | Fixed and viewer filters include/exclude the expected controlled records.                   |
| Zero versus error     | A true empty result is distinguishable from a permission-denied/configuration failure.      |
| Scope                 | A Central Service Centre viewer cannot obtain another Centre’s detail by changing a filter. |
| Aggregation           | KPI/chart totals match a reviewed manual count for a small date range.                      |
| Status/date semantics | Received/closed measures use the approved status and date basis.                            |
| Manual source         | Owner, refresh date, and source are visible and the value can be reconciled.                |
| Version change        | A changed widget/filter is reviewed before viewers rely on it.                              |
| Print/PDF             | Loaded widgets, filters, titles, language, and sensitive data are correct in the output.    |

## Troubleshooting

| Symptom                 | Likely cause                                                                                       | Check and resolve                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Widget is blank         | No matching records, wrong field/filter, source not configured, or viewer cannot read source data. | Test the filter against a known record, inspect widget configuration, then compare with the viewer’s source permissions. |
| Permission-denied state | Dashboard can open but the source query is not allowed.                                            | Review viewer role/scope and source-field visibility; do not replace the widget with copied sensitive data.              |
| KPI total is surprising | Wrong aggregation, denominator, date field, status mapping, or manual data is stale.               | Reconcile a small controlled period and document the correct measure definition.                                         |
| Filter changes nothing  | The filter may not apply to that section/widget or uses an unavailable field/value.                | Check filter scope, widget configuration, stored keys, and viewer control mapping.                                       |
| Chart is misleading     | Too many categories, unsuitable visual, mixed time bases, or tiny data set.                        | Simplify the question, choose a different widget, and add a clear title/period.                                          |
| Export is incomplete    | Widgets were still loading or report layout failed.                                                | Wait for readiness, retry through the approved viewer report path, and verify the output before distribution.            |

## Permissions and data-quality limits

Only builders with the appropriate dashboard access should change sources, filters, versions, or audience settings. Viewer access never overrides underlying entity/field/scope access. Use approved non-production records for a first build; then validate against a small reviewed production-like set before publishing. A dashboard is an operational aid, not a source-of-truth substitute or an authorization decision engine.

## Related guides

* [Entities](/build/entities)
* [Calculated fields](/build/calculated-fields)
* [Permissions and availability](/reference/permissions-and-availability)
* [Public API reference](/reference/public-api)
* [Troubleshooting](/reference/troubleshooting)