Clés de champ

Pourquoi elles existent

Sans clés de champ, une automatisation devrait adresser vos questions par des ids internes qui ne signifient rien pour personne — et un payload de webhook en serait plein. Avec les clés de champ, les deux côtés lisent la même chose :

{ "company_name": "Acme", "employees": 120, "contacts": [{ "name": "Ada" }] }

Les clés de champ sont utilisées à deux endroits : prefill, context, et readonly lors de la création d’une demande ; et les maps answers et display de chaque callback et de chaque payload webhook.

Où les trouver

Chaque clé que le formulaire publie vit à un seul endroit, le tableau Clés : chaque champ, et sous une question à choix chaque option, sous une matrice chaque ligne et colonne. Il se termine par un aperçu de l’objet answers que votre callback portera, avec vos clés dedans.

1. 1

   Ouvrez-le

   Cliquez sur l'icône clé de la barre d'outils de l'éditeur (ou Clés dans le menu de débordement de la barre d'outils sur une fenêtre étroite). Le tableau s'ouvre dans un panneau latéral par-dessus tout le formulaire.

2. 2

   Lisez l'espace réservé

   Quand un champ de saisie est vide, son espace réservé affiche la clé à laquelle le champ répond réellement — la clé sous laquelle il a été publié si le formulaire est en ligne, sinon la clé dérivée de son titre ou de son intitulé actuel. Tapez pour la remplacer ; videz le champ pour revenir en arrière.

La ligne d’indice de chaque option — la ligne grise sous l’option que vous modifiez — se termine par sa clé sous forme de puce. Cliquez sur la puce pour modifier la clé sur place, appuyez sur Entrée ou Échap une fois terminé. Une matrice affiche la puce pour la ligne ou la colonne dont vous modifiez le libellé. Une puce devient ambrée quand le formulaire est publié et que la clé que vous avez tapée déplacerait celle que les automatisations utilisent déjà.

Le même tableau apparaît en lecture seule là où vous câblez une intégration : sous le mapping des champs du webhook, et sous les extraits de demande de la carte Demandes du panneau Partager. Vous pouvez aussi lire toutes les clés d’un coup avec fields.list.

Comment une clé est dérivée

Vous n’avez rien à définir. Tant que vous ne la modifiez pas, une clé est dérivée du titre de la question : les accents sont retirés et des lettres comme ø, æ et ß deviennent o, ae et ss, tout est mis en minuscules, chaque suite de caractères qui n’est ni une lettre ni un chiffre devient un unique tiret bas, les tirets bas en début et en fin sont retirés, et le résultat est coupé à 64 caractères.

Un titre écrit uniquement dans une écriture non latine, comme l’arabe, l’hébreu, le cyrillique, le grec, le chinois ou le japonais, n’a rien à retirer ni à convertir : sa clé est field_ suivi de sa position, et celle d’une option est option_ suivi de sa position. Une fois publiées, ces clés sont aussi stables que les autres, mais elles ne disent rien de la question. Quand une automatisation lit les réponses, définissez vous-même une clé lisible dans le tableau Clés.

Si deux champs devaient se retrouver avec la même clé, formbase tranche dans l’ordre du document en ajoutant _2, _3, et ainsi de suite. Une clé que vous avez définie vous-même l’emporte toujours ; c’est la clé dérivée qui cède.

Définir votre propre clé

Saisissez un nom dans le champ Clé de champ pour remplacer la clé dérivée. Vider le champ revient à la clé dérivée. Les caractères autorisés sont les lettres, les chiffres, _, . et -, jusqu’à 64 caractères — tout le reste est refusé avec « Use only letters, numbers and _ . - (max 64 characters). » Les espaces sont convertis en tirets bas au fur et à mesure de la saisie, donc « contact name » devient contact_name.

Les clés sont sensibles à la casse et doivent être uniques dans un même formulaire. Réutiliser une clé déjà prise par une autre question, un groupe répétable, un champ caché, ou un champ calculé est refusé avec « Another field already uses this key. »

Les clés se figent à la première publication

La première fois que vous publiez, la clé de chaque champ est inscrite dans cette version publiée. Chaque publication suivante reporte les mêmes clés, ce qui signifie :

• Changer le titre ne déplace jamais une clé. Renommez « Company name » en « Legal entity name » et la clé reste company_name. Vos automatisations continuent de fonctionner ; seuls les mots affichés changent.

• Changer le type d’une question ne déplace jamais une clé. Transformer une question texte en liste déroulante garde sa clé — même si la forme de valeur que votre automatisation doit envoyer change avec elle.

• Déplacer une question ne déplace jamais sa clé. La position ne compte que pour le repli positionnel d’un champ sans titre exploitable.

• Dupliquer un bloc donne une nouvelle clé à la copie. Une clé que vous avez définie vous-même est copiée et re-nommée vers le prochain _2 libre ; les clés dérivées sont rendues uniques à la publication.

• Les formulaires créés avant l’existence des clés de champ reçoivent les leurs à leur prochaine publication.

C’est aussi à la publication que les collisions de clés sont détectées, et toutes les deux bloquent la publication plutôt que de renommer silencieusement un champ :

• Deux champs revendiquant une clé — Field key “…” is used by more than one field.

• Une clé que vous avez saisie sur un champ, déjà publiée par un autre champ —

  Field key “…” is already published on “…”. Giving it to “…” would rename that field’s key to “…_2” and break automations using “…”.

  Libérez la clé sur l’un des deux et publiez à nouveau.

