Leitfäden
Bedingte Felder: Erstellen Sie intelligente, verzweigte Signatur-Workflows über die API
Die meisten Unterzeichnungsdokumente sind nicht statisch. Ein Feld für den Namen des Ehepartners sollte nur dann erscheinen, wenn jemand „Verheiratet“ auswählt. Ein zusätzlicher Abschnitt zur Offenlegung sollte erforderlich werden, wenn eine Transaktion einen bestimmten Dollarbetrag überschreitet. Ein Block für die Lieferadresse ist nur dann von Bedeutung, wenn der Unterzeichner „An eine andere Adresse senden“ ankreuzt.
Ohne bedingte Felder müssten Sie diese gesamte Logik in Ihrer eigenen UI-Ebene aufbauen. Sie würden Sichtbarkeitsumschaltungen, Validierungsregeln und Randfälle clientseitig verwalten und hoffen, dass nichts umgangen wird. Es funktioniert, bis es eben nicht mehr funktioniert.
Die API von Firma.dev unterstützt bedingte Felder jetzt nativ. Sie definieren die Regeln in Ihrem Feldschema, und die API kümmert sich um die Sichtbarkeit, den Erforderlich-Status und die serverseitige Durchsetzung bei der Übermittlung. Keine benutzerdefinierte UI-Logik erforderlich.
Zwei Arten von Bedingungen
Jedes Feldobjekt in der API von Firma.dev akzeptiert jetzt zwei neue, nullwertfähige Eigenschaften: required_conditions und visibility_conditions.
required_conditions überschreibt das statische Flag required eines Feldes. Wenn Sie required_conditions festlegen, wird das Feld nur dann erforderlich, wenn die Bedingungen basierend auf anderen Feldwerten zum Zeitpunkt der Übermittlung als wahr ausgewertet werden. Wenn die Bedingungen als falsch ausgewertet werden, ist das Feld optional, unabhängig davon, was das Flag required besagt.
visibility_conditions steuert, ob der Unterzeichner das Feld überhaupt sieht. Wenn diese Option festgelegt ist, bleibt das Feld ausgeblendet, es sei denn, die Bedingungen werden als wahr ausgewertet. Ausgeblendete Felder werden bei der Validierung komplett übersprungen, sodass Sie keine Fehler bei Feldern erhalten, die der Unterzeichner nie gesehen hat.
Beide Eigenschaften sind nullwertfähig. Wenn sie auf null belassen werden (Standardeinstellung), verhält sich das Feld genau wie zuvor: Das statische Flag required bestimmt, ob es erforderlich ist, und das Feld ist immer sichtbar. Bestehende Integrationen erfordern keine Änderungen.
Das Bedingungsschema
Bedingungen verwenden eine dreistufige verschachtelte Struktur: ConditionSet, ConditionGroup und Condition. Dies ist der Teil, den es sich zu verstehen lohnt, da er Ihnen eine kombinierbare boolesche Logik ohne tief verschachtelte Bäume ermöglicht.
ConditionSet ist der Container auf oberster Ebene. Er hat zwei Eigenschaften: einen logic-Operator (entweder and oder or) und ein Array von groups (ConditionGroup-Objekte). Der Logik-Operator bestimmt, wie die Gruppen kombiniert werden. Wenn logic gleich and ist, müssen alle Gruppen als wahr ausgewertet werden. Wenn logic gleich or ist, reicht es aus, wenn eine einzige Gruppe als wahr ausgewertet wird.
ConditionGroup enthält ein Array von conditions (einzelne Condition-Objekte). Hier ist das entscheidende Detail: Bedingungen innerhalb einer Gruppe werden mit der gegenteiligen Logik des übergeordneten ConditionSet kombiniert. Wenn das ConditionSet and verwendet, werden Bedingungen innerhalb jeder Gruppe mit or kombiniert. Wenn das ConditionSet or verwendet, verwenden Bedingungen innerhalb jeder Gruppe and.
Dieses gegensätzliche Logikmuster macht das Schema ausdrucksstark, ohne dass eine tiefe Verschachtelung erforderlich ist. Es ermöglicht Ihnen, Anweisungen wie „(Betrag > 50000 ODER Kundentyp ist Enterprise) UND Region ist nicht leer“ mit nur zwei Gruppen innerhalb eines and-ConditionSet zu erstellen. Die erste Gruppe würde zwei Bedingungen enthalten (Betrag und Kundentyp, kombiniert mit or, da das übergeordnete Element and ist), und die zweite Gruppe würde eine Bedingung für die Regionsprüfung enthalten.
Condition ist eine einzelne Auswertung. Sie verweist auf eine field_id (die UUID eines anderen Feldes im Dokument), einen operator und einen optionalen value zum Vergleich.
Operator-Referenz
Firma.dev unterstützt 10 Vergleichsoperatoren für bedingte Felder:
is_filled prüft, ob ein Feld überhaupt einen Wert hat. Nützlich, um Folgefelder anzuzeigen, wenn ein Unterzeichner beginnt, einen Abschnitt auszufüllen. is_empty ist das Gegenteil und eignet sich gut, um ein Fallback-Feld zu fordern, wenn ein primäres Feld leer gelassen wird.
equals und not_equals führen einen exakten Wertabgleich durch. Zeigen Sie Ehepartner-Felder an, wenn der Familienstand gleich „Verheiratet“ ist, oder blenden Sie einen Abschnitt aus, wenn das Land nicht gleich „US“ ist.
contains und not_contains prüfen auf Teilstrings. Sie könnten Compliance-bezogene Felder anzeigen, wenn ein Beschreibungsfeld „reguliert“ enthält, oder einen Abschnitt überspringen, wenn in den Notizen kein bestimmtes Schlüsselwort erwähnt wird.
greater_than, less_than, greater_than_or_equal und less_than_or_equal übernehmen numerische Vergleiche. Dies sind die Operatoren, die Sie verwenden würden, um eine schwellenwertbasierte Logik aufzubauen, z. B. um die Genehmigung eines Managers zu verlangen, wenn ein Betrag 10.000 überschreitet, oder um vereinfachte Bedingungen anzuwenden, wenn ein Vertragswert unter eine bestimmte Zahl fällt.
Wie Bedingungen in der Praxis aussehen
Das API-Changelog enthält ein Beispiel für das einfachste bedingte Muster: Ein Feld wird nur dann erforderlich, wenn ein anderes Feld ausgefüllt wurde. Die Eigenschaft required_conditions nimmt ein ConditionSet mit and-Logik, einer einzelnen Gruppe und einer einzelnen Bedingung auf, die den Operator is_filled verwendet:
Die field_id verweist auf die UUID des Feldes, das Sie auswerten. In diesem Fall wird das aktuelle Feld immer dann erforderlich, wenn das referenzierte Feld einen beliebigen Wert hat. Wenn es leer ist, wird das Feld wieder optional.
Sie können auf diesem Muster in verschiedene Richtungen aufbauen. Für die bedingte Sichtbarkeit würden Sie dieselbe ConditionSet-Struktur unter visibility_conditions anstelle von required_conditions verwenden. Ein Textfeld „Name des Ehepartners“, das nur angezeigt wird, wenn das Kontrollkästchen „Verheiratet“ aktiviert ist, würde jedoch visibility_conditions mit einer einzelnen is_filled-Bedingung verwenden, die auf die UUID des Kontrollkästchen-Feldes verweist.
Für Logiken mit mehreren Bedingungen fügen Sie weitere Gruppen oder mehr Bedingungen innerhalb von Gruppen hinzu. Wenn Sie ein Feld für die Compliance-Zertifizierung nur dann benötigen, wenn der Transaktionsbetrag größer als 10.000 ist UND das Land „US“ entspricht, erstellen Sie ein ConditionSet mit and-Logik, das zwei Gruppen mit jeweils einer Bedingung enthält. Die erste Gruppe prüft den Betrag mit greater_than, die zweite das Land mit equals.
Das ausdrucksstärkste Muster verwendet die gegensätzliche Logikregel. Angenommen, Sie möchten einen Abschnitt „Sonderbedingungen“ anzeigen, wenn (Betrag > 50.000 ODER Kundentyp gleich „Enterprise“) UND die Region nicht leer ist. Sie würden die logic des ConditionSet auf and mit zwei Gruppen festlegen. Die erste Gruppe enthält zwei Bedingungen (Betrag und Kundentyp), die automatisch mit or kombiniert werden, da das übergeordnete Element and verwendet. Die zweite Gruppe enthält die einzelne Regionsbedingung. Das Ergebnis ist eine saubere, lesbare Struktur, die andernfalls verschachtelte boolesche Bäume erfordern würde.
Serverseitige Durchsetzung
Alle Bedingungen werden serverseitig ausgewertet, wenn der Unterzeichner das Dokument übermittelt. Dies ist nicht optional und kann nicht durch clientseitige Manipulationen umgangen werden.
Wenn ein Feld bedingt erforderlich ist und die Bedingung zum Zeitpunkt der Übermittlung als wahr ausgewertet wird, gibt die API einen Validierungsfehler zurück, wenn dieses Feld leer ist. Wenn die visibility_conditions eines Feldes als falsch ausgewertet werden, wird das Feld ausgeblendet und bei der Validierung komplett übersprungen. Keine Randfälle, keine Race-Conditions zwischen Ihrer UI und dem Backend.
Für Compliance-Workflows ist dies von Bedeutung. Die Bedingungen, die Sie in der API definieren, sind die Bedingungen, die durchgesetzt werden, Punkt. Ihre clientseitige UI kann die Sichtbarkeits- und Erforderlich-Zustände in Echtzeit rendern, um dem Unterzeichner eine gute Benutzererfahrung zu bieten, aber die Quelle der Wahrheit liegt serverseitig.
Wo Bedingungen funktionieren
Bedingte Felder sind auf allen Oberflächen in Firma.dev verfügbar: der Template-Editor-UI, der Signieranforderungs-Editor-UI, dem eingebetteten Template-Editor, dem eingebetteten Signieranforderungs-Editor und der vollständigen REST-API sowohl für Vorlagen als auch für Signieranforderungen.
Über die API festgelegte Bedingungen werden auf allen UI-Oberflächen korrekt angezeigt und ausgewertet, und über die Editoren konfigurierte Bedingungen sind über die API vollständig zugänglich. Es gibt keine Funktionslücke zwischen den visuellen Tools und der programmgesteuerten Schnittstelle.
Erste Schritte
Bedingte Felder wurden als Teil der Firma.dev API v1.10.0 veröffentlicht. Sie sind vollständig additiv und enthalten keine Breaking Changes. Felder ohne Bedingungen funktionieren weiterhin genau wie zuvor, und bestehende Integrationen erfordern keinerlei Änderungen.
Sie können noch heute damit beginnen, required_conditions und visibility_conditions für jedes beliebige Feldobjekt zu verwenden. Die vollständige Schemareferenz finden Sie im API-Changelog und die vollständige Feldspezifikation in der API-Dokumentation.
Firma.dev berechnet 0,049 € pro Umschlag ohne monatliche Mindestbeträge, ohne Lizenzgebühren und ohne Vorabverpflichtungen. Wenn Sie Signier-Workflows erstellen, die sich an die Eingaben des Unterzeichners anpassen müssen, können Sie diese Logik mit bedingten Feldern dorthin verlagern, wo sie hingehört: in die API, durchgesetzt bei jeder Übermittlung.
Starten Sie kostenlos mit Firma.dev, keine Kreditkarte erforderlich.
Verwandte Artikel
Unsere Plattform wurde entwickelt, um Unternehmen jeder Größe zu befähigen, intelligenter zu arbeiten und ihre Ziele mit Zuversicht zu erreichen.
