visibility_conditions, required_conditions y multi_group_id — las tres propiedades que impulsan este comportamiento — junto con los errores que más a menudo hacen que se comporten mal.
El modelo de condiciones
Tantovisibility_conditions como required_conditions aceptan la misma forma: un ConditionSet.
Operadores
field_id debe hacer referencia a otro campo asignado al mismo destinatario que el campo que lleva la condición. Tanto la vista de firma como el servidor evalúan las condiciones usando únicamente los valores de campo de ese propio destinatario — una condición que hace referencia a un campo perteneciente a un firmante o aprobador diferente nunca se resolverá a un valor real (consulta más abajo el detalle sobre referencias obsoletas). value acepta una cadena o un número; omítelo para is_filled/is_empty.
Límites aplicados del lado del servidor: como máximo 20 grupos por conjunto de condiciones, como máximo 20 condiciones por grupo,
field_id de hasta 100 caracteres, y un value de cadena de hasta 1000 caracteres. Estos existen para acotar el costo de evaluación, no para restringir el uso realista — la mayoría de los conjuntos de condiciones usan uno o dos grupos.Condiciones de visibilidad
Configuravisibility_conditions en un campo para controlar si se muestra o no al firmante:
visibility_conditions siempre es visible. Un campo con visibility_conditions es visible solo mientras el conjunto de condiciones se evalúe como verdadero, y está oculto en caso contrario. Un campo oculto también queda excluido de la validación — no puede impedir que el firmante termine, y no se renderiza en la vista de firma.
Condiciones de obligatoriedad
Configurarequired_conditions para que el estado obligatorio de un campo dependa de los valores de otros campos, en lugar de estar fijo en el momento de creación del campo:
Un campo puede ser obligatorio mientras está oculto — verifica esto
Nada te impide escribir un campo cuyasrequired_conditions se evalúen como verdaderas en una combinación de valores donde sus visibility_conditions se evalúen como falsas. El firmante quedaría entonces bloqueado para terminar por un requisito que no puede ver y no puede satisfacer. Los editores de plantillas y de solicitudes de firma muestran una advertencia en vivo en el panel de propiedades del campo cuando las condiciones de obligatoriedad y visibilidad de un campo podrían estar en desacuerdo — pero la verificación es una heurística conservadora (marca conjuntos de condiciones estructuralmente diferentes, no solo los lógicamente incompatibles), así que revisa manualmente cualquier campo que lleve ambas propiedades. El patrón más seguro es hacer que visibility_conditions sea un superconjunto de required_conditions: siempre que el campo deba completarse, también debe estar en pantalla.
multi_group_id: vinculación de casillas de verificación y botones de opción
multi_group_id vincula varios campos checkbox o radio_buttons en un solo grupo lógico. Es un UUID, no una etiqueta — y los dos tipos de campo se comportan de manera diferente una vez agrupados.
Botones de opción: mutuamente excluyentes por diseño
Los campos de tiporadio_buttons que comparten un multi_group_id forman un grupo de selección única: seleccionar uno deselecciona todos los demás campos del grupo, tanto en la interfaz de firma como en la forma en que se resuelve el estado obligatorio del grupo. Usa esto cuando quieras que el firmante elija exactamente una opción de un conjunto fijo — un solo campo por opción, todos compartiendo un multi_group_id:
required: true en un grupo de botones de opción significa “el firmante debe elegir una de las opciones” — el requisito se satisface tan pronto como cualquier campo del grupo tenga un valor.
Casillas de verificación: agrupadas para “elegir al menos una”, nunca excluyentes
Los campos de tipocheckbox que comparten un multi_group_id no se vuelven mutuamente excluyentes. Cada casilla de verificación del grupo se marca o desmarca de forma independiente — marcar una no desmarca las demás. Agrupar casillas de verificación solo cambia la forma en que se evalúa el estado obligatorio: en lugar de que todas las casillas del grupo deban estar marcadas, el grupo en su conjunto se satisface una vez que al menos una casilla esté marcada.
Si realmente quieres opciones de selección única mutuamente excluyentes representadas como casillas de verificación en lugar de círculos, no existe un indicador del lado del servidor para eso — construye el grupo con
radio_buttons. multi_group_id en campos checkbox sirve para “selecciona cualquiera de estas, pero al menos una”, no para exclusividad.
Combinación de las tres
Un caso real habitual: una casilla de verificación que revela un campo de texto, el cual a su vez forma parte de una elección de tipo radio en otra parte del documento.opt-out-reason está oculto y es opcional hasta que se marca opt-out-checkbox, momento en el cual se vuelve tanto visible como obligatorio — el mismo conjunto de condiciones idéntico en ambas propiedades los mantiene sincronizados, de modo que el campo nunca es obligatorio mientras está oculto.
Aspectos a tener en cuenta
El contador de campos obligatorios puede retroceder mientras el firmante completa el formulario
La vista de firma muestra un indicador de “X de Y campos obligatorios completados”.Y (el total) se calcula a partir de los campos que están actualmente marcados como obligatorios — incluyendo cualquier campo cuyas required_conditions acaban de volverse verdaderas. Eso significa que marcar una casilla que revela un campo recién obligatorio aumenta Y de inmediato, mientras que X (el conteo de completados) no cambia hasta que el firmante completa ese nuevo campo. El efecto visible es que el porcentaje de finalización cae justo después de que el firmante responde una pregunta, lo cual se percibe como que el contador “no se actualiza” cuando en realidad está haciendo lo contrario: actualizándose para reflejar un formulario que se acaba de alargar.
No hay forma de evitar esto si un campo condicional va a agregar un requisito nuevo y genuino, pero puedes minimizar el salto colocando los campos que revelan nuevos requisitos al principio del documento, de modo que la “revelación” ocurra antes de que el firmante haya avanzado mucho, en lugar de cerca del final.
Las condiciones que hacen referencia a un campo eliminado o inalcanzable nunca se activan
Si unfield_id dentro de una condición no coincide con ningún campo que el firmante pueda ver, el evaluador trata su valor como vacío — la condición no genera un error, simplemente se resuelve como si ese campo estuviera en blanco. Las condiciones is_empty y not_equals contra un id de campo faltante se evalúan como verdaderas; is_filled, equals, contains y las comparaciones numéricas se evalúan como falsas. Un conjunto de visibility_conditions construido enteramente a partir de referencias field_id obsoletas (por ejemplo, verificaciones equals/is_filled) simplemente hará que el campo quede oculto de forma permanente. Si un campo que esperabas que apareciera nunca lo hace, confirma que el field_id en sus condiciones todavía coincide con el id de un campo real en esa misma solicitud de firma, y que el campo referenciado no fue eliminado posteriormente en una edición de la plantilla.
Próximos pasos
- Precarga de Campos — las propiedades que controlan el valor mostrado de un campo, a diferencia de si se muestra o es obligatorio
- Envío de una Solicitud de Firma — el flujo completo de creación de destinatarios y campos en el que viven estos campos