Liaison des paramètres
Chaque requête SQL et chaque endpoint HTTP reçoit ses valeurs via un modèle de paramètres cohérent : l'éditeur de connecteur déclare les paramètres ; la page qui consomme le connecteur (un écran, un graphique, un tableau de bord) les affiche comme saisies de formulaire ; le framework résout chaque saisie via une petite chaîne de fall-backs avant d'exécuter la requête.
Cette page couvre comment les paramètres apparaissent dans l'interface sur chaque surface, d'où viennent les valeurs par défaut, comment les filtres en cascade rétrécissent une liste déroulante en fonction d'une autre, et le contexte spécial session que chaque requête obtient gratuitement.
Vue d'ensemble
Déclarer un paramètre
Dans Paramètres → Connecteurs, ouvrir un connecteur et passer sur l'onglet Paramètres. L'onglet est une table — une ligne par paramètre — avec les champs de l'éditeur en dessous.
| Champ de l'éditeur | Description |
|---|---|
| Nom | Identifiant du paramètre. Apparaît comme nom de placeholder dans la requête (:name) et comme libellé de repli de la saisie de formulaire. |
| Type | string / int / float / bool / date / datetime / decimal. Pilote le type de widget sur les écrans (saisie texte vs sélecteur de date vs case à cocher) et la coercion avant l'exécution de la requête. |
| Libellé | Libellé affiché de la saisie sur la page consommatrice. Se rabat sur Nom quand vide. Localisé via le dictionnaire. |
| Obligatoire | Quand activé, la page consommatrice doit fournir une valeur sinon la requête échoue avec 400 Bad Request. Quand Obligatoire est désactivé, Défaut prend le relais à l'omission. |
| Défaut | Valeur appliquée quand l'appelant omet le paramètre. Voir Valeurs par défaut. |
| Lookup | Liste déroulante de lookups du dictionnaire. Quand défini, la saisie de formulaire devient une liste déroulante de paires { value, label } issues du lookup. |
| Multiple | Quand activé, la saisie accepte une liste ; la requête reçoit une clause IN (...). |
| Filter from | Multi-sélection d'autres paramètres dont celui-ci dépend en cascade — voir Filtres en cascade. |
Les paramètres qui apparaissent dans la requête (:name) mais ne sont pas déclarés sont quand même fournis par l'appelant — ils n'ont juste pas de widget ni de valeur par défaut. Utile quand la valeur est toujours définie par un autre mécanisme (une valeur fixe d'un graphique, les params d'un job).
L'onglet Paramètres de l'éditeur de connecteur valide chaque ligne en temps réel — une combinaison invalide (par exemple Obligatoire activé sans Défaut et sans Lookup) est signalée avant l'enregistrement.
Où les paramètres apparaissent
Un paramètre apparaît sur chaque page qui consomme le connecteur :
Écrans
La barre d'outils d'un écran affiche une saisie par paramètre déclaré. Le widget dépend de Type et Lookup :
| Type / lookup | Widget |
|---|---|
string | Saisie texte |
int / float / decimal | Saisie numérique |
bool | Case à cocher |
date / datetime | Sélecteur date / datetime |
| Tout type avec Lookup défini | Liste déroulante alimentée par le lookup |
string + Multiple activé | Multi-sélection |
Le bouton Appliquer / Exécuter de la barre relance la requête de lecture avec les valeurs courantes. Le framework applique un debounce sur les saisies texte (~300 ms) pour que la frappe ne sollicite pas la base à chaque caractère.
Graphiques
Chaque entrée de graphique dispose d'un panneau Paramètres fixes dans son éditeur. Les opérateurs règlent la valeur une fois ; le graphique tourne toujours contre ces valeurs. Utile pour des graphiques « Q1 uniquement » ou « app billing uniquement ». Les jetons de style ${month.first} sont acceptés ici pour que le graphique suive le calendrier.
Tableaux de bord
Les tableaux de bord ajoutent une étape : la Barre de filtres partagée du tableau de bord (en haut de la disposition) peut exposer un paramètre une fois, et chaque graphique qui référence le même nom de paramètre hérite de la valeur. Les opérateurs voient un seul filtre en haut du tableau de bord, pas un par panneau.
Jobs
La table Paramètres d'une étape de job a la même structure que la déclaration du connecteur — une ligne par paramètre, nom en lecture seule, valeur modifiable. Les substitutions comme ${params.period} se chaînent entre étapes.
Valeurs par défaut
Trois formes de Défaut sont acceptées dans l'éditeur de connecteur :
| Forme | Résolution |
|---|---|
Littéral — open, 5, true | La valeur littérale. |
Jeton de date — ${today}, ${yesterday}, ${week.monday}, ${week.sunday}, ${month.first}, ${month.last}, ${month.previous} | La date correspondante dans le fuseau du serveur, ré-évaluée à chaque appel. La valeur par défaut suit donc le calendrier. |
Valeur de session — ${session.user}, ${session.lang}, ${session.roles} | L'identité, la langue, les rôles de l'utilisateur appelant. Documenté ci-dessous. |
Un paramètre Obligatoire sans Défaut et sans valeur fournie par l'appelant fait échouer l'appel avec 400 Bad Request: missing required parameter.
Contexte de session
Trois valeurs sont toujours disponibles pour chaque requête, même non déclarées :
| Variable | Source |
|---|---|
session.user | Le claim sub du JWT — généralement le nom d'utilisateur local ou l'email OIDC. |
session.lang | La langue active (en-tête X-Liberty-Lang, avec repli sur la préférence de l'utilisateur). |
session.roles | La liste des rôles de l'appelant. |
Utiles pour les filtres au niveau ligne qui ne doivent jamais venir de l'utilisateur. Dans le champ Requête de l'éditeur de connecteur, écrire la requête comme :
SELECT * FROM contracts WHERE owner = :session_user;
Le framework réécrit session.user en placeholder :session_user à l'analyse (SQLAlchemy n'accepte pas les points dans les noms de placeholder).
Filtres en cascade
Motif courant : un écran a une liste déroulante Société et une liste déroulante Contrat — les contrats doivent se restreindre en fonction de la société. Dans l'onglet Paramètres de l'éditeur de connecteur, mettre le champ Filter from du paramètre Contrat à company :
| Mise en place |
|---|
Les deux paramètres définissent Lookup — le lookup company tire les sociétés, le lookup contract tire les contrats. |
Contrat met Filter from = [company]. |
La requête de lookup pour Contrat référence :company dans sa clause WHERE (typiquement avec IS NULL OR pour gérer le cas « aucune société choisie »). |
Quand l'opérateur choisit une société, le framework vide la sélection Contrat et re-récupère la liste déroulante avec la nouvelle société. Plusieurs dépendances sont prises en charge — Filter from = [company, region].
La cascade se configure entièrement depuis le dictionnaire (définitions de lookups) et l'éditeur de connecteur ; aucun SQL n'est écrit depuis l'écran consommateur.
Valeurs multiples
Un paramètre avec Multiple activé accepte une liste de valeurs et la lie comme IN (:name) dans la requête. Le widget devient une multi-sélection.
Dans le champ de requête, écrire WHERE status IN (:statuses) — le framework étend le placeholder en coulisses ; l'opérateur tape simplement IN (:statuses). Une liste vide est rejetée (le SQL IN () est illégal sur la plupart des bases) ; associer Multiple à Obligatoire : Off + une valeur par défaut raisonnable pour gérer le cas vide.
À l'exécution
Pour un écran du connecteur tasks sans valeur réglée dans la barre d'outils, le framework construit la map de paramètres résolue au moment de la requête :
status = "open" (défaut)
from_date = 2026-05-01 (jeton de date étendu)
to_date = 2026-05-31 (jeton de date étendu)
session.user = "alice" (session)
session.lang = "en" (session)
session.roles = ["viewer", "editor"] (session)
…et exécute la requête avec. Le panneau réseau des outils de dev du navigateur affiche la requête ; le logger de debug du framework (avec LIBERTY_LOG_LEVEL=DEBUG) imprime la map de paramètres résolue à côté du SQL.
Permissions
Une requête hérite du code de permission du connecteur (sql:<connector>:<query>, api:<connector>:<endpoint>). Le framework refuse tout appel à une requête que l'appelant ne peut pas exécuter ; la page consommatrice (écran / graphique / tableau de bord) élague aussi la surface pour que l'opérateur ne voie pas un widget inutilisable. Voir Rôles et permissions.
Sous le capot
Les déclarations de paramètres vivent sur l'entrée du connecteur à l'intérieur de connectors.toml. Les opérateurs n'éditent pas ce fichier à la main ; l'éditeur de connecteur est l'interface canonique. Les opérateurs avancés peuvent utiliser l'onglet Raw TOML comme issue de secours quand une limite de l'éditeur les bloque.
Pour aller plus loin
- Concepts → Connecteurs — la définition de connecteur qui porte les requêtes.
- Concepts → Dictionnaire — les définitions de lookups référencées par le champ Lookup.
- Concepts → Conditions de formulaire — règles conditionnelles
visible_when/required_whensur les écrans.