Connecteurs
Un connecteur est le moyen par lequel Liberty Next atteint une source de données. Chaque écran, graphique, tableau de bord, action, étape de tâche et réponse de l'assistant désigne le connecteur et la requête — ou l'endpoint — qu'il utilise.
| Type | Atteint | Contient |
|---|---|---|
| SQL | Une base de données, par un pool. | Des requêtes nommées, de quatre types : tables, requêtes, séquences, lookups. |
| API | Une API web (REST, JSON). | Des endpoints nommés : méthode, chemin, en-têtes, corps, extraction de la réponse. |
Un connecteur doté d'un menu est une application — voir Applications.
Vue d'ensemble
Liberty Next → Construire → Connecteurs
La liste de gauche a deux groupes : Applications (connecteurs dotés d'un menu) et Sources de données (les autres). + Connecteur en crée un (nom, type SQL ou API) ; le volet de droite modifie le connecteur sélectionné. Enregistrer écrit connectors.toml et applique la modification sans redémarrage ; Abandonner annule les modifications en attente. Les boutons propres au connecteur — Cloner (avec sa portée du dictionnaire, ses écrans, son menu, ses graphiques et tableaux de bord), Renommer (toutes les références réécrites), Supprimer (avec tout ce qui lui appartient) — se trouvent sur sa vue de réglages.
Pools
Un pool est une connexion à une base de données, définie dans Liberty Next → Administrer → Pools et partagée par les connecteurs qui l'utilisent :
| Champ | Effet |
|---|---|
| Url | L'URL de connexion (postgresql+asyncpg://user@hôte:5432/base, oracle+oracledb://user@hôte:1521/?service_name=…). Choisir d'abord un Dialect remplit un modèle. ${VARIABLE} accepté. |
| Password | Tenu hors de l'URL ; chiffré à l'enregistrement. |
| Dialect | postgresql, oracle, sqlite, mysql, mssql… — déduit de l'URL s'il est vide ; choisit la variante par dialecte d'une requête. |
| Schemas, DB Links | Les valeurs des jetons #SCHEMA.<NOM># et #DBLINK.<NOM># — voir plus bas. |
| Pool size, Max overflow, Pool pre ping, Pool recycle | Connexions gardées ouvertes, connexions supplémentaires sous charge, contrôle de validité, recyclage. |
| Max rows | Limite de lignes par défaut des lectures du pool (1 000 si vide). |
| Arraysize | Oracle : lignes lues par aller-retour ; à relever (500 à 1 000) pour les gros volumes. |
| Trim strings | Retire les espaces de fin des textes de longueur fixe (Oracle CHAR, JD Edwards). |
| Coalesce nulls | À l'écriture, remplace les valeurs vides par un espace ou 0 (colonnes texte Oracle NOT NULL). |
| Debug sql | Journalise chaque instruction exécutée sur le pool. |
Connecteur SQL
La barre de modes d'un connecteur SQL propose cinq vues : Paramètres…, Tables, Requêtes, Séquences, Lookups. Les quatre vues de requêtes sont décrites dans Requêtes — vue d'ensemble.
Réglages
Le mode Settings d'un connecteur SQL (le bouton Settings de la page du connecteur) regroupe ses réglages de connexion.
| Champ | Effet |
|---|---|
| Pool | Le pool sur lequel s'exécutent les requêtes — une liste des pools définis dans Liberty Next → Administrer → Pools. Le connecteur reprend l'adresse, les identifiants et le dialecte du pool. |
| Pools | Les pools supplémentaires sur lesquels les mêmes requêtes peuvent s'exécuter — voir Connecteurs multi-pools. |
| Show In Switcher | Affiche le connecteur comme une application dans le sélecteur en haut du menu latéral — avec un menu, voir Faire d'un connecteur une application. |
| Home | L'entrée de menu ouverte quand l'application est choisie. |
| Max Rows | Nombre maximal de lignes d'une lecture par défaut ; sinon celui du pool, puis 1 000. La limite d'un écran ou d'une requête l'emporte. |
| Dd Prefix | Longueur du préfixe de table dans les noms de colonnes (JD Edwards : 2, pour que ABCO, MCCO et SDCO portent tous l'élément CO). Utilisé par le périmètre de données des rôles. 0 : les noms de colonnes sont les éléments. |
Éditeur de requête
+ Ajouter une requête, ou un clic sur une requête existante, ouvre l'éditeur de requête :
| Champ | Effet |
|---|---|
| Name | Identifiant de la requête — utilisé dans l'URL (/api/sql/billing/<nom>) et dans la permission (sql:billing:<nom>). |
| SQL | L'instruction, avec ses paramètres :nom et ses valeurs serveur {{JETON}}. Un texte unique, ou une variante par base de données — voir Variantes SQL par dialecte. |
| Writable | Désactivé : seul un SELECT est accepté. Activé : INSERT / UPDATE / DELETE / CALL / MERGE. |
| Params | Les paramètres déclarés (nom, libellé, valeur par défaut) — voir Liaison de paramètres. |
| Label, Description (Advanced) | Affichés dans les listes de choix, et lus par l'assistant IA pour choisir ses requêtes. |
L'éditeur SQL colore la syntaxe, complète les noms de tables et de colonnes à partir du pool, et propose un menu Token ({{LOGIN}}, {{SYSDATE}}…) et un menu Pool schemas. Les boutons de l'éditeur — Find usages, Renommer, Changer le type, Déplacer, Cloner, Supprimer — sont décrits dans Créer une requête personnalisée.
Jetons de schéma et de DB link
Une requête SQL peut porter deux jetons de substitution : le même texte tourne alors sur n'importe quel pool — local ou distant — sans qu'il faille maintenir une variante de la requête par environnement.
| Jeton | Résout en | Où le configurer |
|---|---|---|
#SCHEMA.<NOM># | Le mappage du pool pour le schéma <NOM> (par ex. SY920.). Vide quand le pool n'a pas d'entrée — le jeton disparaît et le nom de table est écrit brut. | Paramètres du pool — la table Schemas de chaque pool. |
#DBLINK.<NOM># | Le suffixe de DB link du pool pour le schéma <NOM> (par ex. @ORCLPROD). Ajouté après le nom de table : #SCHEMA.SY#F0092#DBLINK.SY# devient donc SY920.F0092@ORCLPROD. Vide quand il n'y a pas d'entrée — rien n'est ajouté et la requête reste locale. | Paramètres du pool — la table DB links de chaque pool (dblinks = { SY = "@ORCLPROD", … }). |
Les deux jetons sont indépendants : #SCHEMA.…# préfixe la table, #DBLINK.…# la suffixe. Une même requête tourne en local (les deux mappages vides), sur un schéma distant sans lien (schéma mappé, dblink vide), ou via un DB link (les deux mappés) — c'est le pool qui décide quelle forme émettre.
Une valeur de DB link non vide doit être une référence @lien nue (commence par @, puis uniquement lettres, chiffres, _, $, # et .). Toute autre valeur fait échouer la requête à son exécution — garde-fou contre une valeur qui tenterait d'introduire du SQL dans l'instruction.
Mode thick d'Oracle
Le pilote Oracle fonctionne par défaut en mode thin : aucun client Oracle nécessaire, chaque appel s'exécute dans la boucle d'événements du serveur. Deux cas demandent le mode thick, qui passe par l'Oracle Instant Client :
- le chiffrement réseau natif (NNE) exigé par la base — le mode thin échoue avec
DPY-3001; - la lecture d'un LOB au travers d'un DB link — le mode thin échoue avec
ORA-22992/ORA-03149.
Cocher Oracle thick mode dans Liberty Next → Administrer → App (section App) et redémarrer le serveur : tous les pools Oracle passent alors en mode thick — le réglage vaut pour tout le serveur, pas pour un pool. Les pools PostgreSQL ne sont pas concernés. L'Instant Client est inclus dans l'image Docker (amd64 et arm64) ; une installation Python en a besoin sur l'hôte.
Connecteurs multi-pools
Un même connecteur SQL peut desservir plusieurs pools — plusieurs bases ou instances JDE — sans cloner le connecteur ni dupliquer ses écrans. À côté du Pool par défaut, listez les autres dans Pools (deux listes déroulantes de pools configurés, dans le mode Settings du connecteur) ; les mêmes requêtes nommées et les mêmes écrans s'exécutent alors sur n'importe quel pool de l'ensemble.
Le pool se choisit à l'exécution :
- Dans l'application — quand l'application courante passe par un connecteur multi-pools, un choix Pool apparaît dans le menu latéral, sous le sélecteur d'applications (Default désigne le pool propre du connecteur). Choisir un pool relance les écrans de l'application sur l'instance retenue. Le choix est conservé par application dans le navigateur, et ne s'applique qu'aux connecteurs qui déclarent réellement ce pool — les autres connecteurs (mono-pool) de l'application gardent leur pool par défaut au lieu d'échouer.
- Dans les tâches — une étape
sql_copyacceptepooldans son blocsourceoutarget, une étapesql_queryacceptepool, pour cibler une instance précise sans nouveau connecteur (étapes). Ces clés se définissent dansjobs.toml; l'éditeur d'étape ne les affiche pas.
L'ensemble atteignable est le pool par défaut plus pools ; une requête ou une tâche ne peut jamais atteindre un pool en dehors, et seuls les noms de pool arrivent au sélecteur — jamais d'URL ni d'identifiants. Un connecteur avec un seul pool se comporte exactement comme avant.
Un connecteur API appelé depuis ces écrans — AIS, pour JD Edwards — peut suivre les mêmes environnements : voir Un serveur par environnement.
Connecteur API
Un connecteur API appelle une API web. Son éditeur comporte six onglets :
| Onglet | Contenu |
|---|---|
| Connection | Base URL (https://api.example.com, ${VARIABLE} accepté), Default headers, Timeout, Vérification SSL (true, false, ou une variable comme ${JDE_AIS_VERIFY_SSL:-true}, conservée telle quelle), Show in switcher, Home. |
| Authentication | Auth type : None, Basic (utilisateur et mot de passe), Bearer (jeton fixe), API Key (nom de l'en-tête et clé), OAuth2 / JWT (endpoint de jeton, corps et en-têtes de la demande, champ du jeton, durée de vie). Les secrets sont chiffrés à l'enregistrement. |
| Environnements | Un serveur par environnement, pour un connecteur utilisé avec plusieurs environnements JDE — voir Un serveur par environnement. |
| Endpoints | Les endpoints nommés — voir ci-dessous. |
| Webhooks | Pas encore disponible : un système externe ne peut pas pousser d'événements vers Liberty Next. |
| Test | Tester la connexion vérifie l'authentification ; Run appelle un endpoint avec des valeurs de paramètres et affiche la réponse. Rien n'est enregistré. |
Un endpoint comporte :
| Champ | Effet |
|---|---|
| Name | Utilisé dans l'URL (/api/http/<connecteur>/<nom>) et dans la permission (api:<connecteur>:<nom>). |
| Method, URL path | GET, POST, PUT, PATCH, DELETE… ; le chemin s'ajoute à l'URL de base (une URL absolue la remplace). |
| Headers, Query params | Ajoutés à ceux du connecteur ; les valeurs acceptent des {{variables}}. |
| Body template, Body Content-Type | Le corps de la requête, avec des {{variables}}. |
| Response field, Response mappings | Un chemin dans la réponse JSON (data.0.id), ou plusieurs chemins nommés ; vide, la réponse entière est renvoyée. |
| Parameters | Les {{variables}} déclarées, avec libellé et valeur par défaut. |
| Label, Description | Affichés dans les listes de choix et à l'assistant IA. |
Les endpoints sont appelés par les actions d'écran (call_api), les entrées de menu (type endpoint), les règles de notification (canal action), les plugins (connectors.api(…).call(…)) et — s'il y est autorisé — l'assistant IA. Une étape Nomaflow http appelle directement une URL, sans connecteur.
Un serveur par environnement
Quand les écrans s'appuient sur un connecteur multi-pools — plusieurs environnements JD Edwards — chaque environnement a en général son propre serveur AIS. L'onglet Environnements donne au connecteur API un serveur par environnement ; les endpoints restent définis une seule fois.
| Champ | Effet |
|---|---|
| Environnement (pool) | L'environnement (pool) du serveur du connecteur — sa Base URL et ses identifiants. Obligatoire dès qu'il y a un autre environnement. |
| Autres environnements | Une entrée par autre pool : Base URL, Username, Password, Token, Vérification SSL. Un champ vide reprend la valeur du connecteur. Mots de passe et jetons sont chiffrés à l'enregistrement. |
Personne ne choisit le serveur. Un appel suit l'environnement de l'écran — le Pool choisi dans la barre latérale, ou celui par défaut — et le pool d'une étape de tâche (tout type d'étape). Cela couvre les actions d'écran (call_api), les plugins, /api/http et l'assistant IA.
Un appel fait pour un des environnements du connecteur sans serveur est refusé (« no target for pool … ») ; il n'est jamais envoyé au serveur du connecteur, qui est un autre environnement — souvent la production. Les environnements sont le pool du connecteur plus tous les pools des connecteurs SQL qui s'appuient dessus : un environnement JDE ajouté côté SQL et oublié ici est refusé lui aussi. L'onglet liste ces environnements sans serveur, Paramètres → Intégrité aussi.
[connectors.ais_connection]
base_url = "${JDE_AIS_URL}"
pool = "jdedwards" # l'environnement de base_url
[connectors.ais_connection.targets.jdedwards_dev]
base_url = "https://ais-dev.example.com:7077/jderest/v2"
auth_password = "ENC:…" # seulement ce qui diffère
Pour nommer l'environnement avant un appel sensible, utilisez #POOL# dans le message d'un confirm : Reset the password of {INPUT.user} on #POOL#?. Une mise à jour des applications sous licence conserve le pool et les targets d'une installation.
Découverte de schéma et indices de colonnes
Une requête ne déclare pas de liste de colonnes : ses colonnes sont celles que renvoie la base à l'exécution. L'apparence d'une colonne sur un écran est déterminée, dans cet ordre, par :
- les réglages de colonne de l'écran (onglet Colonnes) — libellé, format, largeur, règle, conditions ;
- l'entrée du dictionnaire dont la clé est le nom de la colonne, ou celle indiquée dans le champ
ddde la colonne — libellé par langue, format, règle (booléen, énumération, lookup…) ; - à défaut, le nom de la colonne et l'affichage par défaut de son type.
Une colonne n'a pas besoin de réglage propre : une entrée du dictionnaire portant son nom suffit. Voir Dictionnaire et Écrans → Colonnes.
Permissions
Chaque requête et chaque endpoint a sa propre permission :
| Permission | Autorise |
|---|---|
sql:<connecteur>:<requête> | L'exécution de la requête — en lecture comme en écriture. |
api:<connecteur>:<endpoint> | L'appel de l'endpoint. |
Elles s'accordent par les rôles : autoriser une entrée de menu accorde ce qu'elle ouvre, et Au-delà des menus accorde une requête, un endpoint ou un connecteur entier — des motifs comme sql:billing:report_* sont acceptés. Voir Rôles et permissions.
Conseils
- Nommer les requêtes d'après l'entité —
invoices_get,invoices_by_status_get— les listes se lisent d'elles-mêmes. - Décrire les requêtes que doit utiliser l'assistant IA : libellé et description (onglet Advanced).
- Préférer le dictionnaire aux libellés par écran : une entrée sert tous les écrans.
- Tenir les secrets hors des fichiers par des références
${VARIABLE}quand un gestionnaire de secrets est en place — voir Chiffrement et secrets.
Sous le capot
Connecteurs et pools sont enregistrés dans connectors.toml, dans le dossier de configuration des applications. Les pages de Liberty Next sont le moyen normal de les modifier ; la même configuration est accessible par l'API REST sous /admin/config/connectors — voir API REST.
Pour aller plus loin
- Requêtes — vue d'ensemble — les quatre types de requêtes et leurs éditeurs.
- Dictionnaire — libellés, formats et listes de valeurs des colonnes.
- Liaison de paramètres — paramètres, sources intégrées et jetons.
- Écrans — grilles et dialogues sur les requêtes.