Entrées, sorties et bindings
Chaque paramètre d’un node reçoit une valeur selon un contrat typé. Ormuz distingue une valeur configurée, un binding direct vers le contexte et une expression de transformation ; l’éditeur vérifie la compatibilité avant que le processus puisse être utilisé.
Trois modes de paramétrage
Les trois modes convergent vers le même contrat de paramètre : le type attendu par le node reste l’autorité finale.
| Mode | Quand l’utiliser | Comportement |
|---|---|---|
value | Valeur configurée dans la définition | Convient aux constantes et aux contenus structurés connus à la conception. Les chaînes et structures peuvent aussi contenir des interpolations `{{ ... }}` résolues à l’exécution lorsque le paramètre les autorise. |
binding | Reprendre directement une valeur du contexte | Lit une source `input`, `node`, `var` ou `env` sans ajouter de transformation. C’est le mode privilégié pour transmettre des objets plateforme et des valeurs déjà typées. |
expression | Calculer ou transformer une valeur | Évalue une expression JSONata sur le contexte disponible. À réserver aux calculs, coalescences, agrégations et transformations qu’un binding direct ne peut pas exprimer. |
Envoyer à {{ env.support_email }} reste un value : sa structure est définie dans le processus et ses placeholders sont rendus à l’exécution. Passez à expressionlorsqu’il faut réellement calculer ou transformer la valeur.
Le système de types
Chaque paramètre déclare le ou les types qu’il accepte. L’éditeur compare le type de la source avec le type attendu et refuse les câblages incompatibles. Cette vérification porte notamment sur les sous-types d’objets : un platform.company n’est pas interchangeable avec un platform.invoice.
Types primitifs
| Type | Description |
|---|---|
string | Texte, éventuellement enrichi d’un sous-type sémantique ou d’une enum. |
integer | Entier, éventuellement borné. |
number | Nombre décimal, éventuellement borné. |
boolean | Booléen vrai/faux. |
object | Objet structuré : objet plateforme, draft, objet commun ou objet d’extension. |
array<T> | Collection dont le type des éléments est déclaré et vérifié. |
Exemples de sous-types sémantiques
Les sous-types ajoutent une sémantique et des règles de validation à un type de base. La liste ci-dessous est volontairement représentative, pas exhaustive ; la référence des schémas et types est le point d’entrée pour les contrats publics détaillés.
| Sous-type | Signification |
|---|---|
common.email | Adresse email. |
common.phone | Numéro de téléphone. |
common.url | URL http ou https. |
common.datetime | Date et heure ISO 8601. |
common.date | Date ISO 8601. |
common.duration | Durée ISO 8601, par exemple `P7D` ou `PT2H`. |
common.country_code | Code pays ISO 3166-1 alpha-2. |
common.currency_code | Code devise ISO 4217. |
common.address | Adresse postale structurée. |
Objets plateforme
Les objets plateforme utilisent un sous-type tel que platform.company, platform.invoiceou platform.order. Lorsqu’un paramètre attend un objet plateforme persistant, il reçoit normalement cet objet via un binding ou une expression ; il ne s’agit pas d’un JSON libre à ressaisir dans le processus.
Les drafts utilisent le même objet métier avec un mode de type draft. Ils restent distincts d’une ressource persistée portant un id.
Sources de binding
Un binding lit directement l’une des quatre portées du contexte d’exécution. Il n’ajoute pas de calcul : la valeur lue doit déjà être compatible avec le paramètre cible.
| Portée | Source | Description | Exemple |
|---|---|---|---|
input | Entrée du processus | Valeur fournie au démarrage de l’instance. | input.invoice |
node | Sortie d’un node | Valeur produite par un node amont garanti sur le chemin courant. | nodes.resolve_contact.selected_contact |
var | Variable de processus | Valeur mutable portée par l’instance pour partager ou accumuler un état explicite. | vars.company_draft |
env | Variable d’environnement | Valeur configurée pour l’environnement du marchand et capturée dans le contexte d’exécution. | env.approval_limit |
Relations d’objets
Lorsqu’une source est un objet plateforme typé, un binding peut traverser une relation déclarée sans transformer l’identifiant en accès implicite. Par exemple, depuis une facture, l’éditeur peut proposer la relation vers son entreprise acheteuse. Ormuz résout alors explicitement la cible de cette relation dans le périmètre autorisé du processus.
Références de ressources
Certains paramètres attendent seulement l’identité publique typée d’une ressource, notée conceptuellementref(T), et non l’objet complet platform.T.
Un objet complet peut alimenter une référence du même type : Ormuz projette alors son idsans lecture supplémentaire. L’inverse n’est jamais automatique : connaître un identifiant ne donne pas accès au contenu de la ressource. Utilisez un node de lecture explicite si le processus a besoin de l’objet.
| Source | Destination | Compatibilité |
|---|---|---|
platform.T | ref(T) | Oui, projection de l’ID. |
ref(T) | platform.T | Non, une lecture explicite est requise. |
Les références de configurations d’extension sont également qualifiées par extension : connaître l’identité d’une configuration ne révèle pas son contenu ni ses secrets.
Ancêtres garantis
Une sortie de node ne peut être utilisée que si le node source est un ancêtre garanti du node courant dans les chemins de routage concernés. Une branche conditionnelle qui peut être évitée ne fournit donc pas une sortie sûre après la convergence simplement parce qu’elle apparaît graphiquement en amont.
Cette vérification évite qu’un processus valide dépende, à l’exécution, d’une sortie qui n’existe pas sur le chemin réellement emprunté.
- Déplacer le calcul avant la branche lorsque cette valeur peut être produite avant la décision.
- Concevoir explicitement la convergence lorsque chaque branche doit fournir une valeur compatible.
- Utiliser une variable de processus seulement lorsque le modèle du processus garantit réellement qu’elle sera initialisée avant lecture.
Variables de processus
Les variables de processus portent une valeur explicite pendant toute la durée de vie d’une instance. Elles sont utiles lorsqu’un état doit être partagé entre plusieurs étapes sans dépendre directement de la sortie d’un seul node.
Certaines primitives peuvent créer une variable ; d’autres peuvent mettre à jour une variable existante. Un pattern fréquent consiste à faire évoluer un draft typé au fil de plusieurs interactions, puis à le matérialiser explicitement lorsque le contrat métier est complet.
Variables d’environnement
Les valeurs propres à un marchand ou à un environnement sont disponibles sous la portée env. Elles peuvent être utilisées directement par un binding, référencées dans un template value ou consommées par une expression selon le besoin.
Une référence comme env.approval_limit doit identifier statiquement sa clé afin qu’Ormuz puisse enregistrer la dépendance du processus et vérifier son type avant déploiement. Les détails de configuration sont décrits dans Comptes, marchands et environnements.
Classification des données
Le câblage conserve la classe de protection des données dont il dépend. Une valeur sensitive ousecret reste protégée lorsqu’elle est transmise directement, placée dans une variable ou utilisée dans une expression.
Lorsqu’une transformation dépend de plusieurs sources, le résultat hérite de la classification nécessaire pour protéger ces dépendances. Une réduction explicite de classification peut nécessiter un consentement lors de l’enregistrement du processus.
Voir Protection des données dans les processus pour le modèle complet de propagation, downgrade et reveal ciblé.