visibility_conditions, required_conditions et multi_group_id — les trois propriétés qui pilotent ce comportement — ainsi que les erreurs qui les font le plus souvent mal fonctionner.
Le modèle de condition
visibility_conditions et required_conditions acceptent tous deux la même structure : un ConditionSet.
Opérateurs
field_id doit référencer un autre champ assigné au même destinataire que le champ portant la condition. La vue de signature comme le serveur évaluent les conditions en utilisant uniquement les valeurs de champs propres à ce destinataire — une condition référençant un champ appartenant à un autre signataire ou approbateur ne se résoudra jamais à une valeur réelle (voir plus bas le point de vigilance sur les références obsolètes). value accepte une chaîne ou un nombre ; omettez-le pour is_filled/is_empty.
Limites appliquées côté serveur : au maximum 20 groupes par ensemble de conditions, au maximum 20 conditions par groupe,
field_id jusqu’à 100 caractères, et une value de type chaîne jusqu’à 1000 caractères. Elles existent pour borner le coût d’évaluation, et non pour restreindre un usage réaliste — la plupart des ensembles de conditions utilisent un ou deux groupes.Conditions de visibilité
Définissezvisibility_conditions sur un champ pour contrôler s’il est affiché ou non au signataire :
visibility_conditions est toujours visible. Un champ avec visibility_conditions n’est visible que tant que l’ensemble de conditions s’évalue à vrai, et masqué dans le cas contraire. Un champ masqué est également exclu de la validation — il ne peut pas empêcher le signataire de terminer, et il n’est pas rendu dans la vue de signature.
Conditions d’obligation
Définissezrequired_conditions pour que le statut obligatoire d’un champ dépende des valeurs d’autres champs, plutôt que d’être fixé à la création du champ :
Un champ peut être obligatoire tout en étant masqué — vérifiez ce point
Rien ne vous empêche d’écrire un champ dont lesrequired_conditions s’évaluent à vrai pour une combinaison de valeurs où ses visibility_conditions s’évaluent à faux. Le signataire serait alors bloqué pour terminer par une exigence qu’il ne peut ni voir ni satisfaire. Les éditeurs de modèles et de demandes de signature affichent un avertissement en temps réel dans le panneau de propriétés du champ lorsque les conditions d’obligation et de visibilité d’un champ pourraient être en désaccord — mais cette vérification est une heuristique prudente (elle signale des ensembles de conditions structurellement différents, pas uniquement ceux logiquement incompatibles), donc examinez manuellement tout champ portant les deux propriétés. Le schéma le plus sûr consiste à faire de visibility_conditions un sur-ensemble de required_conditions : chaque fois que le champ doit être rempli, il doit aussi être à l’écran.
multi_group_id : lier des cases à cocher et des boutons radio
multi_group_id lie plusieurs champs checkbox ou radio_buttons en un seul groupe logique. C’est un UUID, pas un libellé — et les deux types de champs se comportent différemment une fois regroupés.
Boutons radio : mutuellement exclusifs par conception
Les champs de typeradio_buttons qui partagent un multi_group_id forment un groupe à choix unique : en sélectionner un désélectionne tous les autres champs du groupe, à la fois dans l’interface de signature et dans la façon dont le statut obligatoire du groupe est résolu. Utilisez ceci lorsque vous voulez que le signataire choisisse exactement une option parmi un ensemble fixe — un champ par option, tous partageant un même multi_group_id :
required: true sur un groupe de boutons radio signifie « le signataire doit choisir l’une des options » — l’exigence est satisfaite dès qu’un seul champ du groupe a une valeur.
Cases à cocher : regroupées pour « en choisir au moins une », jamais exclusives
Les champs de typecheckbox qui partagent un multi_group_id ne deviennent pas mutuellement exclusifs. Chaque case à cocher du groupe est cochée ou décochée indépendamment — en cocher une ne décoche pas les autres. Regrouper des cases à cocher ne change que la façon dont le statut obligatoire est évalué : au lieu que chaque case du groupe doive être cochée, le groupe dans son ensemble est satisfait dès qu’au moins une case y est cochée.
Si vous voulez réellement des options à choix unique mutuellement exclusives rendues sous forme de cases à cocher plutôt que de cercles, il n’existe pas d’indicateur côté serveur pour cela — construisez le groupe avec
radio_buttons. multi_group_id sur des champs checkbox sert à « sélectionnez-en autant que vous voulez, mais au moins une », pas à l’exclusivité.
Combiner les trois
Un cas de figure réel courant : une case à cocher qui révèle un champ de texte, lequel fait lui-même partie d’un choix radio ailleurs dans le document.opt-out-reason est masqué et facultatif jusqu’à ce que opt-out-checkbox soit coché, moment auquel il devient à la fois visible et obligatoire — l’ensemble de conditions identique sur les deux propriétés les maintient synchronisés, de sorte que le champ n’est jamais obligatoire tant qu’il est masqué.
Points de vigilance
Le compteur de champs obligatoires peut reculer pendant que le signataire remplit le formulaire
La vue de signature affiche un indicateur « X sur Y champs obligatoires complétés ».Y (le total) est calculé à partir des champs qui sont actuellement obligatoires — y compris tout champ dont les required_conditions viennent de devenir vraies. Cela signifie que cocher une case qui révèle un champ nouvellement obligatoire augmente Y immédiatement, alors que X (le nombre de champs remplis) ne change pas tant que le signataire n’a pas rempli ce nouveau champ. L’effet visible est que le pourcentage d’achèvement chute juste après que le signataire a répondu à une question, ce qui donne l’impression que le compteur « ne se met pas à jour » alors qu’il fait en réalité l’inverse : il se met à jour pour refléter un formulaire qui vient de s’allonger.
Il n’y a aucun moyen d’éviter cela si un champ conditionnel doit ajouter une exigence réellement nouvelle, mais vous pouvez minimiser le saut en plaçant tôt dans le document les champs qui révèlent de nouvelles exigences, afin que la « révélation » se produise avant que le signataire n’ait beaucoup avancé plutôt que vers la fin.
Les conditions référençant un champ supprimé ou inaccessible ne se déclenchent jamais
Si unfield_id à l’intérieur d’une condition ne correspond à aucun champ visible par le signataire, l’évaluateur traite sa valeur comme vide — la condition ne provoque pas d’erreur, elle se résout simplement comme si ce champ était vide. Les conditions is_empty et not_equals portant sur un identifiant de champ manquant s’évaluent à vrai ; is_filled, equals, contains et les comparaisons numériques s’évaluent à faux. Un ensemble visibility_conditions construit entièrement à partir de références field_id obsolètes (par exemple, des vérifications equals/is_filled) rendra simplement le champ masqué de façon permanente. Si un champ que vous attendiez n’apparaît jamais, vérifiez que le field_id dans ses conditions correspond encore à l’id d’un champ réel sur cette même demande de signature, et que le champ référencé n’a pas été supprimé ultérieurement lors d’une modification de modèle.
Prochaines étapes
- Préremplissage des Champs — les propriétés qui contrôlent la valeur affichée d’un champ, par opposition à son affichage ou son caractère obligatoire
- Envoi d’une Demande de Signature — le flux complet de création des destinataires et des champs dans lequel s’inscrivent ces champs