Feldschlüssel

Warum es sie gibt

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.

Wo du sie findest

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.

1. 1

   Öffnen

   Klicke auf das Schlüssel-Symbol in der Editor-Symbolleiste (oder Schlüssel im Überlaufmenü der Symbolleiste bei schmalem Fenster). Die Tabelle öffnet sich als Seitenfenster über dem ganzen Formular.

2. 2

   Den Platzhalter lesen

   Ist ein Eingabefeld leer, zeigt sein Platzhalter den Schlüssel, auf den das Feld tatsächlich hört — den Schlüssel, unter dem es veröffentlicht wurde, falls das Formular live ist, sonst den aus dem aktuellen Titel oder Label abgeleiteten Schlüssel. Tippen überschreibt ihn; das Eingabefeld leeren geht zurück.

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.

Wie ein Schlüssel abgeleitet wird

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 formbase 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.

Deinen eigenen Schlüssel setzen

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.”

Schlüssel frieren bei der ersten Veröffentlichung ein

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:

• Umbenennen verschiebt nie einen Schlüssel. Benenne “Company name” in “Legal entity name” um, und der Schlüssel bleibt company_name. Deine Automationen funktionieren weiter; nur die Wörter auf der Seite ändern sich.

• Den Typ einer Frage zu ändern verschiebt nie einen Schlüssel. Eine Textfrage in ein Dropdown umzuwandeln behält ihren Schlüssel — auch wenn sich die Wertform ändert, die deine Automation senden muss.

• Eine Frage zu verschieben verschiebt nie ihren Schlüssel. Die Position spielt nur beim positionsbasierten Fallback für ein Feld ohne brauchbaren Titel eine Rolle.

• Einen Block zu duplizieren gibt der Kopie einen neuen Schlüssel. Ein selbst gesetzter Schlüssel wird kopiert und auf das nächste freie _2 umbenannt; abgeleitete Schlüssel werden bei der Veröffentlichung eindeutig gemacht.

• Formulare, die vor Feldschlüsseln gebaut wurden, bekommen ihre bei der nächsten Veröffentlichung.

Auch bei der Veröffentlichung werden Schlüsselkollisionen entdeckt, und beide stoppen die Veröffentlichung, statt ein Feld stillschweigend umzubenennen:

• Zwei Felder beanspruchen denselben Schlüssel — Field key “…” is used by more than one field.

• Ein Schlüssel, den du auf ein Feld getippt hast, den ein anderes Feld bereits veröffentlicht hat —

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

  Gib den Schlüssel bei einem der beiden frei und veröffentliche erneut.

Beide erscheinen neben dem Veröffentlichen-Button, zusammen mit jedem anderen Pre-Flight-Befund — siehe Veröffentlichungsprüfungen.

Wenn ein veröffentlichter Schlüssel gleich verschwindet

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 formbase-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:

Feldschlüssel "company_name" wird nach dieser Veröffentlichung nicht mehr existieren. Integrationen und Anfragen, die ihn verwenden, erhalten diese Antwort nicht mehr. Ein neues Feld "Company" wird als "company" veröffentlicht. Setze seinen Feldschlüssel auf "company_name", damit sie weiter funktionieren.

• Damit deine Automationen weiter funktionieren, öffne die Schlüssel-Tabelle, finde das Feld, das die Warnung nennt, und tippe den alten Schlüssel ein. Die Warnung verschwindet, und der Schlüssel läuft weiter, als wäre nichts gewesen.

• Hast du das Feld absichtlich entfernt, veröffentliche trotzdem — es ist eine Warnung, kein Fehler — und aktualisiere die Automationen, die den Schlüssel lesen.

• Die Warnung nennt ein Feld nur, wenn die Wahl eindeutig ist: das Feld, dessen Schlüssel du neu getippt hast, oder das einzige neue Feld, das dort steht, wo ein einzelnes gelöschtes stand. Sonst nennt sie nur den Schlüssel.

• Eine Wiederholungsgruppe zu löschen warnt für den Schlüssel der Gruppe und für den Schlüssel jedes Felds darin. Das Veröffentlichen über form_publish des MCP-Servers liefert dieselben Meldungen in warnings zurück.

• Options-, Zeilen- und Spaltenschlüssel bekommen dieselbe Behandlung: Löschst du eine Option oder änderst ihren Schlüssel in einem veröffentlichten Formular, warnt das Veröffentlichen Der Optionsschlüssel „pro” von „Plan” wird nach dieser Veröffentlichung nicht mehr existieren, und nennt den Schlüssel, unter dem die Option jetzt veröffentlicht wird, wenn sie noch existiert. Der Veröffentlichungsdialog listet jede Schlüsseländerung, auf beiden Ebenen, unter Schlüssel, die sich mit dieser Veröffentlichung ändern.

Wiederholungsgruppen und versteckte Felder

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.

Optionsschlüssel: die Auswahlmöglichkeiten in einer Frage

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.