Les deux apparaissent à côté du bouton Publier avec tous les autres résultats de la vérification préalable — voir Contrôles de publication.

Quand une clé publiée est sur le point de disparaître

Une clé appartient au champ sur lequel elle a été publiée, pas à son titre. Il y a donc deux façons d’en perdre une sans le vouloir : saisir une clé différente sur un champ publié, ou supprimer une question et en ajouter une nouvelle à sa place. La nouvelle question est un nouveau champ — elle reçoit une clé fraîche dérivée de son propre titre, et l’ancienne clé disparaît.

Rien n’échoue côté formbase quand cela arrive. Le webhook se déclenche toujours et le callback arrive toujours, simplement sans cette réponse, et requests.create commence à refuser l’ancienne clé avec UNKNOWN_FIELD_KEY. La publication vérifie donc cela en premier. Quand une clé que la version en ligne publie n’existerait plus dans la prochaine, la boîte de dialogue de publication et l’indicateur de problème à côté du bouton Publier affichent un avertissement :

La clé de champ "company_name" n’existera plus après cette publication. Les intégrations et demandes qui l’utilisent cesseront de recevoir cette réponse. Un nouveau champ "Company" est publié sous la clé "company". Définissez sa clé de champ sur "company_name" pour qu’elles continuent de fonctionner.

• Pour garder vos automatisations fonctionnelles, ouvrez le tableau Clés, trouvez le champ que l’avertissement nomme, et saisissez l’ancienne clé. L’avertissement disparaît et la clé continue comme si de rien n’était.

• Si vous avez supprimé le champ intentionnellement, publiez quand même — c’est un avertissement, pas une erreur — et mettez à jour les automatisations qui lisent la clé.

• L’avertissement ne nomme un champ que lorsque le choix est évident : le champ dont vous avez retapé la clé, ou l’unique nouveau champ à la place d’un unique champ supprimé. Sinon, il nomme seulement la clé.

• Supprimer un groupe répétable avertit pour la clé du groupe et pour la clé de chaque champ qu’il contient. Publier via form_publish du serveur MCP renvoie les mêmes messages dans warnings.

• Les clés d’option, de ligne et de colonne reçoivent le même traitement : supprimez une option ou retapez sa clé sur un formulaire publié et la publication avertit La clé d’option “pro” de “Plan” n’existera plus après cette publication, en nommant la clé sous laquelle l’option est publiée maintenant quand elle existe encore. La boîte de dialogue de publication liste chaque changement de clé, aux deux niveaux, sous Clés qui changent avec cette publication.

Groupes répétables et champs cachés

Un groupe répétable a sa propre clé, et chaque champ qu’il contient aussi. Les automatisations adressent le groupe dans son ensemble et imbriquent les membres :

{ "contacts": [{ "name": "Ada", "email": "ada@acme.com" }, { "name": "Grace", "email": "grace@acme.com" }] }

Un champ à l’intérieur d’un groupe n’est atteignable que par son groupe — il n’y a pas de name au premier niveau ici, seulement contacts[0].name. Renommer la clé du groupe déplace tout le tableau ; renommer la clé d’un membre ne change que ce nom à l’intérieur de chaque objet.

Le nom de paramètre d’un champ caché est sa clé de champ. C’est la clé que vous placez dans context lors de la création d’une demande, et le même nom que vous utiliseriez comme paramètre d’URL sur un lien public.

Le nom d’un champ calculé est sa clé de champ, et il partage le même jeu de clés du formulaire que tout le reste. Il est en lecture seule : c’est le formulaire qui calcule sa valeur, donc vous ne pouvez jamais en envoyer un — fields.list le liste avec calculated: true et requests.create le refuse dans prefill et context. Vous pouvez en revanche le relire : il arrive dans answers sous son nom, comme answers.total par exemple. Renommer un champ calculé publié renomme sa clé, avec le même avertissement de publication que n’importe quel autre champ.

Clés d’option : les choix à l’intérieur d’une question

Les parties d’une question qu’une réponse nomme reçoivent aussi des clés. Chaque option d’une question radio, liste déroulante, case à cocher, choix d’image ou classement, et chaque ligne et colonne d’une matrice, a une clé d’option : dérivée de son libellé de la même façon qu’une clé de champ est dérivée d’un titre, modifiable, et figée à la publication. Une réponse se lit donc comme un nom des deux côtés :

{ "plan": "pro", "interests": ["billing", "api"], "satisfaction": { "delivery_speed": "very_good" } }

Un workflow bifurque sur answers.plan == “pro” quelle que soit la langue dans laquelle le répondant a répondu, et une demande préremplit un choix avec { "plan": "pro" }. Les clés sont listées par fields.list sous options de chaque champ, ou sous rows et columns d’une matrice, et modifiées dans le tableau Clés ou sur la puce de l’option. Les options de chaque question forment leur propre espace de noms, donc deux questions peuvent toutes deux avoir une option yes, et une ligne et une colonne de matrice peuvent partager une clé. Deux options d’une même question qui dériveraient la même clé sont distinguées avec _2, comme les champs.

La question de décision est un bouton radio ordinaire dont les trois options portent les clés approve, decline et changes ; c’est ce qui fait du outcome d’une demande un ensemble fermé.