Types d'étape
Dans l'éditeur de jobs, une étape s'ajoute en cliquant sur ➕ Ajouter étape dans la section Étapes. L'éditeur d'étape s'ouvre à droite avec un sélecteur Type ; choisir un type déploie le formulaire avec les champs propres à ce type. Cinq types sont pris en charge.
Cette page couvre chaque type avec le formulaire affiché, les validations exécutées et le résultat consigné.
Vue d'ensemble
liberty-apps/plugins/ — la sortie de secours.SQL Query
Exécuter une requête SQL nommée d'un connecteur. Les requêtes de lecture remontent leur nombre de lignes ; les requêtes d'écriture remontent le nombre de lignes affectées. La requête et ses paramètres vivent dans le catalogue de connecteurs — cette étape en choisit une et fournit les valeurs pour ce job.
| Champ du formulaire | Description |
|---|---|
| Connecteur | Liste déroulante de chaque connecteur SQL défini sur l'installation. Filtrée aux connecteurs que l'appelant peut exécuter (sql:<connector>:*). |
| Requête | Liste déroulante des requêtes déclarées sur le connecteur choisi. Les requêtes de lecture ont un badge read ; les requêtes d'écriture un badge write. |
| Paramètres | Une ligne par paramètre déclaré sur la requête. Chaque ligne est name (lecture seule) + value. Les valeurs prennent en charge les substitutions ${...} documentées dans Liaison des paramètres. |
| Mode de lecture | All (défaut) / First / None. None rejette les lignes et ne consigne que le nombre — utile pour les grandes lectures où seul le compte est nécessaire. |
| Alias de résultat | Nom sous lequel le résultat est exposé à l'étape suivante via ${steps.<alias>.…}. Défaut : le Nom de l'étape. |
L'étape consigne row_count (lecture), rows_affected (écriture), les 100 premières lignes du résultat et le temps écoulé. La page de détail d'exécution les déploie en ligne.
SQL Copy
Diffuser des lignes d'un connecteur source vers un pool cible, avec coercion de types optionnelle et bascule de table atomique. Le motif canonique pour ETL des bases opérationnelles vers les entrepôts de reporting.
| Champ du formulaire | Description |
|---|---|
| Connecteur source | Liste déroulante de connecteurs SQL. |
| Requête source | Liste déroulante des requêtes de lecture du connecteur. |
| Paramètres source | Identique à SQL Query. |
| Pool cible | Liste déroulante de pools (un pool, pas un connecteur — l'étape écrit directement). |
| Table cible | Texte libre — la table de staging où les lignes sont insérées. Créée depuis le schéma source si elle manque. |
| Table finale | Optionnelle. Nom de la table finale vers laquelle Table cible est renommée après la copie. Quand elle est définie, la copie est atomique (l'application voit l'ancienne table jusqu'à ce que le renommage les permute). Laisser vide pour ignorer la bascule et garder les lignes dans la table de staging. |
| Taille de bloc | Lignes par lot. Défaut 1000. |
| Coercion de types | Strict (défaut) / JDE / Truncate. Pilote la correspondance des types source vers cible. JDE convertit les colonnes décimales à zéro en entiers ; Truncate raccourcit les chaînes pour entrer dans une colonne cible plus étroite. |
| Vider la cible | Interrupteur. Quand activé, la table de staging est TRUNCATE avant la copie. Activé par défaut quand Table finale est définie, désactivé sinon. |
| Filtre Where | Clause WHERE optionnelle ajoutée à la requête source — utile pour les copies incrémentales. |
| Transform | Référence optionnelle à un callable Python dans liberty-apps/plugins/. La fonction reçoit chaque ligne comme un dict, retourne un dict (ou None pour écarter la ligne). |
L'étape consigne rows_read, rows_written, rows_dropped (par la transformation), chunks et le temps écoulé. Les incompatibilités de schéma (colonne manquante sur la cible) font échouer l'étape avec le nom de la colonne dans l'erreur.
Python
Appeler une fonction Python dans liberty-apps/plugins/. La sortie de secours pour tout ce que les types déclaratifs ne peuvent pas exprimer.
| Champ du formulaire | Description |
|---|---|
| Callable | Référence de la forme module.path:function. L'éditeur vérifie que la fonction s'importe proprement à l'enregistrement ; une fonction manquante fait échouer. |
| Arguments nommés | Une table de lignes name + value. Les valeurs sont passées en **kwargs au callable. Prend en charge les substitutions ${params.*} et ${steps.<name>.…}. |
Voir Apps et Plugins → Plugins pour la signature de la fonction, le contexte d'exécution que le framework injecte (connectors, pools, job_id, etc.) et les conventions d'empaquetage.
L'étape consigne le dict retourné par la fonction, le timing et toute trace d'exception quand la fonction lève.
HTTP
Appeler un endpoint HTTP / API — soit un endpoint nommé d'un connecteur HTTP existant, soit une URL brute — et consigner la réponse.
Le formulaire dispose d'un interrupteur au sommet : Utiliser un endpoint de connecteur / Utiliser une URL brute.
Variante A — endpoint de connecteur
| Champ du formulaire | Description |
|---|---|
| Connecteur | Liste déroulante de connecteurs HTTP / API. |
| Endpoint | Liste déroulante des endpoints nommés du connecteur choisi. |
| Paramètres | Une ligne par paramètre déclaré, name + value. |
| Statuts attendus | Multi-sélection des statuts HTTP acceptables. Défaut 200 201 202 204. Tout autre statut fait échouer l'étape. |
| Alias de résultat | Identique à SQL Query. |
Variante B — URL brute
| Champ du formulaire | Description |
|---|---|
| Méthode | GET / POST / PUT / DELETE / PATCH. |
| URL | URL complète. ${env.VAR} substitue depuis l'environnement du processus. |
| Body | Corps JSON optionnel (objet ou tableau). |
| En-têtes | Table name/value optionnelle. |
| Authentification | None / Basic / Bearer. Le formulaire Bearer prend un seul champ — câblé à l'interrupteur 🔒 de chiffrement de valeurs. |
Le corps de la réponse est consigné comme résultat de l'étape (tronqué à 100 KiB pour l'aperçu de la page de détail). À n'utiliser en URL brute que pour des appels ponctuels — les appels récurrents doivent être définis comme endpoint de connecteur pour vivre dans le catalogue.
LDAP Sync
Tirer un sous-arbre d'un annuaire LDAP et insérer ou mettre à jour les lignes résultantes dans un connecteur. Remplace les scripts LDAP ad hoc que la plupart des installations finissent par écrire.
| Champ du formulaire | Description |
|---|---|
| Pool LDAP | Liste déroulante de pools LDAP (séparés des pools SQL — définis dans l'onglet Pools quand Type est LDAP). |
| Base DN | Base du sous-arbre à lire. |
| Filter | Filtre LDAP. Défaut (objectClass=*). |
| Portée | Base / One level / Subtree. Défaut Subtree. |
| Correspondance d'attributs | Une ligne par ldap_attribute → target_column. Les attributs répétés sont concaténés avec ;. |
| Connecteur cible | Liste déroulante de connecteurs SQL. |
| Requête cible | Liste déroulante des requêtes d'écriture du connecteur (seules les requêtes :write apparaissent). |
| Colonne clé | La colonne sur laquelle l'upsert s'appuie. |
| Mode de suppression | None (défaut) / Hard / Soft. Hard supprime les lignes qui ne correspondent plus au filtre LDAP ; Soft bascule une colonne drapeau (le champ Colonne de suppression apparaît). |
L'étape consigne read, upserted, deleted. Un échec de bind LDAP fait échouer rapidement (pas de relance, puisque les identifiants ne vont pas se réparer seuls) ; les échecs par ligne sont consignés mais l'étape continue.
Chaînage des résultats
Chaque étape consigne son résultat sur la ligne d'exécution. L'étape suivante peut le référencer via ${previous_step.<key>} (l'étape immédiatement précédente) ou ${steps.<name>.<key>} (toute étape antérieure). La référence est tapée directement dans le champ consommateur — Paramètres, Arguments nommés, Body, etc.
Exemple : une première étape find-batch exécute une requête SQL avec Mode de lecture = First ; une seconde étape send-batch lit ${steps.find-batch.first_row.id} pour n'envoyer que ce lot. Le champ Condition de send-batch peut court-circuiter quand aucun lot n'a été trouvé : ${steps.find-batch.row_count} > 0.
La syntaxe d'expression est la même que celle documentée dans Conditions de formulaire.
Quand une étape échoue
| Échec | Comportement |
|---|---|
| Exception dans le callable / le pilote / l'endpoint | Étape consignée comme failed avec la trace. La politique de relance s'applique. |
| Délai dépassé | L'étape est annulée. Consignée comme failed avec error = "timeout". La politique de relance s'applique. |
| Connexion à la base perdue en cours d'étape | Identique à une exception. |
| Continuer en cas d'erreur = activé | Étape failed mais le job continue. Le statut final du job est partial-success. |
| Toutes les relances épuisées | Statut final du job failed. Aucune étape suivante ne s'exécute. |
La politique de relance est réglée dans l'éditeur de jobs — défaut au niveau du job, avec remplacements par étape dans l'éditeur d'étape.
Permissions
Les types d'étape héritent de la permission sous-jacente du connecteur / endpoint — sql:<connector>:<query>, api:<connector>:<endpoint>. Une étape qui référence un connecteur que l'appelant ne peut pas exécuter est refusée à l'enregistrement avec la permission manquante dans l'erreur.
L'enregistrement et l'exécution du job lui-même sont filtrés par settings:jobs + job:<name>.
Sous le capot
Les définitions d'étapes sont enregistrées à l'intérieur du bloc TOML de chaque job sous liberty-apps/plugins/<app>/jobs.toml. Les opérateurs n'éditent pas ce fichier à la main ; l'éditeur d'étape est l'interface canonique. Les opérateurs avancés peuvent toujours utiliser l'onglet Raw TOML de l'éditeur de jobs quand une limite de l'éditeur les bloque.
Pour aller plus loin
- Éditeur de jobs — où les étapes s'organisent dans le pipeline du job.
- Exécutions et supervision — où les résultats d'étape sont remontés.
- Apps et Plugins → Plugins — écrire les callables Python derrière les étapes Python.
- Concepts → Connecteurs — les connecteurs SQL / HTTP / LDAP que les étapes ciblent.