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.
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.
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.
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é, Formstep 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.
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. »
> Sur un formulaire publié, le champ Clé de champ vous avertit que le formulaire est publié et que les automatisations utilisant la clé > actuelle vont se casser. Rien ne vous en empêche, mais chaque workflow qui préremplit ou lit cette clé cesse de correspondre dès que > vous publiez le changement. Mettez à jour l'automatisation dans la foulée. La publication vous{' '} > avertit à nouveau avant que le changement ne soit en ligne. >
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 :
company_name. Vos automatisations continuent de fonctionner ; seuls les mots affichés changent.
_2 libre ; les clés dérivées sont rendues uniques à la 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 :
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.
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é Formstep 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 :
form_publish du serveur MCP renvoie les mêmes messages dans warnings.
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.
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é.