Widgets

À quoi ça sert

Un widget est un graphique de l'organisation : chiffre d'affaires, nombre de tâches ouvertes, activité commerciale… Ces graphiques forment le catalogue « Widgets » dans lequel vous puisez pour composer un tableau composé. Un même widget peut se retrouver sur plusieurs tableaux composés, les vôtres comme ceux qu'on partage avec vous.

Chaque widget interroge directement les données de votre organisation.

Concepts clés

Widget ou graphique — un graphique du catalogue, identifié par un titre et un résumé.
Auteur — la personne qui a créé le graphique. Elle seule, avec un administrateur du module KPI, peut le modifier.
Partage d'un graphique — privé, restreint à des périmètres, ou ouvert à toute l'organisation. Indépendant du partage du tableau composé qui l'affiche : un graphique peut être plus restreint que le tableau sur lequel il est posé, auquel cas certains lecteurs du tableau voient une tuile restreinte à sa place.
Type de rendu — la façon dont le graphique s'affiche : tableau, barres, courbe, aire, camembert, nombre, jauge, entonnoir, et une dizaine d'autres.
Couleurs — les couleurs des séries d'un graphique. Elles appartiennent au graphique : les changer les change partout où il est posé.
Lien au clic — une destination de Deltia, ou une adresse web, vers laquelle un clic sur un élément du graphique renvoie, ses variables étant remplacées par les valeurs de la ligne cliquée. Laissé vide, le graphique n'est pas cliquable.
Format d'une colonne — comment se lit une colonne du résultat : nombre brut, pourcentage, montant dans une devise, avec préfixe ou suffixe.
Graphique personnel — un widget dont la requête compare l'adresse e-mail de qui le regarde à une donnée du résultat : chaque lecteur voit alors ses propres chiffres, jamais ceux d'un collègue. Demandez ce genre de graphique à l'assistant IA, par exemple « mes tâches » ou « mes factures », ou écrivez-le dans la requête (voir « Règles de la requête » en Référence).
Source des données — « Données Deltia » (le réglage par défaut, interrogé par une requête) ou « Source externe » (un jeu de données publié depuis une base ou une API de votre organisation). Voir Jeux de données des sources externes.
Jeu de données — une collection d'une source externe dont le mapping a été publié. C'est ce que vous choisissez pour un graphique sur « Source externe ».
Aperçu — le graphique tel qu'il s'affichera, à la taille réelle d'une tuile de tableau composé, à gauche du volet des réglages.
Version — chaque fois que la requête ou le rendu d'un widget change, depuis ses réglages ou via l'assistant IA, la version précédente est conservée plutôt que perdue. Un administrateur du module KPI peut la consulter et la restaurer. Voir Administration des tableaux composés et des widgets.

Comment faire

Voir Ajouter un graphique.

Deux façons d'ouvrir les réglages d'un graphique :

Sur un tableau composé, en mode d'édition, cliquez sur l'icône de réglages de sa tuile : le panneau « Tuile sélectionnée » s'ouvre à côté du tableau, avec les onglets « Données », « Style » et « Filtres » (voir Habiller un tableau composé).
Ou, dans le menu « Ajouter un widget » du panneau « Configuration » (liste « Widgets disponibles », voir Ajouter un graphique), cliquez sur le nom d'un graphique que vous pouvez modifier : ses réglages s'ouvrent directement, sans le poser sur le tableau.

Une fois les réglages ouverts, ajustez le titre, le résumé, la requête, le type de rendu, les options de la section « Rendu », les couleurs des séries, le lien au clic ou la section « Format des colonnes », puis cliquez sur « Enregistrer ». L'aperçu se met à jour à chaque sortie de champ de la requête. Dans le panneau d'une tuile, l'onglet « Données » regroupe le titre, le résumé, le partage et la requête, et l'onglet « Style » le reste ; sous « Style », choisissez si la modification vaut « Partout où il apparaît » ou seulement pour « Ce tableau ».

