# Configurer un widget

Choisir la visualisation d’un widget, décrire ses données avec des requêtes et des filtres, les combiner par des formules et fixer un objectif.

> **Accès :** droit de modification sur le tableau de bord. Un modèle ou un tableau en lecture seule se modifie après **Dupliquer pour personnaliser**. Le module tableaux de bord et certains indicateurs dépendent de votre offre.

## Ouvrir l’éditeur

1. Sur le tableau, cliquez **Personnaliser**.
2. Ajoutez un widget depuis la galerie, ou ouvrez le menu d’un widget existant et choisissez **Configurer**.
3. L’éditeur s’ouvre dans un panneau latéral. **Agrandir l’éditeur** lui donne toute la largeur de l’écran.

Le panneau contient le **Titre**, un **Aperçu**, puis les sections **Visualisation**, **Données** et **Affichage**. **Appliquer** reporte les réglages sur le tableau ; pensez ensuite à **Enregistrer** le tableau.

L’aperçu se met à jour pendant la saisie. Tant que la configuration est incomplète, il affiche « L’aperçu s’affichera une fois la configuration complète » ou « Aperçu de la dernière configuration valide ». **Épingler l’aperçu** le garde visible pendant que vous faites défiler les réglages.

## Choisir la visualisation

| Visualisation | Usage | Données attendues |
|---|---|---|
| Chiffre clé | Une valeur mise en avant. | Une valeur unique. |
| Ratio | Un pourcentage avec une barre ou un anneau de progression. | Une part et un total. |
| Courbe | Une évolution dans le temps. | Un regroupement par date ; jusqu’à 12 séries. |
| Barres | Une comparaison entre catégories ou périodes. | Un regroupement ; jusqu’à 12 séries. |
| Anneau | Une répartition. | Un regroupement par catégorie. |
| Liste | Des éléments avec un lien vers leur détail. | Des colonnes (8 maximum). |
| Matrice | Une grille qui croise deux dimensions, colorée selon le volume. | Un regroupement et un champ **Séparer par**. |
| Graphe réseau | Les liens entre fournisseurs, actifs ou risques. | Une source de type réseau. |
| Texte | Des consignes, du contexte, des liens. | Aucune : contenu Markdown (titres, listes, liens, gras). |
| Section | Un titre qui sépare le tableau en parties. | Aucune : titre et **Sous-titre** facultatif. |
| Actualités | Les dernières actualités cyber. | Aucune : **Sources**, **Catégories** et **Nombre d’articles**. |
| Cartographie | Une mini-carte de vos fournisseurs et de leurs dépendances. | Aucune. |

Changer de visualisation adapte les requêtes existantes quand c’est possible. Si les données ne conviennent pas au nouveau type, un message l’indique en bas du panneau, par exemple « Ce type de widget demande un regroupement et un champ « Séparer par ». »

## Décrire les données avec des requêtes

La section **Données** contient une ou plusieurs requêtes. Chaque requête porte un nom (**a**, **b**…) que la valeur affichée et les formules réutilisent.

1. Dans **Source**, choisissez un indicateur prêt à l’emploi (groupe **Indicateurs**) ou une famille de données (groupe **Données** : fournisseurs, risques, mesures de traitement, incidents, contrôles, preuves, dérogations, évaluations, actifs, vulnérabilités, applications, activités, traitements RGPD, connecteurs, plans d’action, tâches).
2. Ajoutez des filtres (voir plus bas).
3. Pour une courbe, des barres ou un anneau, choisissez **Regrouper par**. Pour une date, choisissez la période : jour, semaine, mois, trimestre ou année.
4. Pour une liste, choisissez les **Colonnes** (8 maximum).
5. Ouvrez **Options avancées** si nécessaire : **Calculer** (Nombre, Valeurs distinctes, Somme, Moyenne, Médiane, Minimum, Maximum, Part), **Sur le champ**, **Séparer par**, **Période** et **Date utilisée**, **Trier par** et **Nombre maximum de lignes** (200 maximum).
6. Le champ **Libellé** renomme la série dans la légende.

Le sélecteur **Plans d’action** limite les données aux plans d’action choisis, pour les sources qui s’y rattachent.

