Claves de campo

Por qué existen

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.

Dónde encontrarlas

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.

1. 1

   Ábrela

   Haz clic en el icono de claves de la barra de herramientas del editor (o en Claves, dentro del menú de desbordamiento de la barra de herramientas en una ventana estrecha). La tabla se abre en una hoja lateral sobre todo el formulario.

2. 2

   Lee el marcador de posición

   Cuando una entrada está vacía, su marcador de posición muestra la clave con la que responde el campo realmente — la clave con la que se publicó si el formulario está activo, o si no, la clave derivada de su título o etiqueta actual. Escribe para anularla; vacía la entrada para volver atrás.

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.

Cómo se deriva una clave

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

Fijar tu propia clave

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

Las claves se congelan en la primera publicación

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:

• Cambiar el título nunca mueve una clave. Renombra “Company name” a “Legal entity name” y la clave sigue siendo company_name. Tus automatizaciones siguen funcionando; solo cambian las palabras en la página.

• Cambiar el tipo de una pregunta nunca mueve una clave. Convertir una pregunta de texto en un desplegable conserva su clave — aunque la forma de valor que tu automatización debe enviar cambia con ella.

• Mover una pregunta nunca mueve su clave. La posición solo importa para el recurso posicional en un campo que no tiene un título utilizable.

• Duplicar un bloque le da a la copia una nueva clave. Una clave que fijaste tú se copia y se renombra al siguiente _2 libre; las claves derivadas se hacen únicas al publicar.

• Los formularios creados antes de que existieran las claves de campo reciben las suyas en su siguiente publicación.

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:

• Dos campos que reclaman una misma clave — La clave de campo “…” la usa más de un campo.

• Una clave que escribiste en un campo y que otro campo ya tenía publicada —

  La clave de campo “…” ya está publicada en “…”. Dársela a “…” renombraría la clave de ese campo a “…_2” y rompería las automatizaciones que usan “…”.

  Libera la clave en uno de los dos y publica de nuevo.

Ambos aparecen junto al botón Publicar con cualquier otro hallazgo previo — consulta Comprobaciones de publicación.

Cuando una clave publicada está a punto de desaparecer

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

La clave de campo "company_name" dejará de existir después de esta publicación. Las integraciones y solicitudes que la usan dejarán de recibir esa respuesta. Un nuevo campo "Company" se publica como "company". Pon su clave de campo en "company_name" para que sigan funcionando.

• Para que tus automatizaciones sigan funcionando, abre la tabla de Claves, busca el campo que nombra la advertencia, y escribe la clave antigua. La advertencia desaparece y la clave sigue como si nada hubiera pasado.

• Si eliminaste el campo a propósito, publica de todos modos — es una advertencia, no un error — y actualiza las automatizaciones que leen esa clave.

• La advertencia nombra un campo solo cuando la elección es obvia: el campo cuya clave reescribiste, o el único campo nuevo que ocupa el lugar de un único campo eliminado. En caso contrario, solo nombra la clave.

• Eliminar un grupo repetible advierte tanto de la clave del grupo como de la clave de cada campo que contiene. Publicar a través de form_publish del servidor MCP devuelve los mismos mensajes en warnings.

• Las claves de opción, fila y columna reciben el mismo trato: eliminar una opción o volver a escribir su clave en un formulario publicado hace que publicar te avise La clave de opción “pro” de “Plan” dejará de existir después de esta publicación, indicando la clave con la que se publica la opción ahora cuando todavía existe. El diálogo de publicación lista cada cambio de clave, en ambos niveles, bajo Claves que cambian en esta publicación.

Grupos repetibles y campos ocultos

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.

Claves de opción: las alternativas dentro de una pregunta

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.