L'icône de réglages d'une tuile s'affiche sur tous les widgets de votre tableau, sauf un graphique désactivé par un administrateur. Dans le panneau « Widgets disponibles », seul le nom d'un graphique que vous pouvez modifier est cliquable. Dans les deux cas, vous ne pouvez enregistrer une modification que sur un graphique dont vous êtes l'auteur ; un administrateur du module KPI peut modifier n'importe lequel. Sur un graphique d'un autre auteur, la section « Partage » reste masquée et l'enregistrement est refusé.

Comparer une évolution

Les réglages « Comparer à », « Afficher la variation en », « Libellé de la période » et « Couleurs par seuil » sont décrits dans Comparer une évolution.

Colorer un entonnoir

Disponible sur le type « Entonnoir ». Par défaut, les étapes forment un dégradé d'une seule teinte, celle de l'organisation.

Dans les réglages ouverts, sous « Rendu », choisissez la « Couleur de base du dégradé » : tout le dégradé part de cette teinte. « Couleur principale » revient à la teinte de l'organisation.
Ou, sous « Couleurs », choisissez une couleur par étape.
Cliquez sur « Enregistrer ».

Les deux manières ne se cumulent pas : choisir une couleur de base remet toutes les étapes sur le dégradé, et les couleurs choisies une à une sont perdues.

Lire une source de données externe

Dans les réglages ouverts, sous « Source des données », cliquez sur « Source externe ».
Choisissez un « Jeu de données ».
Ajoutez une ou plusieurs « Mesures » : une mesure du mapping, ou une agrégation libre (Nombre, Nombre de valeurs distinctes, Somme, Moyenne, Minimum, Maximum) sur un champ.
Ajoutez au besoin des « Répartitions » pour ventiler le résultat par un champ, sur l'axe ou en séries, avec un « Top N » si besoin.
Pour un axe temporel, choisissez le champ de date et sa granularité (heure, jour, semaine, mois, trimestre, année).
Ajoutez des « Filtres » si besoin.
Cliquez sur « Enregistrer ».

« Source externe » ne s'affiche que si votre organisation a au moins un jeu de données publié ; « Aucune collection publiée. Un administrateur doit en adopter une et publier son mapping depuis l'administration KPI. » s'affiche sinon. Contrairement à « Données Deltia », vous ne saisissez pas de requête : vous composez le graphique à partir des champs exposés du mapping. Un champ situé dans un tableau affiche « Ce champ est dans un tableau : la requête produira une ligne par élément, pas par document. ».

Sur sa tuile, un graphique externe affiche un repère de fraîcheur : « Lu à l'instant sur la source externe. », ou « Résultat mis en cache : cliquez pour relire la source externe. ». Pendant la relecture, le repère tourne et ne peut plus être cliqué. « Les définitions de ce jeu de données ont été republiées depuis la création de ce graphique. » signale que le mapping a changé ; « Le résultat a été tronqué : la source renvoie plus de lignes que la limite du graphique. » signale un résultat coupé. Un graphique externe ne peut pas pointer vers une liste de Deltia au clic : seul un lien vers une adresse web est possible. Voir Jeux de données des sources externes pour adopter une collection et publier un mapping.

Combiner plusieurs requêtes dans un graphique

Dans les réglages ouverts, sous « Requêtes », choisissez « Plusieurs requêtes combinées ».
Cliquez sur « Ajouter une requête » pour chacune des requêtes à combiner (au maximum cinq), chacune sur « Données Deltia » ou « Source externe », et donnez à chacune un « Nom de la requête ».
Dans « Fonction d'agrégation (JavaScript) », écrivez une fonction qui combine les requêtes nommées et retourne { columns, rows }.
Cliquez sur « Enregistrer ».

Chaque requête est disponible dans la fonction sous son nom, comme une liste de lignes ; seuls Math, JSON et Date sont disponibles. Une requête combinée n'a pas de lien au clic dérivé d'une colonne ; un lien écrit à la main reste possible.

Vérifier l'aperçu

Dans les réglages ouverts, regardez l'aperçu à gauche du volet.
Sous « Taille sur un tableau de bord », choisissez « Petite tuile », « Tuile moyenne » ou « Grande tuile » (moyenne par défaut).

Tant que la requête ne renvoie aucune donnée, l'aperçu affiche « L'aperçu s'affichera ici dès que la requête renverra des données. ». Une requête refusée affiche son erreur. Sur un tableau composé, l'aperçu se dessine sur le tableau, à la taille réelle de la tuile.

