Étapes
Une étape est une unité de travail d'une tâche. Les étapes s'exécutent dans l'ordre ; quand l'une échoue, les suivantes sont enregistrées comme skipped: earlier step failed.
| L'étape… | Type |
|---|---|
| lance une requête nommée d'un connecteur SQL | sql_query |
| copie une table entière d'un connecteur à un autre | sql_copy |
| charge un classeur ou un fichier CSV dans une table | file_load |
| écrit le résultat d'une requête de lecture dans un fichier Excel ou CSV | file_export |
| appelle une fonction Python d'un plugin | python |
| appelle une URL | http |
| lit un annuaire LDAP / Active Directory dans une table | ldap_sync |
| lance une autre tâche et l'attend | call_job |
| produit un fichier Excel ou PDF à partir d'une analyse enregistrée, d'un tableau de bord ou d'un rapport | report |
| envoie un message, accompagné des fichiers de l'exécution | notify |
Dans l'éditeur de tâche, la barre Ajouter une étape : propose un bouton par type, et chaque étape ouvre un formulaire avec ses propres champs. Quelques clés n'existent que dans jobs.toml (signalées ci-dessous).
Vue d'ensemble
Champs communs
| Champ | Défaut | Remarques |
|---|---|---|
name | — | Affiché dans le détail de l'exécution ; unique dans la tâche. |
type | — | L'un des dix types. |
enabled | true | false saute l'étape (enregistrée comme skipped: disabled). Se règle dans jobs.toml, ou pour une exécution dans la fenêtre Exécuter avec des paramètres. |
timeout_seconds | 3600 | L'étape est annulée passé ce délai. Se règle dans jobs.toml. |
continue_on_failure | false | true : quand l'étape échoue (après ses tentatives), les suivantes s'exécutent quand même et l'exécution finit en échec en la nommant — pour une tâche qui enchaîne des traitements indépendants. Une case à cocher dans l'éditeur d'étape ; pour toutes les étapes d'une tâche, [jobs.step_defaults]. |
Désactiver une étape pour une installation. Une étape dont l'installation n'a pas besoin — la collecte LDAP sans LDAP — se liste dans disabled_steps = ["SECURITY_LDAP"] de la tâche (la case Désactivée pour cette installation de l'éditeur d'étape). Elle ne s'exécute jamais, même quand une exécution ou un préréglage sélectionne toutes les étapes : la fenêtre Exécuter avec des paramètres la montre désactivée et non sélectionnable, l'exécution l'enregistre comme skipped: turned off for this install. Contrairement à enabled — la valeur par défaut qu'une exécution peut remplacer — c'est le dernier mot de l'exploitant, et l'installateur des applications sous licence la conserve d'une mise à jour à l'autre.
Quand une étape échoue sur une erreur de base de données, le détail de l'exécution affiche la phrase de la base elle-même — invalid input for query argument $1: 2025 (expected str, got int) — et l'instruction part dans le journal du serveur.
Requête SQL — sql_query
Lance une requête nommée d'un connecteur SQL — une requête définie sur la page du connecteur, en lecture ou en écriture.
| Champ | Requis | Remarques |
|---|---|---|
connector | oui | Le connecteur SQL. |
query | oui | Le nom de la requête, pas du texte SQL. |
params | non | Les valeurs liées aux paramètres de la requête. |
pool | non | Un autre pool de l'ensemble du connecteur — voir Connecteurs multi-pools. Uniquement dans jobs.toml. |
Enregistre le nombre de lignes renvoyées ou modifiées. Pour rafraîchir une vue matérialisée, appeler une procédure ou purger une table, écrire l'instruction comme une requête du connecteur, puis l'appeler ici.
Copie SQL — sql_copy
Transfère les lignes d'une table source vers une table cible, éventuellement sur une autre base.
| Champ | Défaut | Remarques |
|---|---|---|
source = {connector, schema, table} | — | Requis. pool peut s'y ajouter (uniquement dans jobs.toml). |
target = {connector, schema, table} | — | Requis. Idem. |
mode | overwrite | overwrite : les lignes sont écrites dans une table de travail <table>__new, qui remplace ensuite la cible en une transaction — la cible n'est jamais vide pendant la copie. append : les lignes s'ajoutent à la cible telle quelle. |
type_coercion | jde | jde applique les règles JD Edwards (décimales implicites, dates juliennes, codes complétés d'espaces) ; none copie les valeurs telles quelles. |
decimal_mode | truncate | Avec jde : tronquer (truncate) ou conserver (preserve) la partie décimale. |
batch_size | 10000 | Lignes par lot. |
strip_both_columns | [] | Colonnes dont les valeurs sont débarrassées des espaces des deux côtés. |
upsert est accepté par le schéma mais refusé à l'exécution : pour un ajout ou une mise à jour, écrire une requête MERGE / ON CONFLICT et l'appeler avec sql_query. Enregistre le nombre de lignes écrites.
Chargement de fichier — file_load
Charge un classeur Excel (.xlsx, .xlsm) ou un fichier texte (.csv, .txt, .tsv) dans une table — selon une planification, sans personne au clavier, aux volumes d'une table de faits, et rejouable pour une période sans toucher aux autres.
Le fichier
Le fichier vient, par ordre de priorité :
- d'un fichier choisi au lancement de la tâche — la fenêtre Exécuter avec des paramètres affiche un sélecteur de fichier pour chaque étape
file_load(la fenêtre s'ouvre pour toute tâche qui en contient une), de même que la page de la tâche ouverte depuis le menu d'une application, pour les étapes sanspathni dossier surveillé ; - de
path— un chemin sur le serveur, qui peut contenir${params.x}(un paramètre d'exécution),${run.id}et${job.id}:/data/in/sales-${params.period}.xlsx; - d'un dossier surveillé —
watch_diretwatch_pattern(*.xlsx) : chaque fichier correspondant est chargé dans l'ordre des noms, chacun dans sa propre transaction, puis déplacé dansdone/oufailed/sous un nom horodaté. Un fichier en échec arrête l'exécution ; les fichiers suivants restent dans le dossier. Un dossier vide n'est pas une erreur.
| Champ | Défaut | Remarques |
|---|---|---|
sheet | première feuille | Un nom ou un numéro (1 = la première). |
header_row | 1 | La ligne des en-têtes de colonnes ; les données commencent en dessous. Les lignes vides sont ignorées. |
delimiter | détecté | Séparateur CSV ; détecté parmi ; , tabulation ` |
encoding | utf-8-sig | CSV uniquement. |
La cible
| Champ | Remarques |
|---|---|
target = {connector, schema, table} | Un connecteur SQL ; la table doit exister. |
columns | Colonne cible ← en-tête du fichier ou position (#3). Les en-têtes se retrouvent sans tenir compte de la casse, des espaces, de _ et de - ; les colonnes non citées se retrouvent par leur nom. |
constants | Colonne cible ← valeur, pour ce que le fichier ne porte pas : period = "${params.period}", batch_id = "${run.id}". |
Chaque cellule est convertie au type de sa colonne cible : entiers, décimaux (12,5 et 12.5 donnent tous deux 12,5 ; une virgule seule est le séparateur décimal), dates (2026-10-27, 27/10/2026, 27.10.2026, 20261027, et dates Excel), booléens (1, true, yes, oui…), texte. Un nombre saisi comme texte ne retrouve pas les zéros de tête que le tableur a déjà retirés.
Mode de chargement
| Champ | Choix |
|---|---|
load_mode | append (défaut) ajoute les lignes. replace_partition supprime d'abord les lignes des partitions présentes dans le fichier, puis insère — en une seule transaction : un chargement en échec laisse les données précédentes en place, et un mois corrigé ne remplace que ce mois. |
partition_by | Les colonnes de partition (period, company) — obligatoires avec replace_partition. Les partitions viennent des constantes quand elles couvrent toutes les colonnes, sinon des valeurs distinctes trouvées dans le fichier. |
on_error | fail (défaut) : la première cellule invalide fait échouer l'étape et cite la ligne. skip : les lignes invalides sont comptées comme rejetées et écrites dans un CSV (fichier, ligne, motif) proposé dans le détail de l'exécution. |
batch_size | 10000 lignes par insertion. |
Garde-fous
| Champ | Remarques |
|---|---|
refuse_query | Une requête nommée lancée avant toute écriture, avec les paramètres d'exécution et les constantes comme paramètres liés. Avec partition_by, elle s'exécute une fois par partition présente dans le fichier, les colonnes de partition servant de paramètres liés (:YEAR, :MONTH, :COMPANY_CODE) : la garde suit le fichier, et non un paramètre saisi au lancement. Si elle renvoie une ligne, le chargement est refusé et la première colonne en donne le motif : période 2026-02 clôturée. refuse_connector : son connecteur, celui de la cible par défaut. |
control_column + control_total | La colonne est sommée sur les lignes chargées et comparée à une valeur, à ${params.total} ou à une cellule du fichier (@B2, @Totaux!B2), à control_tolerance près. Un écart annule le chargement du fichier et cite les deux montants. |
Dans l'exécution
Le détail de l'exécution affiche N read · N inserted · N rejected et, quand des lignes ont été rejetées, Rejected rows (csv) pour les télécharger. Le journal ajoute les partitions remplacées et les lignes supprimées.
Les fichiers envoyés et les fichiers de rejets vont dans la zone de travail des tâches, .nomaflow/files à côté de la configuration ; un envoi est limité à 200 Mo.
[[jobs.steps]]
type = "file_load"
name = "load-sales"
path = "/data/in/ventes-${params.period}.xlsx"
sheet = "Ventes"
target = { connector = "sales", schema = "public", table = "fact_sales" }
columns = { company = "Société", article = "Article", qty = "Quantité", revenue = "CA" }
constants = { period = "${params.period}", batch_id = "${run.id}" }
load_mode = "replace_partition"
partition_by = ["period", "company"]
refuse_query = "period_closed_get"
control_column = "revenue"
control_total = "@Totaux!B2"
Python — python
Appelle une fonction d'un plugin : callable = "paquet.module:fonction".
| Champ | Remarques |
|---|---|
callable | module.chemin:fonction — forme vérifiée à l'enregistrement, import au lancement de l'étape. |
op_kwargs | Les arguments passés à la fonction, fusionnés par-dessus les paramètres partagés de la tâche. |
La fonction reçoit ses arguments par mot-clé et, quand elle les déclare par leur nom, connectors (le registre des connecteurs), ctx (l'exécution : ctx.run_id, ctx.job_id, ctx.trigger) et settings. Elle peut être async ou non. Sa valeur de retour : un int donne le nombre de lignes modifiées, un dict est conservé comme détail de l'étape, None convient ; une exception fait échouer l'étape. Pour écrire dans le journal de l'exécution, utiliser un logger d'un espace de noms enregistré. Le contrat complet se trouve dans Écrire un callable.
HTTP — http
| Champ | Défaut | Remarques |
|---|---|---|
url | — | Requis. Utilisée telle quelle. |
method | GET | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. |
headers | {} | Envoyés tels quels. |
body | aucun | Du texte, ou une table envoyée en JSON (avec Content-Type: application/json si aucun n'est défini). |
Une réponse 2xx réussit ; toute autre fait échouer l'étape avec le code. L'étape conserve le code, les 4 premiers Ko de la réponse et la durée. Les valeurs de l'environnement s'écrivent ${NOM} dans jobs.toml et sont remplacées au chargement du fichier.
Synchronisation LDAP — ldap_sync
Lit des entrées d'un annuaire LDAP et lance une requête d'écriture d'un connecteur SQL pour chacune.
| Champ | Remarques |
|---|---|
server | ldaps://ad.example.com:636. |
bind_dn, bind_password | Le compte de lecture ; écrire le mot de passe ${LDAP_PASSWORD}. |
search_base, search_filter | Où et quoi chercher : DC=example,DC=com, (objectClass=user). |
attributes | Les attributs à lire. |
target_connector, target_query | La requête d'écriture lancée pour chaque entrée. |
mapping | Attribut LDAP → paramètre de la requête. Un attribut absent donne NULL. |
Enregistre le nombre d'entrées lues et de lignes écrites.
Lancer une tâche — call_job
target_job_id désigne une autre tâche. L'étape la lance, attend sa fin et en prend le résultat : succès, échec ou annulation. La tâche appelée a sa propre exécution dans l'historique et reprend le niveau de journal et les paramètres d'exécution de l'appelante. Une tâche qui finirait par s'appeler elle-même est refusée.
Rapport — report
Produit un document dans la zone de travail de l'exécution : une analyse ou un tableau de bord enregistré de l'explorateur de données, ou un rapport d'un plugin. Suivie d'une étape notify, elle fait d'une synthèse planifiée une tâche ordinaire.
| Champ (éditeur) | Remarques |
|---|---|
| Source | Une analyse enregistrée (Explorateur), Un tableau de bord d'analyses (Explorateur) — une section par tuile — ou Un rapport (plugin). |
| Modèle d'exploration, Analyses / Tableaux de bord | Le modèle, puis l'une de ses analyses ou l'un de ses tableaux de bord partagés. Un élément privé n'est pas proposé. |
| Rapport | Pour un rapport de plugin : le rapport, parmi ceux des applications installées. |
| Format | Excel ou PDF — les mêmes documents que l'export de l'explorateur, graphiques dessinés dans le PDF. |
| Période | Un préréglage (Mois dernier, Ce trimestre, 7 derniers jours…, ou toutes les dates), ou La période propre de l'analyse. |
| Nom du fichier | Le nom du fichier ; par défaut, le titre de l'analyse. |
| Rendre comme l'utilisateur | Le document contient ce que voit cet utilisateur : le périmètre de données de ses rôles, avec ses attributs. Une synthèse rendue pour le responsable d'une société ne contient que cette société. |
| Rendre comme le rôle | Le périmètre de données d'un rôle. Une règle dont les valeurs viennent d'un attribut utilisateur n'autorise rien dans ce cas : pour ces rôles, préférer Rendre comme l'utilisateur. |
Pour un rapport de plugin, les paramètres de l'exécution — ceux de la tâche, ceux choisis au lancement, les paramètres utilisateur — sont transmis au rapport en plus de ceux de l'étape, convertis dans le type que déclare le rapport (un nombre reste un nombre) ; une valeur vide laisse la valeur par défaut du rapport.
Sans utilisateur ni rôle, le document est sans restriction. Le détail de l'exécution propose le fichier au téléchargement sous l'étape ; le journal le nomme avec sa taille.
Notification — notify
Envoie un message par les canaux de notification, accompagné des fichiers produits par l'exécution.
| Champ (éditeur) | Remarques |
|---|---|
| Destinataires | user:<identifiant>, role:<rôle> ou email:<adresse>, un par ligne. |
| Objet, Corps | Texte avec marqueurs : {JOB}, {RUN_ID}, {FILES} (les noms des fichiers joints), {DATE} (la date du jour). |
Joindre (fichiers du run ; * = tous) | * joint tous les fichiers produits par l'exécution — chaque report, et les lignes rejetées d'un file_load ; sinon, nommer les fichiers. Un fichier nommé que l'exécution n'a pas produit fait échouer l'étape. |
| Canaux | portal (la cloche) et email. Le compte de messagerie est celui des notifications. |
Le message renvoie vers l'exécution. Le détail de l'exécution liste les fichiers joints sous l'étape.
[[jobs.steps]]
type = "report"
name = "revenue"
report = "analysis:revenue_by_business_unit"
app = "sales"
model = "sales"
format = "pdf"
period = "lastMonth"
as_user = "cfo"
[[jobs.steps]]
type = "notify"
name = "send"
recipients = ["role:management"]
subject = "Synthèse des ventes {DATE}"
body = "La synthèse mensuelle des ventes est jointe : {FILES}."
attach = ["*"]
Planifier la tâche le premier du mois (cron 0 7 1 * *) — voir Planifications.
Export de fichier — file_export
Écrit le résultat d'une requête de lecture nommée dans un fichier de la zone de travail de l'exécution — pour qu'un autre système le récupère, ou qu'une étape notify le joigne. Une requête d'écriture est refusée.
| Champ (éditeur) | Remarques |
|---|---|
| Connecteur, Requête | La requête de lecture à exécuter. |
| Paramètres | Ses paramètres liés ; ceux de l'exécution sont transmis aussi. Une valeur peut utiliser ${params.x}. |
| Format | Excel (xlsx) (par défaut) ou CSV. |
| Nom du fichier (par défaut : la requête) | Peut utiliser ${params.x} et ${run.id} : sales-${params.period}. |
| Feuille | Excel seulement — le nom de la requête par défaut. |
| Séparateur CSV, Encodage | CSV seulement — ; et utf-8-sig par défaut. |
| Copier aussi dans ce dossier (optionnel) | Un dossier du serveur où une copie est également écrite, créé s'il n'existe pas : /data/out/${params.period}. |
Les lignes sont lues dans la base au fil de l'eau, dans la limite de lignes du connecteur — le journal indique quand l'export a été plafonné. La ligne d'en-tête porte les libellés des colonnes ; les colonnes masquées sont écartées. Le détail de l'exécution propose le fichier sous l'étape, et la rétention de la zone de travail s'y applique — pas à la copie dans l'autre dossier.
Réessais et délais
Le bloc Politique de réessai de la tâche (attempts, backoff fixe ou exponentiel, base_seconds) s'applique à chaque étape : une étape est tentée jusqu'à attempts fois au total (1, la valeur par défaut, signifie aucune nouvelle tentative), avec une attente de base_seconds entre deux tentatives — constante, ou doublée à chaque fois avec exponential. La tâche entière s'arrête après timeout_seconds (4 heures par défaut).