Veldsleutels

Waarom ze bestaan

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.

Waar je ze vindt

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.

1. 1

   Open het

   Klik op het sleutelicoon in de werkbalk van de editor (of Sleutels in het overloopmenu van de werkbalk op een smal venster). De tabel opent in een zijpaneel over het hele formulier.

2. 2

   Lees de placeholder

   Als een invoerveld leeg is, toont de placeholder de sleutel waarop het veld daadwerkelijk reageert — de sleutel waaronder het is gepubliceerd als het formulier live is, anders de sleutel afgeleid van de huidige titel of het label. Typ om hem te overschrijven; maak het invoerveld leeg om terug te gaan.

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.

Hoe een sleutel wordt afgeleid

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

Je eigen sleutel instellen

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

Sleutels bevriezen bij de eerste publicatie

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:

• Hernoemen verplaatst nooit een sleutel. Hernoem “Company name” naar “Legal entity name” en de sleutel blijft company_name. Je automatiseringen blijven werken; alleen de tekst op de pagina verandert.

• Het type van een vraag wijzigen verplaatst nooit een sleutel. Een tekstvraag omzetten naar een keuzelijst behoudt de sleutel — al verandert daarmee wel de waardevorm die je automatisering moet versturen.

• Een vraag verplaatsen verplaatst zijn sleutel nooit. Positie is alleen relevant voor de positionele terugval bij een veld zonder bruikbare titel.

• Een blok dupliceren geeft de kopie een nieuwe sleutel. Een zelf ingestelde sleutel wordt gekopieerd en herzien naar de volgende vrije _2; afgeleide sleutels worden uniek gemaakt bij publicatie.

• Formulieren gebouwd voordat veldsleutels bestonden krijgen hun sleutels bij hun volgende publicatie.

Publiceren is ook het moment waarop sleutelbotsingen worden opgemerkt, en beide stoppen het publiceren in plaats van een veld stilzwijgend te hernoemen:

• Twee velden die één sleutel claimen — Veldsleutel “…” wordt door meer dan één veld gebruikt.

• Een sleutel die je op één veld hebt getypt terwijl een ander veld die al publiceerde —

  Veldsleutel “…” is al gepubliceerd op “…”. Die aan “…” geven zou de sleutel van dat veld hernoemen naar “…_2” en automatiseringen die “…” gebruiken breken.

  Maak de sleutel op een van de twee vrij en publiceer opnieuw.

Beide verschijnen naast de knop Publiceren, samen met elke andere pre-flight-bevinding — zie Publicatiecontroles.

Wanneer een gepubliceerde sleutel op het punt staat te verdwijnen

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

Veldsleutel "company_name" bestaat na deze publicatie niet meer. Integraties en aanvragen die deze gebruiken, ontvangen dat antwoord niet meer. Een nieuw veld "Company" wordt gepubliceerd als "company". Zet de veldsleutel op "company_name" om ze te laten werken.

• Om je automatiseringen te laten werken open je de tabel Sleutels, zoek je het veld dat de waarschuwing noemt, en typ je de oude sleutel. De waarschuwing verdwijnt en de sleutel gaat verder alsof er niets is gebeurd.

• Als je het veld met opzet hebt verwijderd, publiceer dan gewoon — het is een waarschuwing, geen fout — en werk de automatiseringen bij die de sleutel lezen.

• De waarschuwing noemt een veld alleen als de keuze duidelijk is: het veld waarvan je de sleutel hebt herschreven, of het enige nieuwe veld dat staat waar één verwijderd veld stond. Anders noemt hij alleen de sleutel.

• Een herhaalgroep verwijderen geeft een waarschuwing voor de sleutel van de groep en voor de sleutel van elk veld erbinnen. Publiceren via de MCP-server’s form_publish geeft dezelfde meldingen terug in warnings.

• Optie-, rij- en kolomsleutels krijgen dezelfde behandeling: een optie verwijderen of zijn sleutel herschrijven op een gepubliceerd formulier laat publiceren waarschuwen met Optiesleutel “pro” van “Plan” bestaat na deze publicatie niet meer, waarbij de sleutel wordt genoemd waaronder de optie nu publiceert als hij nog bestaat. Het publicatievenster somt elke sleutelwijziging op, op beide niveaus, onder Sleutels die deze publicatie wijzigt.

Herhaalgroepen en verborgen velden

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.

Optiesleutels: de keuzes binnen een vraag

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.