Ouvrir les réglages en pleine page

Dans le volet des réglages d'un widget existant, cliquez sur le bouton d'agrandissement.

Les réglages s'ouvrent sur une page dédiée, avec les modifications en cours conservées. Quitter cette page alors que des modifications ne sont pas enregistrées demande une confirmation. Supprimer le widget depuis la pleine page ramène à l'accueil du module KPI.

Ouvrez les réglages du widget.
Cliquez sur « Supprimer ».
Confirmez : « {titre} sera retiré de tous les tableaux de bord qui l'utilisent. Cette action est définitive. »

Le widget disparaît de tous les tableaux composés où il était posé, y compris ceux d'autres propriétaires, et du catalogue. La suppression est réservée à l'auteur du widget ou à un administrateur du module KPI, et elle est irréversible — à la différence de la désactivation, qui reste réversible et n'efface rien. Voir Administration des tableaux composés et des widgets.

Ouvrez les réglages du widget.
Dans « Partage », choisissez « Privé », « Périmètres choisis » (uniquement parmi vos propres périmètres) ou « Toute l'organisation ».
Cliquez sur « Enregistrer ».

Un partage plus étroit que celui d'un tableau composé sur lequel le graphique est posé rend sa tuile restreinte pour les lecteurs qui n'y ont plus droit.

