# Configure a widget

Choose a widget's visualization, describe its data with queries and filters, combine them with formulas and set a target.

> **Access:** edit right on the dashboard. A template or read-only dashboard is edited after **Duplicate to customize**. The dashboards module and some indicators depend on your plan.
>
> **Language:** the widget editor is not yet translated into English. Labels below translate the French interface; formulas and query code are identical in both languages.

## Open the editor

1. On the dashboard, select **Customize**.
2. Add a widget from the gallery, or open an existing widget's menu and choose **Configure**.
3. The editor opens in a side panel. **Expand editor** gives it the full screen width.

The panel holds the **Title**, a **Preview**, then the **Visualization**, **Data** and **Display** sections. **Apply** carries the settings over to the dashboard; then **Save** the dashboard.

The preview updates as you type. While the configuration is incomplete, it says the preview will appear once the configuration is complete, or shows the last valid configuration. **Pin preview** keeps it visible while you scroll through the settings.

## Choose the visualization

| Visualization | Use | Expected data |
|---|---|---|
| Key figure | One highlighted value. | A single value. |
| Ratio | A percentage with a progress bar or ring. | A part and a total. |
| Line | Change over time. | A grouping by date; up to 12 series. |
| Bars | Comparison between categories or periods. | A grouping; up to 12 series. |
| Donut | A breakdown. | A grouping by category. |
| List | Items with a link to their details. | Columns (maximum 8). |
| Matrix | A grid crossing two dimensions, colored by volume. | A grouping and a **Split by** field. |
| Network graph | Links between vendors, assets or risks. | A network-type source. |
| Text | Instructions, context, links. | None: Markdown content (headings, lists, links, bold). |
| Section | A heading that splits the dashboard into parts. | None: title and optional **Subtitle**. |
| News | Latest cyber news. | None: **Sources**, **Categories** and **Number of articles**. |
| Cartography | A mini-map of your vendors and their dependencies. | None. |

Changing the visualization adapts the existing queries when possible. If the data does not fit the new type, a message at the bottom of the panel explains why, for example that this widget type needs a grouping and a **Split by** field.

## Describe the data with queries

The **Data** section contains one or more queries. Each query has a name (**a**, **b**…) that the displayed value and formulas reuse.

1. In **Source**, choose a ready-to-use indicator (**Indicators** group) or a data family (**Data** group: vendors, risks, treatment measures, incidents, controls, evidence, exemptions, assessments, assets, vulnerabilities, applications, activities, GDPR processing activities, connectors, action plans, tasks).
2. Add filters (see below).
3. For a line, bars or donut, choose **Group by**. For a date, choose the period: day, week, month, quarter or year.
4. For a list, choose the **Columns** (maximum 8).
5. Open **Advanced options** if needed: **Calculate** (Count, Distinct values, Sum, Average, Median, Minimum, Maximum, Share), **On field**, **Split by**, **Period** and **Date used**, **Sort by** and **Maximum number of rows** (maximum 200).
6. The **Label** field renames the series in the legend.

The **Action plans** selector limits the data to the chosen action plans, for sources attached to them.

