Expressions
Le mode expression utilise JSONata pour calculer une valeur à l’exécution lorsqu’un binding direct ou une valeur fixe ne suffit pas. Il conserve le système de types et les règles de protection des données du processus.
Éditeur d’expression
Les expressions s’éditent dans une modale dédiée. La valeur du paramètre n’est modifiée qu’au clic sur Valider ; fermer ou annuler la modale conserve l’expression précédente. Cette édition transactionnelle permet d’explorer et tester une expression sans modifier progressivement le processus.
La barre d’outils regroupe les aides de conception : navigateur de variables, navigateur de fonctions, snippets prêts à adapter et panneau de test. Les suggestions sont filtrées selon le contexte du node courant et son type attendu.
Contexte disponible
Une expression peut lire les mêmes sources que les bindings : input pour l’entrée du processus, nodes.<node_id> pour les sorties garanties d’un node précédent, vars pour les variables du processus et env pour les variables d’environnement du marchand.
Les relations virtuelles exposées par les objets plateforme peuvent être parcourues comme les autres propriétés lorsque leur disponibilité est garantie. L’éditeur utilise leur type réel pour l’autocomplétion et la validation.
Les règles d’ancêtres garantis restent applicables : une expression ne transforme pas une sortie potentiellement absente en dépendance sûre. Pour le typage et les sources disponibles, voir Entrées, sorties et bindings.
Type attendu et type inféré
Le header de l’éditeur affiche le type attendu par le paramètre. Pendant l’édition, Ormuz infère également le type du résultat de l’expression et signale les incompatibilités avant validation. Le but est de vérifier non seulement que l’expression est syntaxiquement valide, mais qu’elle produit une valeur utilisable par le node.
Lorsque Each est activé, le type attendu est transformé pour refléter la cardinalité de la source : un node qui attend T peut ainsi recevoir une collection T[] et être exécuté une fois par élément. Voir Collections et boucles.
Fonctions Ormuz
Ce tableau est dérivé du catalogue de fonctions sûres disponible dans le runtime d’expression ; il reste donc aligné sur les fonctions Ormuz réellement exposées.
| Fonction | Description et exemple |
|---|---|
$add_days(date, n) | Ajoute un nombre de jours à une date ou datetime. $add_days(input.invoice.due_date, 7) |
$add_hours(datetime, n) | Ajoute un nombre d’heures et retourne une datetime ISO 8601. $add_hours(input.checkout.created_at, 2) |
$add_minutes(datetime, n) | Ajoute un nombre de minutes et retourne une datetime ISO 8601. $add_minutes(input.checkout.created_at, 30) |
$add_months(date, n) | Ajoute des mois en respectant les fins de mois. $add_months(input.credit_limit.valid_from, 12) |
$cents_to_amount(units, decimals?) | Convertit un entier en unités mineures vers une représentation décimale. $cents_to_amount(input.invoice.amount_including_tax) |
$coalesce(...values) | Retourne le premier argument non null ou non undefined. $coalesce(input.invoice.reference, "UNREFERENCED") |
$diff_days(from, to) | Calcule le nombre de jours entre deux dates. $diff_days(input.invoice.due_date, $now()) |
$end_of_day(date) | Retourne la fin du jour en UTC. $end_of_day(input.invoice.due_date) |
$format(value, format, options?) | Formate une valeur avec les formats publics Ormuz. $format(input.invoice.amount_including_tax, "amount", { "currency": "EUR" }) |
$if_empty(value, fallback) | Retourne une valeur de repli lorsque la valeur est absente ou vide. $if_empty(input.buyer.trade_name, input.buyer.legal_name) |
$markdown_table(rows, columns, options?) | Transforme une collection en tableau Markdown. $markdown_table(input.line_items, [{"label":"Article","path":"product_name"}]) |
$start_of_day(date) | Retourne le début du jour en UTC. $start_of_day(input.invoice.due_date) |
$subtract_days(date, n) | Soustrait un nombre de jours à une date ou datetime. $subtract_days(input.invoice.due_date, 30) |
$subtract_hours(datetime, n) | Soustrait un nombre d’heures et retourne une datetime ISO 8601. $subtract_hours(input.checkout.expires_at, 2) |
$subtract_minutes(datetime, n) | Soustrait un nombre de minutes et retourne une datetime ISO 8601. $subtract_minutes(input.checkout.expires_at, 15) |
$subtract_months(date, n) | Soustrait des mois en respectant les fins de mois. $subtract_months(input.invoice.due_date, 3) |
$to_date(datetime) | Extrait la date YYYY-MM-DD d’une datetime. $to_date(input.invoice.issue_date) |
$today() | Retourne la date courante UTC au format YYYY-MM-DD. $today() |
Tester une expression
Le panneau de test permet d’évaluer l’expression avec le contexte de prévisualisation disponible dans l’éditeur. Il affiche le résultat et son type afin de vérifier rapidement une transformation avant de la valider. Ce test reste une aide de conception : l’exécution réelle utilise les données de l’instance et ses snapshots.
Exemples
/* Date d'échéance + 30 jours */ $add_days(input.invoice.due_date, 30) /* Premier montant disponible */ $coalesce(input.invoice.amount_including_tax, input.order.amount_including_tax) /* Somme d'une collection */ $sum(input.line_items.amount_including_tax) /* Date de fin de validité */ $add_months(input.credit_limit.valid_from, 12)
Quand utiliser une expression
Utilisez une expression pour un calcul, une date relative, une transformation ou une composition de plusieurs valeurs. Pour filtrer, trier, partitionner ou parcourir une collection typée, préférez les nodes dédiés : ils conservent explicitement le type des items et rendent l’intention du processus lisible.
De même, pour une décision de routage courante, préférez les nodes de routage et décision plutôt qu’une expression opaque lorsque le besoin peut être exprimé directement.