Zonder veldsleutels moet een automatisering je vragen aanspreken via interne id's die voor niemand iets betekenen — en een webhookpayload komt daar vol mee binnen. Met veldsleutels lezen beide kanten hetzelfde:
``` { "company_name": "Acme", "employees": 120, "contacts": [{ "name": "Ada" }] } ```
Veldsleutels worden op twee plaatsen gebruikt: prefill, context en readonly bij het aanmaken van
een aanvraag; en de kaarten answers en display in elke callback en elke webhook-payload.
Elke sleutel die het formulier publiceert, staat op één plek: de tabel Sleutels — elk veld, en onder een keuzevraag elke
optie, onder een matrix elke rij en kolom. De tabel eindigt met een voorbeeld van het answers-object dat je callback zal
bevatten, met jouw sleutels erin.
De hintregel van elke optie — de grijze regel onder de optie die je bewerkt — eindigt met zijn sleutel als chip. Klik op de chip om de sleutel direct te bewerken, druk op Enter of Escape als je klaar bent. Bij een matrix toont de chip voor de rij of kolom waarvan je het label bewerkt. Een chip kleurt amber wanneer het formulier gepubliceerd is en de sleutel die je typt de sleutel zou verplaatsen die automatiseringen al gebruiken.
Dezelfde tabel verschijnt alleen-lezen waar je een integratie aansluit: onder de veldkoppeling van de webhook, en onder de
aanvraagfragmenten in de kaart Aanvragen van het deelvenster. Je kunt ook alle sleutels tegelijk uitlezen met fields.list.
Je hoeft niets in te stellen. Totdat je hem bewerkt, wordt een sleutel afgeleid van de titel van de vraag: accenten worden opgevouwen en letters als ø, æ en ß worden o, ae en ss, alles wordt kleine letters, elke reeks tekens die geen letter of cijfer is wordt één underscore, voorloop- en volgunderscores vervallen, en het resultaat wordt afgekapt op 64 tekens.
Een titel die alleen in een niet-Latijns schrift is geschreven, zoals Arabisch, Hebreeuws, Cyrillisch, Grieks, Chinees of Japans, heeft
niets om op te vouwen. Zijn sleutel is daarom field_ plus zijn positie, en die van een optie is option_ plus
haar positie. Zodra ze zijn gepubliceerd, zijn deze sleutels even stabiel als elke andere, maar ze zeggen niets over de vraag. Leest een
automatisering de antwoorden, stel dan zelf een leesbare sleutel in de tabel Sleutels in.
Als twee velden met dezelfde sleutel zouden eindigen, verbreekt Formstep de gelijkstand in documentvolgorde door _2,{' '}
_3, enzovoort toe te voegen. Een sleutel die je zelf hebt ingesteld wint altijd zijn claim, en de afgeleide sleutel wijkt.
Typ een naam in het invoerveld Veldsleutel om de afgeleide sleutel te overschrijven. Het invoerveld leegmaken gaat terug naar de afgeleide
sleutel. Toegestane tekens zijn letters, cijfers, _, . en -, tot 64 tekens — al het andere wordt
geweigerd met "Gebruik alleen letters, cijfers en _ . - (max 64 tekens)." Spaties worden tijdens het typen omgezet in
underscores, dus "contact name" wordt contact_name.
Sleutels zijn hoofdlettergevoelig en moeten uniek zijn binnen één formulier. Hergebruik van een sleutel die al door een andere vraag, herhaalgroep, verborgen veld of berekend veld wordt gebruikt, wordt geweigerd met "Een ander veld gebruikt deze sleutel al."
> Bij een gepubliceerd formulier waarschuwt het invoerveld Veldsleutel dat het formulier gepubliceerd is en dat automatiseringen die de > huidige sleutel gebruiken zullen breken. Niets houdt je tegen, maar elke workflow die deze sleutel vooraf invult of uitleest, stopt met > matchen zodra je de wijziging publiceert. Werk de automatisering in dezelfde sessie bij. Publiceren{' '} > waarschuwt je nogmaals voordat de wijziging live gaat. >
De eerste keer dat je publiceert, wordt de sleutel van elk veld vastgelegd in die gepubliceerde versie. Elke latere publicatie draagt dezelfde sleutels over, wat betekent:
company_name. Je automatiseringen blijven werken; alleen de tekst op de pagina verandert.
_2; afgeleide sleutels worden uniek gemaakt bij publicatie.
Publiceren is ook het moment waarop sleutelbotsingen worden opgemerkt, en beide stoppen het publiceren in plaats van een veld stilzwijgend te hernoemen:
Beide verschijnen naast de knop Publiceren, samen met elke andere pre-flight-bevinding — zie{' '} Publicatiecontroles.
Een sleutel hoort bij het veld waarop hij is gepubliceerd, niet bij de titel ervan. Er zijn dus twee manieren om er ongewild een kwijt te raken: een andere sleutel typen op een gepubliceerd veld, of{' '} een vraag verwijderen en er een nieuwe voor in de plaats zetten. De nieuwe vraag is een nieuw veld — het krijgt een verse sleutel, afgeleid van zijn eigen titel, en de oude sleutel is verdwenen.
Aan de kant van Formstep gaat daarbij niets mis. De webhook vuurt nog steeds af en de callback komt nog steeds binnen, alleen zonder dat
antwoord, en requests.create begint de oude sleutel te weigeren met UNKNOWN_FIELD_KEY. Daarom controleert
publiceren dit vooraf. Wanneer een sleutel die de live versie publiceert, in de volgende versie niet meer zou bestaan, tonen het
publicatievenster en de publicatie-indicator naast de knop Publiceren een waarschuwing:
form_publish geeft dezelfde meldingen terug in warnings.
Een herhaalgroep heeft een eigen sleutel, en elk veld erbinnen ook. Automatiseringen spreken de groep als geheel aan en nesten de leden:
``` { "contacts": [{ "name": "Ada", "email": "ada@acme.com" }, { "name": "Grace", "email": "grace@acme.com" }] } ```
Een veld binnen een groep is alleen bereikbaar via zijn groep — er is hier geen name op het hoogste niveau, alleen{' '}
contacts[0].name. Hernoem de sleutel van de groep en de hele array verplaatst mee; hernoem de sleutel van één lid en alleen
die naam binnen elk object verandert.
De parameternaam van een verborgen veld is zijn veldsleutel. Dat is de sleutel die je in{' '}
context zet bij het aanmaken van een aanvraag, en dezelfde naam die je in een URL-parameter op een openbare link zou
gebruiken.
De naam van een berekend veld is zijn veldsleutel, en het deelt de ene verzameling
sleutels van het formulier met al het andere. Het is alleen-lezen: het formulier berekent zelf de waarde, dus je kunt er nooit een
versturen — fields.list vermeldt het met calculated: true en requests.create weigert het in{' '}
prefill en context. Je leest het wel terug: het komt binnen in answers onder zijn naam (
answers.total). Een gepubliceerd berekend veld hernoemen hernoemt zijn sleutel, met dezelfde publicatiewaarschuwing als elk
ander veld.
De onderdelen van een vraag die een antwoord benoemt, krijgen ook sleutels. Elke optie van een radio-, select-, checkbox-, afbeeldingskeuze- of ranking-vraag, en elke rij en kolom van een matrix, heeft een optiesleutel: afgeleid van zijn label op dezelfde manier als een veldsleutel wordt afgeleid van een titel, bewerkbaar, en bevroren bij publicatie. Zo leest een antwoord als een naam aan beide kanten:
``` { "plan": "pro", "interests": ["billing", "api"], "satisfaction": { "delivery_speed": "very_good" } } ```
Een workflow vertakt op answers.plan == "pro", ongeacht in welke taal de respondent antwoordde, en een aanvraag vult een
keuze vooraf in met {'{ "plan": "pro" }'}. De sleutels worden opgesomd door fields.list onder de{' '}
options van elk veld, of de rows en columns van een matrix, en bewerkt in de{' '}
Sleuteltabel of op de chip van de optie. De opties van elke vraag vormen hun eigen naamruimte, dus twee vragen mogen
allebei een yes hebben, en een rij en kolom van een matrix mogen dezelfde sleutel delen. Twee opties van één vraag die
dezelfde sleutel zouden afleiden, worden uit elkaar gehouden met _2, net als velden.
De beslissingsvraag is een gewone radio waarvan de drie opties de sleutels{' '}
approve, decline en changes dragen; dat is wat de outcome van een aanvraag een
gesloten verzameling maakt.