On each query row, you can **Hide** or **Show** the query (it is still computed and usable by formulas), **Duplicate** it, **Delete** it or collapse it. The **Form / Code** toggle lets you write the query as text; see [Query language](https://docs.cisapp.eu/en/reporting/query-language).

The **Query** button adds a query, copied from the last data query: changing one filter is often enough. A widget holds at most 6 queries.

## Filter the data

1. Select **Add a filter**, then choose a field, a condition and a value.
2. To combine conditions, select **Add a group** and choose its mode: **All**, **At least one** or **None**.

Conditions available depending on the field: equals, differs from, greater than, greater than or equal, less than, less than or equal, contains, is one of, is not one of, contains all, is between, is empty, is filled in.

Dynamic values:

- **Me (signed-in user)** and **My teams**: each reader sees their own figures.
- Relative dates: Today, 7, 30 or 90 days ago, One year ago, In 7 or 30 days, Start of the week, month, quarter or year, or **Exact date**.

An incomplete filter is not applied; it is flagged as not yet taken into account in the preview: complete or delete it. A query holds at most 20 conditions and 4 levels of groups.

## Choose the displayed value

At the top of the **Data** section, a block states what the widget displays. It depends on the visualization.

**Key figure, donut, matrix, network graph: Displayed value.** Enter an expression: `a` by default, the first query. Click query chips to insert them, for example `a - b`. The block summarizes what is displayed.

**Ratio: Part and total.** The widget displays part / total as a percentage.

- **Part**: the counted query, with its **Part filters**.
- **Total**: by default, the same source without the part filters. You can also choose another query, a formula or **New source…**.

Example: share of critical vendors whose assessment is up to date, out of all critical vendors.

**Line, bars, list: Displayed series.** Each visible query is a series. **Combine series** replaces the series with a **Combined expression** (`pct(a, b)` by default). **Show series separately** returns to the series. A line or bar chart shows at most 12 series.

## Combine with formulas

The **Formula** button adds a named intermediate value, for example `d = max(a, b)`. The displayed value and later formulas can reuse it.

- Operators: `+`, `-`, `*`, `/` and parentheses.
- The **?** button lists the available functions. While typing, browse suggestions with ↑ ↓; **Enter** or **Tab** inserts, **Esc** closes.
- A formula only reads queries and formulas declared before it.
- A widget holds at most 4 formulas, each up to 200 characters and 8 levels of nesting.

| Function | Result |
|---|---|
| `abs(x)` | Absolute value. |
| `round(x, digits)` | Rounded to `digits` decimals (0 by default). |
| `floor(x)`, `ceil(x)` | Rounded down or up to an integer. |
| `sqrt(x)` | Square root (empty if negative). |
| `pow(x, n)` | x to the power n. |
| `min(…)`, `max(…)` | Smallest or largest value. |
| `sum(…)`, `avg(…)` | Sum or average, empty values ignored. |
| `clamp(x, low, high)` | Keeps x between low and high. |
| `coalesce(…)` | First non-empty value (fallback value). |
| `pct(part, whole)` | Percentage: part / whole × 100. |

Examples:

- `pct(a, b)`: share of **a** in **b**, as a percentage.
- `a - b`: gap between two queries, for example open risks minus treated risks.
- `coalesce(a, 0)`: shows 0 instead of an empty value.

Series are aligned by period and breakdowns by category. A division by zero or a missing value gives an empty value, except for `coalesce`, `min`, `max`, `sum` and `avg`, which ignore empty values.

Deleting a query used by a formula shows a warning: fix the formula concerned.

## Set a target and thresholds

For a key figure or ratio, the **Display** section offers **Target and thresholds**:

- **Target** (or **Target (%)**): shown next to the value; once reached, the value turns green.
- **Threshold reached** and **Warning threshold**: green above the reached threshold, orange above the warning threshold, red otherwise. If the reached threshold is lower than the warning threshold, a low value is better.
- **Track history**: records the value every day. The line starts when tracking is enabled: nothing is backfilled.

For a ratio, **Display** also lets you choose **Bar** or **Ring**.

Once history is enabled, **Show evolution** in the widget menu adds a line of the recorded value. Only its title can be edited; the query is changed on the original widget.

## Expected outcome

The widget shows the intended value, percentage or series, the preview matches the result, and the dashboard is saved.

## Common issues

- **Apply** stays greyed out: read the messages at the bottom of the panel, for example add a query or make one visible, or 6 queries maximum.
- Outputs do not have the same shape: combined queries must use the same grouping.
- A query is split by a second field: remove **Split by** from that query to use it in a formula.
- A query returns a list or graph: a list or graph cannot be used in a formula.
- No query or formula is called **d**: declare formula **d** before the one using it, or fix the name.
- **Track history** missing: history only applies to a single data query, with no formula, and without the **Me** or **My teams** values.
- Value differs from another widget: the dashboard period may override the widget's own period. A failing query is flagged in the widget frame.

See also [Read and build dashboards](https://docs.cisapp.eu/en/reporting/dashboard) and [Query language](https://docs.cisapp.eu/en/reporting/query-language).