Un périmètre déjà bénéficiaire du partage mais que vous ne pouvez plus cocher (vous n'en êtes plus membre, par exemple) reste listé et coché : vous pouvez le décocher pour le retirer, mais pas en ajouter d'autres hors de vos propres périmètres. Décocher le dernier périmètre restant est impossible tant que vous n'en avez pas coché un autre — ce qui viderait le partage sans le fermer ; passez plutôt sur « Privé » ou « Toute l'organisation ».

Référence

Affichage d'un graphique « Nombre »

Un graphique de type Nombre affiche son chiffre exact tant qu'il tient dans sa tuile. Quand il ne tient plus, il repasse en version compacte (« 1,2 M ») et le chiffre exact s'affiche au survol.

Types de rendu disponibles

Tableau, barres, courbe, aire, camembert, barres horizontales, nombre, nuage de points, combiné, cascade, entonnoir, treemap, progression, tendance, visualisation détaillée, jauge, Sankey, tableau croisé dynamique, comparaison, carte de chaleur, haltères, intervalles, cordes et réseau (ces cinq derniers sont décrits dans Graphiques avancés).

La liste propose tous les types. Ceux que les lignes de la requête peuvent représenter viennent en premier ; les autres suivent, marqués « peu adapté ». Le classement se fait sur les lignes de l'aperçu, ou sur celles du widget enregistré tant que sa requête n'a pas été modifiée. Rien n'est refusé ni remplacé d'office : le choix reste le vôtre.

Si le type choisi ne convient pas aux données, l'éditeur l'indique sous la liste. Quand le graphique s'affiche en tableau, le message est « Ce type de graphique ne correspond pas aux données : il est affiché en tableau. » ; sinon, après une modification de la requête ou pour un widget pas encore créé, c'est « Ce type de graphique ne correspond pas aux données : le rendu peut être vide ou faux. »

Le type « Comparaison » place côte à côte deux chiffres d'une même ligne (par exemple signé et facturé), chacun dans sa couleur, avec leur écart et le premier en pourcentage du second. Il n'est proposé que pour une requête qui renvoie une seule ligne de deux chiffres.

Options de la section « Rendu »

Seules les options du type choisi s'affichent. Les types tableau, nombre, treemap, progression, visualisation détaillée, jauge et Sankey n'ont pas de section « Rendu ».

Option	Types concernés
« Afficher la légende »	Barres, barres horizontales, aire, courbe, combiné, camembert
« Afficher les valeurs sur le graphique »	Barres, barres horizontales, aire, courbe, combiné, cascade
« Afficher le total »	Camembert, cascade
« Étiquettes des tranches » (« Aucune », « Valeurs », « Pourcentages », « Valeurs et pourcentages »), « Décimales des pourcentages », « Regrouper les tranches sous (%) »	Camembert
« Empilement » (« Côte à côte », « Empilé », « Empilé à 100 % »)	Barres, barres horizontales, aire
« Titre de l'axe des catégories », « Titre de l'axe des valeurs », « Graduations des catégories », « Graduations des valeurs », « Échelle » (« Linéaire », « Logarithmique »), « Minimum », « Maximum »	Barres, barres horizontales, aire, courbe, combiné, cascade, nuage de points
« Objectif », « Libellé de l'objectif »	Barres, barres horizontales, aire, courbe, combiné, cascade ; sur Nombre et Tendance, l'objectif s'affiche en barre de progression sous le chiffre (« {pourcentage} % de {objectif} », puis « Objectif atteint »)
« Courbe sous le chiffre »	Tendance
« Couleur de base du dégradé »	Entonnoir
« Total par ligne », « Total par colonne »	Tableau croisé dynamique
Réglages de comparaison : « Comparer à », « Afficher la variation en », « Libellé de la période », « Couleurs par seuil », « Une hausse est une mauvaise nouvelle »	Nombre, Tendance, Courbe, Aire, Barres (voir Comparer une évolution)

Format des colonnes

La section « Format des colonnes » n'apparaît qu'en modification d'un widget existant. Pour chaque colonne, elle propose :

Réglage	Effet
« Nom affiché »	Le nom de la colonne à l'écran
« Type »	« Nombre brut » (aucune mise en forme), « Nombre », « Pourcentage » ou « Montant »
« Décimales »	De 0 à 6
« Devise »	Code ISO 4217 de trois lettres, pour un montant (par exemple EUR) ; EUR par défaut
« Multiplier par », « Préfixe », « Suffixe »	S'ajoutent à n'importe quel type

Règles de la requête

La requête doit lire un jeu de données prévu pour les KPI (kpi_read) et porter les deux paramètres {{organization_id}} et {{group_ids}} : c'est ce qui la borne à votre organisation et à vos périmètres. Pour un graphique personnel, comparez {{current_user_email}} à une colonne contenant une adresse e-mail : il vaut l'adresse de qui regarde le graphique, qui reste donc partageable.

Le module Stocks ajoute trois jeux de données à ceux que la requête peut lire : stock_items (une ligne par article, avec ses seuils de réapprovisionnement), stock_levels (une ligne par article et par entrepôt qui détient du stock, avec la quantité et is_below_reorder_point) et stock_moves (une ligne par mouvement, signée : une sortie est négative, une entrée positive, datée par moved_at). Aucun de ces jeux ne contient de prix d'achat ni de valorisation. Les quantités sont dans l'unité de base de l'article.

Paramètres déclarés par la requête

Une requête peut déclarer ses propres paramètres, au-delà de {{organization_id}} et {{group_ids}}, pour recevoir une valeur d'un filtre de tableau composé qu'aucune colonne de la requête ne porte directement — un regroupement calculé, par exemple. Écrivez chaque condition sous la forme ({{paramètre}}::text IS NULL OR …), pour qu'une valeur non choisie ne filtre rien. Le filtre du tableau composé s'y rattache par le nom du paramètre, et ne peut alors porter qu'une seule valeur.

Catégories sans valeur

Sur un graphique groupé par un champ (barres, camembert, courbe…), les lignes dont ce champ est vide, non renseigné ou ne contient que des espaces sont regroupées dans une seule catégorie « Non renseigné », plutôt que d'apparaître chacune sous sa propre étiquette.

Limites

Limite	Valeur
Titre d'un widget	255 caractères maximum
Résumé d'un widget	1000 caractères maximum
Création ou réécriture de widgets	180 par heure et 600 par jour pour un même utilisateur, 1 800 par jour pour l'organisation entière

La limite de création ou réécriture compte une création aboutie par l'assistant IA, et une modification enregistrée seulement si elle change la requête ou le type de rendu. Un renommage, un changement de couleurs, d'options ou de format ne compte pas, pas plus qu'un graphique créé avec « Nouveau graphique » depuis l'administration.

Qui peut quoi

Action	Qui
Ajouter un widget existant à un tableau composé	Toute personne pouvant modifier ce tableau
Enregistrer une modification sur un widget	L'auteur du widget, ou un administrateur du module KPI
Créer un nouveau widget	Un administrateur du module KPI, ou l'assistant IA si votre organisation l'autorise
Désactiver un widget ou restaurer une version antérieure	Un administrateur du module KPI uniquement
Supprimer un widget	L'auteur du widget, ou un administrateur du module KPI

Messages

Message	Situation
« Votre organisation réserve la création de widgets KPI à certains rôles »	Vous ne détenez aucun des rôles autorisés à créer des widgets
« Seuls l'auteur du graphique et un administrateur du module KPI peuvent le modifier »	Vous tentez de modifier un widget dont vous n'êtes pas l'auteur
« Ce graphique a été retiré de la circulation par un administrateur : il ne peut plus être modifié. »	Le widget a été désactivé
« Vous ne pouvez partager un graphique qu’avec vos propres périmètres »	Le partage choisi désigne un périmètre auquel vous n'appartenez pas
« Choisissez au moins un groupe, ou partagez avec toute l’organisation »	Le partage « Périmètres choisis » a été enregistré sans aucun périmètre coché
« Vous avez atteint la limite de graphiques générés. Réessayez dans {retrySeconds} secondes. »	Vous avez atteint la limite de création ou réécriture de widgets
« La requête n'a ramené aucune donnée pour cette organisation : … »	La requête ne renvoie aucune donnée ; le widget n'est pas enregistré
« Le graphique a été modifié. Rafraîchissez la page et réessayez. »	Le widget a été modifié ailleurs pendant que vous l'éditiez
« Le lien de ce graphique n'est pas valide : la requête ne renvoie pas toutes les variables qu'il utilise, ou la colonne choisie ne correspond à aucun filtre de la liste ciblée. »	Le lien au clic cite une colonne absente du résultat, ou une colonne sans filtre correspondant sur la liste visée
« Le lien doit commencer par « / » (une page de Deltia) ou par « https:// ». »	Le lien au clic saisi ne pointe ni vers une page de Deltia, ni vers une adresse sécurisée
« Un graphique basé sur une source de données externe ne peut pas pointer vers une liste de l'application : écrivez plutôt la destination sous forme de lien. »	Le lien au clic d'un graphique sur « Source externe » cible une liste de Deltia
« La source de données est injoignable. Le dernier contrôle a échoué : corrigez la connexion depuis l'administration des connecteurs. »	La source externe lue par le graphique a échoué à son dernier test
« Le mapping de cette collection n'a pas été publié : ouvrez-le, vérifiez les champs et publiez-le. »	Le jeu de données lu par le graphique n'a plus de mapping publié

Questions fréquentes

Puis-je créer un widget moi-même ? Cela dépend des réglages de votre organisation : voir Administration des tableaux composés et des widgets. Vous pouvez demander un graphique à l'assistant IA, s'il est activé.

Pourquoi un graphique de mon tableau affiche-t-il un message à la place des données ? Le graphique n'est pas disponible pour votre compte, le plus souvent parce que son partage est plus restreint que celui du tableau. Un graphique désactivé par un administrateur, lui, disparaît du tableau pour ses lecteurs. Voir Tableaux composés.

Une modification de couleur affecte-t-elle les autres tableaux qui utilisent ce widget ? Oui, sauf si vous l'avez enregistrée pour « Ce tableau » seulement : les couleurs appartiennent au graphique et changent partout où il est posé.

Puis-je faire en sorte qu'un clic sur mon graphique ouvre une autre page de Deltia ? Oui, avec un lien au clic dans les réglages du widget : le clic ouvre, dans un nouvel onglet, la liste correspondante filtrée sur la valeur cliquée.

Puis-je afficher un widget ailleurs que sur un tableau composé ? Oui, un graphique que vous pouvez lire peut aussi apparaître seul sur la page d'accueil, comme widget « Carte KPI ». Voir Page d'accueil. Ses données se téléchargent depuis sa tuile : voir Télécharger un widget.

Puis-je créer un graphique sur une base de données de mon organisation ? Oui, si un administrateur des connecteurs a déclaré cette base ou cette API et qu'un administrateur du module KPI a publié le mapping d'une de ses collections : choisissez « Source externe ». Voir Jeux de données des sources externes.