Sin claves de campo, una automatización tendría que dirigirse a tus preguntas por ids internos que no significan nada para nadie — y un payload de webhook llegaría lleno de ellos. Con claves de campo, ambos lados leen lo mismo:
``` { "company_name": "Acme", "employees": 120, "contacts": [{ "name": "Ada" }] } ```
Las claves de campo se usan en dos sitios: prefill, context y readonly al crear una solicitud; y
los mapas answers y display de cada callback y cada payload de webhook.
Cada clave que publica el formulario vive en un solo lugar, la tabla de Claves: cada campo, y bajo una pregunta de
elección cada opción, bajo una matriz cada fila y columna. Termina con una vista previa del objeto answers que llevará tu
callback, con tus claves dentro.
La fila de ayuda de cada opción — la línea gris bajo la opción que estás editando — termina con su clave como un chip. Haz clic en el chip para editar la clave en el momento, pulsa Enter o Escape al terminar. Una matriz muestra el chip para la fila o columna cuya etiqueta estás editando. Un chip se pone ámbar cuando el formulario está publicado y la clave que escribiste movería la que ya usan las automatizaciones.
La misma tabla aparece de solo lectura donde conectas una integración: bajo el mapeo de campos del webhook, y bajo los fragmentos de
solicitud de la tarjeta de Solicitudes de la hoja de compartir. fields.list también te deja leer todas las claves a la vez.
No tienes que configurar nada. Hasta que la edites, una clave se deriva del título de la pregunta: se eliminan los acentos y letras como ø, æ y ß pasan a ser o, ae y ss, todo se pone en minúsculas, cada tramo de caracteres que no sea una letra o un dígito se convierte en un único guion bajo, los guiones bajos al principio y al final se eliminan, y el resultado se recorta a 64 caracteres.
Un título escrito solo en una escritura no latina, como árabe, hebreo, cirílico, griego, chino o japonés, no tiene nada que normalizar,
así que su clave es field_ más su posición, y la de una opción es option_ más su posición. Una vez publicadas,
estas claves son tan estables como cualquier otra, pero no dicen nada sobre la pregunta. Cuando una automatización lea las respuestas,
fija tú mismo una clave legible en la tabla de Claves.
Si dos campos acabarían con la misma clave, Formstep resuelve el empate por orden en el documento añadiendo _2,{' '}
_3, y así sucesivamente. Una clave que fijas tú siempre gana su reclamación, y la derivada cede.
Escribe un nombre en el campo Clave de campo para anular la derivada. Si lo vacías, vuelve a la clave derivada. Los caracteres permitidos
son letras, dígitos, _, . y -, hasta 64 caracteres — cualquier otra cosa se rechaza con{' '}
"Usa solo letras, números y _ . - (máximo 64 caracteres)." Los espacios se convierten en guiones bajos mientras escribes, así que
"nombre de contacto" se convierte en nombre_de_contacto.
Las claves distinguen mayúsculas de minúsculas y deben ser únicas dentro de un mismo formulario. Reutilizar una ya usada por otra pregunta, grupo repetible, campo oculto o campo calculado se rechaza con "Otro campo ya usa esta clave."
> En un formulario publicado, el campo Clave de campo te avisa de que el formulario está publicado y de que las automatizaciones que usan > la clave actual dejarán de funcionar. Nada te lo impide, pero cada flujo de trabajo que precompleta o lee esa clave deja de coincidir en > el momento en que publicas el cambio. Actualiza la automatización en la misma sesión. Publicar{' '} > te avisa de nuevo antes de que el cambio entre en vigor. >
La primera vez que publicas, la clave de cada campo queda escrita en esa versión publicada. Cada publicación posterior arrastra las mismas claves, lo que significa:
company_name. Tus automatizaciones siguen funcionando; solo cambian las palabras en la página.
_2 libre; las claves derivadas se hacen únicas al publicar.
Publicar es también donde se detectan los conflictos de claves, y ambos detienen la publicación en lugar de renombrar un campo en silencio:
Ambos aparecen junto al botón Publicar con cualquier otro hallazgo previo — consulta{' '} Comprobaciones de publicación.
Una clave pertenece al campo en el que se publicó, no a su título. Así que hay dos formas de perderla sin querer: escribir una clave distinta en un campo publicado, o eliminar una pregunta y añadir una nueva en su lugar. La pregunta nueva es un campo nuevo — recibe una clave nueva derivada de su propio título, y la clave antigua desaparece.
Nada falla del lado de Formstep cuando ocurre esto. El webhook se sigue disparando y el callback sigue llegando, solo que sin esa
respuesta, y requests.create empieza a rechazar la clave antigua con UNKNOWN_FIELD_KEY. Por eso publicar lo
comprueba primero. Cuando una clave que publica la versión activa no existiría en la siguiente, el diálogo de publicación y el indicador
de incidencias junto al botón Publicar muestran una advertencia:
form_publish del servidor MCP devuelve los mismos mensajes en warnings.
Un grupo repetible tiene su propia clave, y también cada campo dentro de él. Las automatizaciones se dirigen al grupo como un todo y anidan los miembros:
``` { "contacts": [{ "name": "Ada", "email": "ada@acme.com" }, { "name": "Grace", "email": "grace@acme.com" }] } ```
Un campo dentro de un grupo solo es accesible a través de su grupo — aquí no hay ningún name de nivel superior, solo{' '}
contacts[0].name. Renombra la clave del grupo y todo el array se mueve; renombra la clave de un miembro y solo cambia ese
nombre dentro de cada objeto.
El nombre de parámetro de un campo oculto es su clave de campo. Esa es la clave que pones
en context al crear una solicitud, y el mismo nombre que usarías en un parámetro de URL en un enlace público.
El nombre de un campo calculado es su clave de campo, y comparte el mismo conjunto de
claves del formulario con todo lo demás. Es de solo lectura: el formulario calcula su valor, así que nunca puedes enviarlo —{' '}
fields.list lo lista con calculated: true y requests.create lo rechaza en prefill y en{' '}
context. Sí puedes leerlo de vuelta: llega en answers bajo su nombre (answers.total). Renombrar un
campo calculado publicado renombra su clave, con la misma advertencia de publicación que cualquier otro campo.
Las partes de una pregunta que una respuesta nombra también tienen claves. Cada opción de una pregunta de radio, desplegable, casillas, elección con imágenes o ranking, y cada fila y columna de una matriz, tiene una clave de opción: derivada de su etiqueta del mismo modo en que se deriva una clave de campo a partir de un título, editable, y congelada al publicar. Así una respuesta se lee como un nombre en los dos lados:
``` { "plan": "pro", "interests": ["billing", "api"], "satisfaction": { "delivery_speed": "very_good" } } ```
Un flujo de trabajo ramifica sobre answers.plan == "pro" sea cual sea el idioma en que respondió el encuestado, y una
solicitud precompleta una elección con {'{ "plan": "pro" }'}. Las claves las lista fields.list bajo las{' '}
options de cada campo, o bajo las rows y columns de una matriz, y se editan en la{' '}
tabla de Claves o en el chip de la opción. Las opciones de cada pregunta son su propio espacio de nombres, así que
dos preguntas pueden tener ambas un yes, y una fila y una columna de una matriz pueden compartir clave. Dos opciones de una
misma pregunta que derivarían la misma clave se distinguen con _2, igual que los campos.
La pregunta de decisión es un radio normal cuyas tres opciones llevan las claves{' '}
approve, decline y changes; eso es lo que hace que el outcome de una solicitud sea un
conjunto cerrado.