Étiquettes de connexion

Les étiquettes de connexion sont des représentations visuelles des données disponibles depuis les blocs connectés. Elles offrent un moyen simple de référencer les sorties des blocs précédents dans votre workflow.

Qu'est-ce qu'une étiquette de connexion ?

Les étiquettes de connexion sont des éléments interactifs qui apparaissent lorsque des blocs sont connectés. Elles représentent les données pouvant circuler d'un bloc à un autre et vous permettent de :

• Visualiser les données disponibles depuis les blocs sources
• Référencer des champs de données spécifiques dans les blocs de destination
• Créer des flux de données dynamiques entre les blocs

Utiliser les étiquettes de connexion

Il existe deux façons principales d'utiliser les étiquettes de connexion dans vos workflows :

Syntaxe des étiquettes

Les étiquettes de connexion utilisent une syntaxe simple pour référencer les données :

<blockname.path.to.data>

Où :

• blockname est le nom du bloc source, en minuscules et sans espaces. Un bloc nommé « Customer Lookup » se lit <customerlookup.…>. L'identifiant du bloc n'est jamais résolu, et renommer un bloc met à jour les étiquettes qui le désignent, y compris la collection et la condition while d'une boucle (Loop).
• path.to.data est le chemin vers le champ de données spécifique. Un élément de tableau se lit par sa position, écrite [0] ou .0 : <api2.data.users[0].name> et <api2.data.users.0.name> sont la même référence.

Par exemple :

• <agent1.content> - Référence le champ content d'un bloc nommé « Agent 1 »
• <api2.data.users[0].name> - Référence le nom du premier utilisateur dans le tableau users depuis le champ data d'un bloc nommé « API 2 »
• <start.customerName> - Référence le champ customerName de la charge utile du déclencheur ; start est toujours disponible

Une étiquette n'est résolue que si le bloc qu'elle nomme s'exécute avant le bloc qui la lit. L'éditeur ne met en évidence que les étiquettes résolubles ; une étiquette qui ne l'est pas reste du texte littéral dans les champs texte — <agent1.contnet> envoie le texte <agent1.contnet> — et devient undefined dans le code d'un bloc Function et dans les expressions de condition.

Un workflow contenant une étiquette non résoluble est tout de même enregistré : l'enregistrement la signale comme un avertissement. Il n'est pas déployé : son déploiement ou sa promotion est refusé avec workflow_reference_unresolvable (HTTP 422), et le refus nomme chaque étiquette et le bloc qui la contient. Renommez l'étiquette ou le bloc pour qu'ils correspondent, puis déployez à nouveau. Une étiquette variable qui nomme une variable de workflow déclarée ne produit qu'un avertissement.

Références d'étiquettes dynamiques

Les étiquettes de connexion sont évaluées au moment de l'exécution, ce qui signifie :

1. Elles référencent toujours les données les plus récentes
2. Elles peuvent être utilisées dans des expressions et combinées avec du texte statique
3. Elles peuvent être imbriquées dans d'autres structures de données

Exemples

// Reference in text
"The user's name is <userBlock.name>"

// Reference in JSON
{
  "userName": "<userBlock.name>",
  "orderTotal": <apiBlock.data.total>
}

// Reference in code: no quotes around the tag, string values are inserted as quoted literals
const greeting = "Hello, " + <userBlock.name> + "!";
const total = <apiBlock.data.total> * 1.1; // Add 10% tax

Dans le code d'un bloc Function et dans les expressions de condition, écrivez l'étiquette seule plutôt qu'à l'intérieur d'une chaîne entre guillemets : "Hello, <userBlock.name>!" deviendrait "Hello, "Ada"!", qui n'est pas du code valide.

Dans un champ JSON (les données d'un bloc Response, le format de réponse d'un Agent, les lignes d'une écriture de table ou le contexte d'une instance de processus), une étiquette est insérée selon sa position :

• À l'intérieur d'une chaîne entre guillemets, comme dans "userName": "<userBlock.name>", l'étiquette est remplacée par le texte de la valeur, échappé. Un guillemet double, une barre oblique inverse ou un saut de ligne dans la valeur reste dans la chaîne, et une valeur ne peut pas ajouter de clé.
• Seule, à la place d'une valeur, comme dans "orderTotal": <apiBlock.data.total>, l'étiquette est insérée en JSON. Les objets, tableaux, nombres et booléens sont insérés tels quels. Un texte qui est lui-même une valeur JSON est inséré comme cette valeur ; tout autre texte devient une chaîne JSON.

Deux cas conservent la simple substitution de texte. Un champ qui ne contient qu'une seule étiquette et rien d'autre, comme <agent1.content>, reçoit le texte même de la valeur. Un champ dont le texte n'est pas du JSON reste lui aussi en simple substitution.