Sur chaque ligne de requête, vous pouvez **Masquer** ou **Afficher** la requête (elle reste calculée et utilisable par les formules), la **Dupliquer**, la **Supprimer** ou la replier. La bascule **Formulaire / Code** permet d’écrire la requête en texte ; voir [Langage de requête](https://docs.cisapp.eu/pilotage/langage-requete).

Le bouton **Requête** ajoute une requête, copiée de la dernière requête de données : il suffit souvent d’en changer un filtre. Un widget compte au plus 6 requêtes.

## Filtrer les données

1. Cliquez **Ajouter un filtre**, choisissez un champ, une condition et une valeur.
2. Pour combiner des conditions, cliquez **Ajouter un groupe** et choisissez le mode : **Toutes** (toutes les conditions), **Au moins une** ou **Aucune**.

Conditions disponibles selon le champ : est égal à, est différent de, supérieur, supérieur ou égal, inférieur, inférieur ou égal, contient, est parmi, n’est pas parmi, contient tous, est entre, est vide, est renseigné.

Valeurs dynamiques :

- **Moi (utilisateur connecté)** et **Mes équipes** : chaque lecteur voit ses propres chiffres.
- Dates relatives : Aujourd’hui, Il y a 7, 30 ou 90 jours, Il y a un an, Dans 7 ou 30 jours, Début de la semaine, du mois, du trimestre ou de l’année, ou **Date précise**.

Un filtre incomplet n’est pas appliqué ; il est signalé par « Pas encore pris en compte dans l’aperçu : complétez ou supprimez. » Une requête compte au plus 20 conditions et 4 niveaux de groupes.

## Choisir la valeur affichée

En tête de la section **Données**, un bloc indique ce que le widget affiche. Il dépend de la visualisation.

**Chiffre clé, anneau, matrice, graphe réseau : Valeur affichée.** Saisissez une expression : par défaut `a`, la première requête. Cliquez sur les puces de requêtes pour les insérer, par exemple `a - b`. Le bloc résume « Affiché : … ».

**Ratio : Part et total.** Le widget affiche part / total en pourcentage.

- **Part** : la requête comptée, avec ses **Filtres de la part** (« Part qui… »).
- **Total** : par défaut, la même source sans les filtres de la part (« a sans les filtres de la part »). Vous pouvez aussi choisir une autre requête, une formule ou **Nouvelle source…**.

Exemple : part des fournisseurs critiques dont l’évaluation est à jour, sur l’ensemble des fournisseurs critiques.

**Courbe, barres, liste : Séries affichées.** Chaque requête visible est une série. **Combiner les séries** remplace les séries par une **Expression combinée** (par défaut `pct(a, b)`). **Afficher les séries séparément** revient aux séries. Une courbe ou des barres affichent au plus 12 séries.

## Combiner par des formules

Le bouton **Formule** ajoute une valeur intermédiaire nommée, par exemple `d = max(a, b)`. La valeur affichée et les formules suivantes peuvent la réutiliser.

- Opérateurs : `+`, `-`, `*`, `/` et parenthèses.
- Le bouton **?** affiche les **Fonctions disponibles**. Pendant la saisie, les suggestions se parcourent avec ↑ ↓ ; **Entrée** ou **Tab** insère, **Échap** ferme.
- Une formule ne lit que les requêtes et les formules déclarées avant elle.
- Un widget compte au plus 4 formules, de 200 caractères et 8 niveaux d’imbrication maximum.

| Fonction | Résultat |
|---|---|
| `abs(x)` | Valeur absolue. |
| `round(x, digits)` | Arrondi, à `digits` décimales (0 par défaut). |
| `floor(x)`, `ceil(x)` | Arrondi à l’entier inférieur ou supérieur. |
| `sqrt(x)` | Racine carrée (vide si négatif). |
| `pow(x, n)` | x à la puissance n. |
| `min(…)`, `max(…)` | Plus petite ou plus grande des valeurs. |
| `sum(…)`, `avg(…)` | Somme ou moyenne, les vides ignorés. |
| `clamp(x, low, high)` | Borne x entre low et high. |
| `coalesce(…)` | Première valeur non vide (valeur de repli). |
| `pct(part, whole)` | Pourcentage : part / whole × 100. |

Exemples :

- `pct(a, b)` : part de **a** dans **b**, en pourcentage.
- `a - b` : écart entre deux requêtes, par exemple les risques ouverts moins les risques traités.
- `coalesce(a, 0)` : affiche 0 plutôt qu’une valeur vide.

Les séries sont alignées par période et les répartitions par catégorie. Une division par zéro ou une valeur manquante donne une valeur vide, sauf pour `coalesce`, `min`, `max`, `sum` et `avg`, qui ignorent les vides.

Supprimer une requête utilisée par une formule affiche un avertissement : corrigez la formule concernée.

## Fixer un objectif et des seuils

Pour un chiffre clé ou un ratio, la section **Affichage** propose **Objectif et seuils** :

- **Objectif** (ou **Objectif (%)**) : affiché à côté de la valeur ; une fois atteint, la valeur passe au vert.
- **Seuil atteint** et **Seuil d’alerte** : vert au-delà du seuil atteint, orange au-delà du seuil d’alerte, rouge sinon. Si le seuil atteint est inférieur au seuil d’alerte, une valeur basse est meilleure.
- **Suivre l’historique** : enregistre la valeur chaque jour. La courbe démarre à l’activation : rien n’est reconstitué.

Pour un ratio, **Affichage** permet aussi de choisir **Barre** ou **Anneau**.

Une fois l’historique activé, **Afficher l’évolution** dans le menu du widget ajoute une courbe de la valeur enregistrée. Seul son titre se modifie ; la requête se change sur le widget d’origine.

## Résultat attendu

Le widget affiche la valeur, le pourcentage ou les séries voulus, l’aperçu correspond au résultat, et le tableau est enregistré.

## Difficultés courantes

- **Appliquer** reste grisé : lisez les messages en bas du panneau, par exemple « Ajoutez une requête ou rendez-en une visible. » ou « 6 requêtes maximum. »
- « Les sorties n’ont pas la même forme : alignez les regroupements des requêtes. » : les requêtes combinées doivent utiliser le même regroupement.
- « La requête a est séparée par un second champ : retirez-le pour l’utiliser dans une formule. » : retirez **Séparer par** de cette requête.
- « La requête a renvoie une liste ou un graphe : elle ne peut pas être utilisée dans une formule. » : une liste ou un graphe ne se combine pas.
- « Aucune requête ni formule ne s’appelle d » : déclarez la formule **d** avant celle qui l’utilise, ou corrigez le nom.
- **Suivre l’historique** absent : l’historique ne s’applique qu’à une seule requête de données, sans formule, et sans les valeurs **Moi** ou **Mes équipes**.
- Valeur différente d’un autre widget : la période du tableau de bord peut s’imposer au widget (« Période imposée par le tableau de bord »). Une requête en échec est signalée par « Requêtes en erreur : … ».

Voir aussi [Lire et composer les tableaux de bord](https://docs.cisapp.eu/pilotage/tableau-bord) et [Langage de requête](https://docs.cisapp.eu/pilotage/langage-requete).