Build your first dashboard

Create the dashboard

1. Open Dashboards in the navigation.
2. In Dashboard ID, type operations-overview. Use lowercase letters, numbers and hyphens. The ID becomes part of the dashboard’s address and cannot change later.
3. Select Create dashboard.

The new dashboard opens empty, and it appears in the navigation under Dashboards.

Add a text card

1. Turn on Edit Mode at the top of the dashboard.
2. Select Add Widget and choose the Text card.
3. Hover over the new card and select Settings (the gear on the card).
4. In the text field, type Welcome to the operations overview. and apply.

Drag the card by its body to move it. Drag its lower-right corner to resize it. The grid has 24 columns, so a card 12 columns wide fills half the width.

Add a saved query

A saved query gives widgets data. It names an operation that an administrator approved; you choose it from a list and never type a URL or SQL.

1. Open the settings menu (the gear in the dashboard header) and choose Saved queries.
2. Select Add query.
3. In Result name, type trips. Widgets will refer to the data by this name.
4. Choose a Connection and an Operation from the lists.
5. Leave Parameters as {} for now.
6. Select Apply to draft.

The query runs as soon as a widget uses it.

Show a number from the query

1. Select Add Widget and choose a statistic, for example the Circular statistic.
2. Open the widget’s Settings.
3. Set Data Source to Planner, then choose trips as the Variable.
4. In the value field, type a template with a column from the result, such as {{completed}}. Use {{row.<column>}} or {{<column>}} for any column the operation returns.
5. Apply the settings.

The widget shows the value from the first row of the result. When the query is loading, it shows a loading message. If it fails, it shows an error, never the details of the data source.

Add a filter

Filters let viewers narrow the data without editing the dashboard.

1. Open the settings menu and choose Filter Bar.

2. Select Add filter. Set Filter key to date_range, the label to Date, and the type to Date range.

3. Apply the filter.

4. A date range filter gives two values, named after its key: date_range_from and date_range_to. Back in Saved queries, open trips and bind two parameters to them, for example:

   {
     "from": { "kind": "filter", "key": "date_range_from", "omitWhenEmpty": true },
     "to": { "kind": "filter", "key": "date_range_to", "omitWhenEmpty": true }
   }

   The parameter names (from, to) must be ones the operation accepts. omitWhenEmpty leaves a parameter out while the filter is empty. Add filters explains the values each filter type provides.

Pick a date range in the filter bar. The statistic reloads with the new range.

Share it

1. Turn off Edit Mode.
2. Open the settings menu and select Manage permissions.
3. Enter your colleague’s user ID exactly as your identity provider knows it, choose the role Consumer, and add it.
4. Select Save changes.

Your colleague can now open the dashboard and use its filters, but cannot change it. To let them edit, give them Editor.