Ohne Feldschlüssel müsste eine Automation deine Fragen über interne IDs ansprechen, die niemandem etwas sagen — und ein Webhook-Payload käme voll davon an. Mit Feldschlüsseln lesen sich beide Seiten gleich:
``` { "company_name": "Acme", "employees": 120, "contacts": [{ "name": "Ada" }] } ```
Feldschlüssel werden an zwei Stellen verwendet: in prefill, context und readonly beim Erstellen
eines Requests; und in den answers- und display-Maps in jedem Callback und jedem Webhook-Payload.
Jeder Schlüssel, den das Formular veröffentlicht, lebt an einem Ort, der Schlüssel-Tabelle: jedes Feld, und unter einer
Auswahlfrage jede Option, unter einer Matrix jede Zeile und Spalte. Sie endet mit einer Vorschau des answers-Objekts, das
dein Callback tragen wird, mit deinen Schlüsseln darin.
Die Hinweiszeile jeder Option — die graue Zeile unter der Option, die du bearbeitest — endet mit ihrem Schlüssel als Chip. Klicke auf den Chip, um den Schlüssel direkt zu bearbeiten, drücke Enter oder Escape, wenn du fertig bist. Eine Matrix zeigt den Chip für die Zeile oder Spalte, deren Label du bearbeitest. Ein Chip wird gelb, wenn das Formular veröffentlicht ist und der eingegebene Schlüssel den verschieben würde, den Automationen bereits verwenden.
Dieselbe Tabelle erscheint schreibgeschützt, wo du eine Integration verdrahtest: unter der Feldzuordnung des Webhooks und unter den
Request-Snippets in der Requests-Karte des Share-Sheets. Du kannst auch alle Schlüssel auf einmal mit fields.list auslesen.
Du musst nichts einstellen. Bis du ihn bearbeitest, wird ein Schlüssel aus dem Titel der Frage abgeleitet: Akzente werden aufgelöst und Buchstaben wie ø, æ und ß werden zu o, ae und ss, alles wird kleingeschrieben, jede Folge von Zeichen, die weder Buchstabe noch Ziffer sind, wird zu einem einzelnen Unterstrich, führende und abschließende Unterstriche fallen weg, und das Ergebnis wird auf 64 Zeichen gekürzt.
Ein Titel, der nur in einer nicht-lateinischen Schrift geschrieben ist, etwa Arabisch, Hebräisch, Kyrillisch, Griechisch, Chinesisch oder
Japanisch, lässt sich nicht auflösen. Sein Schlüssel ist deshalb field_ plus seine Position, der einer Option
option_ plus ihre Position. Nach der Veröffentlichung sind diese Schlüssel so stabil wie jeder andere, sagen aber nichts über
die Frage aus. Liest eine Automation die Antworten, setze selbst einen lesbaren Schlüssel in der Schlüssel-Tabelle.
Würden zwei Felder auf denselben Schlüssel kommen, löst Formstep den Konflikt in Dokumentreihenfolge auf, indem _2,{' '}
_3 und so weiter angehängt wird. Ein selbst gesetzter Schlüssel gewinnt immer seinen Anspruch, der abgeleitete weicht.
Gib einen Namen ins Feldschlüssel-Eingabefeld ein, um den abgeleiteten zu überschreiben. Leerst du das Feld, wird wieder der abgeleitete
Schlüssel verwendet. Erlaubte Zeichen sind Buchstaben, Ziffern, _, . und -, bis zu 64 Zeichen —
alles andere wird abgelehnt mit "Use only letters, numbers and _ . - (max 64 characters)." Leerzeichen werden beim Tippen in
Unterstriche umgewandelt, sodass aus "contact name" contact_name wird.
Schlüssel unterscheiden Groß- und Kleinschreibung und müssen innerhalb eines Formulars eindeutig sein. Einen bereits von einer anderen Frage, Wiederholungsgruppe, einem versteckten Feld oder berechneten Feld belegten Schlüssel wiederzuverwenden wird abgelehnt mit{' '} "Another field already uses this key."
> Bei einem veröffentlichten Formular warnt das Feldschlüssel-Eingabefeld dich, dass das Formular veröffentlicht ist und Automationen, die > den aktuellen Schlüssel verwenden, kaputtgehen. Nichts hält dich auf, aber jeder Workflow, der diesen Schlüssel vorausfüllt oder liest, > hört in dem Moment auf zu passen, in dem du die Änderung veröffentlichst. Aktualisiere die Automation in derselben Sitzung. Die > Veröffentlichung warnt dich erneut, bevor die Änderung live geht. >
Beim ersten Veröffentlichen wird der Schlüssel jedes Felds in diese veröffentlichte Version geschrieben. Jede spätere Veröffentlichung trägt dieselben Schlüssel weiter, was bedeutet:
company_name. Deine Automationen funktionieren weiter; nur die Wörter auf der Seite ändern sich.
_2 umbenannt; abgeleitete Schlüssel werden bei der Veröffentlichung eindeutig gemacht.
Auch bei der Veröffentlichung werden Schlüsselkollisionen entdeckt, und beide stoppen die Veröffentlichung, statt ein Feld stillschweigend umzubenennen:
Beide erscheinen neben dem Veröffentlichen-Button, zusammen mit jedem anderen Pre-Flight-Befund — siehe{' '} Veröffentlichungsprüfungen.
Ein Schlüssel gehört zu dem Feld, auf dem er veröffentlicht wurde, nicht zu seinem Titel. Es gibt also zwei Wege, einen ungewollt zu verlieren: einen anderen Schlüssel auf ein veröffentlichtes Feld tippen, oder{' '} eine Frage löschen und an ihrer Stelle eine neue hinzufügen. Die neue Frage ist ein neues Feld — sie bekommt einen frischen, aus ihrem eigenen Titel abgeleiteten Schlüssel, und der alte Schlüssel ist weg.
Auf Formstep-Seite schlägt dabei nichts fehl. Der Webhook feuert weiterhin und der Callback kommt weiterhin an, nur ohne diese Antwort,
und requests.create fängt an, den alten Schlüssel mit UNKNOWN_FIELD_KEY abzulehnen. Deshalb prüft die
Veröffentlichung das zuerst. Würde ein Schlüssel, den die aktuelle Version veröffentlicht, in der nächsten nicht mehr existieren, zeigen
der Veröffentlichungsdialog und die Problemanzeige neben dem Veröffentlichen-Button eine Warnung:
form_publish des MCP-Servers liefert dieselben Meldungen in warnings zurück.
Eine Wiederholungsgruppe hat ihren eigenen Schlüssel, ebenso jedes Feld darin. Automationen sprechen die Gruppe als Ganzes an und verschachteln die Mitglieder:
``` { "contacts": [{ "name": "Ada", "email": "ada@acme.com" }, { "name": "Grace", "email": "grace@acme.com" }] } ```
Ein Feld innerhalb einer Gruppe ist nur über seine Gruppe erreichbar — hier gibt es kein name auf oberster Ebene, nur{' '}
contacts[0].name. Benennst du den Schlüssel der Gruppe um, verschiebt sich das ganze Array; benennst du den Schlüssel eines
Mitglieds um, ändert sich nur dieser Name innerhalb jedes Objekts.
Der Parametername eines versteckten Felds ist sein Feldschlüssel. Das ist der Schlüssel,
den du beim Erstellen eines Requests in context angibst — derselbe Name, den du auch als URL-Parameter bei einem öffentlichen
Link verwenden würdest.
Der Name eines berechneten Felds ist sein Feldschlüssel, und es teilt sich das eine
Schlüssel-Set des Formulars mit allem anderen. Es ist nur lesbar: Das Formular ermittelt seinen Wert selbst, du kannst also nie einen
senden — fields.list listet es mit calculated: true auf, und requests.create lehnt es in{' '}
prefill und context ab. Zurücklesen kannst du es aber: Es erscheint in answers unter seinem Namen (
answers.total). Ein veröffentlichtes berechnetes Feld umzubenennen benennt auch seinen Schlüssel um, mit derselben
Veröffentlichungswarnung wie bei jedem anderen Feld.
Auch die Teile einer Frage, die eine Antwort benennt, bekommen Schlüssel. Jede Option eines Radio-, Auswahl-, Checkbox-, Bildauswahl- oder Ranking-Fragen, und jede Zeile und Spalte einer Matrix, hat einen Optionsschlüssel: abgeleitet aus ihrem Label auf dieselbe Weise, wie ein Feldschlüssel aus einem Titel abgeleitet wird, bearbeitbar und bei der Veröffentlichung eingefroren. So liest sich eine Antwort auf beiden Seiten als Name:
``` { "plan": "pro", "interests": ["billing", "api"], "satisfaction": { "delivery_speed": "very_good" } } ```
Ein Workflow verzweigt auf answers.plan == "pro", in welcher Sprache die befragte Person auch geantwortet hat, und ein
Request füllt eine Auswahl mit {'{ "plan": "pro" }'} vor. Die Schlüssel werden von fields.list unter den{' '}
options jedes Felds aufgeführt, oder den rows und columns einer Matrix, und in der{' '}
Schlüsseltabelle oder am Chip der Option bearbeitet. Die Optionen jeder Frage sind ihr eigener Namensraum, sodass
zwei Fragen beide ein yes haben können, und eine Zeile und Spalte einer Matrix sich einen Schlüssel teilen können. Zwei
Optionen einer Frage, die denselben Schlüssel ableiten würden, werden mit _2 auseinandergehalten, wie bei Feldern.
Die Entscheidungsfrage ist ein gewöhnliches Radio, dessen drei Optionen die Schlüssel{' '}
approve, decline und changes tragen; das macht das outcome eines Requests zu einer
geschlossenen Menge.