Organisation

‣

Aufbau und Nutzer

Erstellen & Versenden

‣

Templates

‣

Formulare

‣

Inhaltsblöcke und Formularfelder

Sicherheit

‣

API

‣

Integrationen

Rules Engine

‣

Erste Schritte

‣

Bedingte Sichtbarkeit

Rules Engine

Mit der Paperless Rules Engine können Sie Paperless Formulare um dynamische Funktionsweisen erweitern. Verwenden Sie JavaScript-basierte Regeln, um Formularinhalte während des Ausfüllens zu berechnen, oder deren Sichtbarkeit dynamisch anzupassen.

Ein erstes Dokument mit Regeln versehen

Dieser Guide bietet Ihnen die Möglichkeit, erste Schritte mit der Paperless Rules Engine zu gehen und anhand eines konkreten Beispiels ein erstes Formular mit dynamischen Regeln zu versehen.

Voraussetzungen:

Kenntnisse im Umgang mit dem Paperless Builder (Link auf bestehende Dokumentation?)
Grundkenntnisse in JavaScript: https://developer.mozilla.org/en-US/docs/Web/JavaScript

Ihr erstes dynamisches Formular: Teilnehmerformular für eine Konferenz

Sie sind für die Dauer dieses Guides Organisator des TechInSight Forums, einer alljährlichen Konferenz, auf der sich Teilnehmer in Themen rund um Digitalisierung und Technologische Innovation fortbilden und austauschen können. Für die bevorstehende Konferenz möchten Sie die Registrierung sämtlicher Teilnehmer statt wie gewohnt mit verschiedenen PDF-Formularen erstmals mit Hilfe eines dynamischen Paperless-Formulars umsetzen.

Die nachfolgenden Abschnitte erklären in fünf Schritten, wie ein solches dynamisches Formular mit Hilfe der Paperless Rules Engine erstellt werden kann.

Schritt 1: Erstellen der Formularfelder

Allgemeine Vorgehensweise:

Erstellen Sie unter Verwendung des Paperless-Builders wie gewohnt per Drag-and-Drop alle Blöcke, die Sie für Ihr Formular benötigen (TODO Verlinkung auf bestehende Doku?).

Blöcke, die während des Ausfüllens des Formulars nur unter bestimmten Bedingungen angezeigt werden sollen, können ebenfalls zu diesem Zeitpunkt bereits angelegt werden. Später werden Sie diese mit Hilfe von Sichtbarkeits-Regeln entsprechend dynamisch aus- und einblenden.

Sie sollten für jeden Block einen individuellen Slug festlegen. Dabei ist es sinnvoll, Slugs ausdrucksstark, aber möglichst kurz zu wählen. Später werden Sie über die Slugs in JavaScript-Code auf Formularblöcke und deren Eigenschaften zugreifen.

Sie können den Slug eines Blockes bearbeiten, indem Sie diesen entweder direkt in der Kopfzeile der Block-Einstellungen anpassen, oder im aufklappbaren Reiter Erweitert bearbeiten.

Für Blöcke mit Auswahloptionen, also Radio- und Checkbox-Blöcke, sollten Sie außerdem für jede Auswahloption einen individuellen Slug vergeben. Über diesen Slug können Sie später erfragen, ob die entsprechende Auswahloption gewählt wurde.

Sie können die Slugs der Auswahloptionen eines Blockes bearbeiten, indem Sie im Reiter Optionen auf Erweitert klicken (bis einschließlich vier Auswahloptionen), oder auf den Button Auswahloptionen verwalten klicken (ab fünf Auswahloptionen).

Beispiele im Formular:

Erstellen Sie zunächst ein neues Paperless-Formular (TODO: Link auf Doku).

Sie werden in diesem Schritt alle erforderlichen Blöcke im Formular anlegen. Diese sind zunächst wie gewohnt einfache, statische Blöcke. In Schritt 3 und 4 werden Sie diese nachträglich mit dynamischem Verhalten versehen.

Nachfolgend werden alle Blöcke im Detail beschrieben. Das fertige Formular soll am Ende folgendermaßen aussehen:

Fragen Sie zunächst unter Verwendung von Texteingabe-Blöcken die Kontaktinformationen des Teilnehmers ab:

In den Einstellungen der jeweiligen Blöcke vergeben Sie dabei passende Slugs (siehe Screenshot).

Vergeben Sie die folgenden Slugs:

First Name: first_name
Last Name: last_name
E-Mail Address: email
Contact Number: phone

Als nächstes fragen Sie mit Hilfe eines Radio-Blocks den Besucher-Typ des Teilnehmers ab.

Versehen Sie den Block mit dem Slug registration_type.

Auf Basis des gewählten Typs, soll sich das Dokument später dynamisch anpassen. Daher ist es wichtig, auch die Auswahloptionen mit passenden Slugs zu versehen:

Es folgen:

Ein Datei-Upload-Block, mit welchem Studenten ihre Studienbescheinigung hochladen können.

Slug: cert_enrollment

Ein weiterer Radio-Block, mit welchem freiwillige Helfer ihre Wunsch-Schicht angeben können.

Slug: shift_preferences

Beachten Sie, für die Auswahloptionen auch wieder Slugs zu vergeben:

Ein stylisierter Gruppen-Block mit einem Text-Block, der freiwillige Helfer und solche Teilnehmer, die einen Vortrag halten werden, darauf hinweisen soll, dass der Veranstaltungsorganisator in Kürze Kontakt aufnehmen wird.

Slug: note

Daraufhin sollen alle Teilnehmer, die nicht als Studierende teilnehmen, die Möglichkeit haben, sich mit einem Checkbox-Block für Workshops anzumelden, welche als Ergänzung zu den allgemein zugänglichen Vorträgen angeboten werden.

Slug: workshop_selection

Vergeben Sie auch hier wieder Slugs für die einzelnen Auswahloptionen:

1. Textblöcke

Außerdem bekommen alle Nicht-Studierenden ein Konferenz-Shirt. Ein weiterer Text-Block soll Teilnehmenden den T-Shirt Aufdruck anzeigen, der auf Basis ihrer Angaben erstellt wird. Wie Sie Text in Text-Blöcken mit Hilfe von Variablen dynamisch anpassen können, lernen Sie in Schritt 4 dieses Guides.

Slug: shirt_text

Teilnehmenden soll außerdem in einem weiteren Text-Block der individuell angepasste Preis für die Konferenzteilnahme angezeigt werden.

Slug: price_text

2. Kontodaten-Block Im Anschluss soll allen zahlenden Teilnehmenden ein Kontodaten-Block angezeigt werden, um ihre Zahlungsinformationen zu hinterlegen.

Slug: payment_details

3. Unterschrift Block

Abschließend können Teilnehmende das Formular digital mit einem Unterschrift-Block unterschreiben.

Slug: signature

Schritt 2: Freischalten der Rules-Engine Funktionalität für den aktuellen Workspace

Um die Rules-Engine in Formularen verwenden zu können, ist es zunächst erforderlich, das Modul Rules Engine in den Workspace-Einstellungen des Formulars zu aktivieren.

Öffnen Sie die Einstellungen des Workspace, dem das Formular zugeordnet ist.

Wechseln Sie zu Modulübersicht, indem Sie auf Module klicken.

Aktivieren Sie die Rules-Engine, indem Sie den Schalter für das Modul Rules Engine aktivieren.

Die Rules-Engine kann nach der Aktivierung in allen Dokumenten des Workspace verwendet werden.

Schritt 3: Regeln für Bedingte Sichtbarkeit

In diesem Abschnitt werden Sie lernen, wie Sie mit dynamischen Regeln die Sichtbarkeit einzelner Blöcke während des Ausfüllens steuern können.

Eine Regel für Bedingte Sichtbarkeit erstellen:

Wählen Sie zunächst den Block aus, für den Sie eine Bedingte Sichtbarkeitsregel implementieren wollen.
Aktivieren Sie in den Blockeinstellungen den Schalter Bedingte Sichtbarkeit.

Anschließend öffnet sich ein Code-Editor, in welchem Sie mit JavaScript eine Sichtbarkeitsregel formulieren können.

Im Code-Editor können Sie beliebige JavaScript Funktionalität implementieren. Neben der Unterstützung von Auto-Complete bietet der Editor Ihnen außerdem nützliche Debug-Informationen, wie eine Übersicht über alle Elemente des Dokuments und die Ausgabe von Berechnungsergebnissen oder Fehlermeldungen in Echtzeit.

Die Bedingte Sichtbarkeit eines Blockes kann jederzeit durch Klicken des Buttons Bedingte Sichtbarkeit in den Blockeinstellungen weiter angepasst werden.

Beispiele im Formular:

Der erste Block, der mit einer Bedingten Sichtbarkeit versehen werden soll ist der Datei-Upload-Block für Studienbescheinigungen mit dem Slug cert_enrollment. Dieser soll nur Studierenden angezeigt werden. Folgen Sie dafür zunächst den oben genannten Schritten 1 bis 3, um die Bedingte Sichtbarkeit für diesen Block zu aktivieren. Im Code-Editor kann nun anhand von JavaScript-Code eine Regel formuliert werden:

blocks.registration_type.options.student.selected;

Die Bestandteile des Code-Snippets kurz erklärt:

blocks ist ein fester Bestandteil der Rules Engine API und ermöglicht den Zugriff auf alle Blöcke eines Formulars anhand ihrer Slugs.

registration_type ist der Slug des Radio-Blocks, mit dem Teilnehmende ihren Besuchertyp wählen können. Alle Blöcke können über ihren Slug nach dem Schema blocks.<slug> angesprochen werden.

options ist ebenfalls ein fester Bestandteil der Rules Engine API und ermöglicht für Radio- und Checkbox-Blöcke Zugriff auf alle Auswahloptionen.

student ist der Slug einer konkreten Auswahloption. Auswahloptionen können ähnlich wie Blöcke ebenfalls über ihre Slugs nach dem Schema options.<slug> angesprochen werden.

selected ist ebenfalls fester Bestandteil der Rules Engine API und gibt für die jeweilige Auswahloption zurück, ob diese gerade ausgewählt ist, oder nicht.

Es wird also aus allen Blöcken (blocks), für den Block mit dem Slug registration_type überprüft, ob aus dessen Auswahlmöglichkeiten (options) die Option mit dem Slug student ausgewählt (selected) wurde.

Der Radio-Block für Helferschichten (shift_preferences) soll hingegen lediglich freiwilligen Helfern angezeigt werden. Analog zum vorherigen Block, lässt sich diese Regel mit folgendem Code-Snippet umsetzen:

blocks.registration_type.options.volunteer.selected;

Alternativ lässt sich der Auswahlstatus einer Option auch über die Funktion isOptionSelected() abfragen:

blocks.registration_type.isOptionSelected("volunteer");

isOptionSelected(”<slug>”) ist fester Bestandteil der Rules Engine API und ist äquivalent zu options.<slug>.selected , profitiert jedoch nicht im gleichen Maße von den Auto-Complete Funktionen des Editors und ist daher weniger intuitiv in der Benutzung.

Die Block-Gruppe mit Hinweistext (note) soll freiwilligen Helfern (volunteer) und Vortragenden (speaker) angezeigt werden. Sie können die Ergebnisse der jeweiligen Abfragen mit logischen Ausdrücken, z.B. einem ODER (||), verknüpfen um mehrere Optionen zu berücksichtigen.

blocks.registration_type.options.volunteer.selected || blocks.registration_type.options.speaker.selected;

Da sich der Preis, den der Teilnehmer zu zahlen hat, erst ermitteln lässt, wenn dieser einen Besuchertyp gewählt hat, soll der Texteingabe-Block für den Preis erst angezeigt werden, wenn eine Auswahloption des Blocks registration_type ausgewählt worden ist.

blocks.registration_type.hasOptionSelected();

hasOptionSelected() ist fester Bestandteil der Rules Engine API und gibt für Radio-Blöcke Auskunft, ob mindestens eine Auswahloption ausgewählt ist.

Die beiden Blöcke workshop_selection und shirt_text sollen allen Teilnehmern außer Studenten angezeigt werden, da diese zwar kostenlos teilnehmen dürfen, aber im Gegenzug keine Workshops buchen können und kein Konferenz-Shirt erhalten.

Sie können mehrere Blöcke mit der gleichen Regel versehen, indem Sie diese zunächst gruppieren. Wählen Sie hierfür die betreffenden Blöcke aus und pressen Sie anschließend Strg + G . Die Gruppe kann über den Befehl Strg + Shift + G bei Bedarf wieder aufgelöst werden.

Gruppieren Sie nun die beiden Blöcke workshop_selection und shirt_text und versehen Sie die Block-Gruppe mit der folgenden Regel:

blocks.registration_type.hasOptionSelected() && !blocks.registration_type.options.student.selected;

Hier werden wieder zwei Abfragen mit einem logischen Ausdruck, nämlich einem UND (&&) verknüpft. Zunächst wird abgefragt, ob NICHT (!) die Option student ausgewählt ist. Da dies allerdings auch vor dem Ausfüllen immer bereits der Fall ist und die Gruppe somit von Beginn an angezeigt werden würde, wird mit hasOptionSelected() zusätzlich geprüft, ob überhaupt schon eine Option des Blocks registration_type ausgewählt ist.

Gruppen sparen Zeit und Aufwand, wenn mehrere Blöcke mit der selben Sichtbarkeitsregel versehen werden sollen. Wird die Gruppe später wieder aufgelöst, verfällt die Regel allerdings für alle Blöcke der Gruppe.

Schritt 4: Regeln als Variablen

In manchen Fällen ist es sinnvoll, Regeln nicht pro Block zu definieren, sondern als formularweite JavaScript Variable anzulegen. Eine solche Variable kann wiederum in einzelnen Blöcken abgefragt werden, um deren Bedingte Sichtbarkeit zu bestimmen.

Dies ist besonders sinnvoll für Regeln, die für viele Blöcke relevant sind, und / oder deren Berechnung aufwändiger ist.

Darüber hinaus kann das Ergebnis der Regel-Berechnung als Variable in Text-Blöcken verwendet werden.

Eine Variable erstellen:

Klicken Sie auf den Reiter Regeln am rechten Bildschirmrand.
Klicken Sie anschließend auf das Plus-Zeichen, um eine neue Regel zu erstellen.

Wählen Sie in der Maske den Typ JavaScript Variable.
Vergeben Sie einen kurzen, aber ausdrucksstarken Namen für die neue Regel.
Klicken Sie nun auf Erstellen.

Anschließend öffnet sich ein Code-Editor, in welchem Sie mit JavaScript eine Regel formulieren können.

Beispiele im Formular:

JavaScript Variablen für Bedingte Sichtbarkeit nutzen:

Anhand des payment_details Blocks werden Sie nun zunächst lernen, wie eine JavaScript Variable für die Bedingte Sichtbarkeit verwendet werden kann.

Legen Sie dazu, wie zuvor beschrieben, eine JavaScript Variable has_to_pay an.

Das Ziel ist, zu überprüfen, ob der Teilnehmer einem der Besuchertypen regular, vip, oder speaker angehört oder ob er einen Workshop gebucht hat. Beides führt dazu, dass der Teilnehmer eine Teilnahmegebühr zahlen muss und die Zahlungsdaten als Pflichtfeld angezeigt werden. Versehen Sie dafür die Variable has_to_pay mit folgendem Code:

const payingAttendees = ["regular", "vip", "speaker"];

const isPayingAttendee = payingAttendees.includes(blocks.registration_type.selectedOption.slug);

const workshopSelected = blocks.workshop_selection.anyOptionSelected();

isPayingAttendee || workshopSelected;

selectedOption ist fester Bestandteil der Rules Engine API und gibt für Radio-Blöcke die ausgewählte Option zurück.

slug ist fester Bestandteil der Rules Engine API und gibt den Slug einer Auswahloption zurück.

Es wird also zunächst geprüft, ob der Slug des gewählten Besuchertyps regular, vip, oder speaker lautet.

anyOptionSelected() ist fester Bestandteil der Rules Engine API und gibt für Checkbox-Blöcke Auskunft, ob mindestens eine Auswahloption ausgewählt ist

Hier wird also geprüft, ob der Besucher mindestens einen der angebotenen Workshops ausgewählt hat.

Anschließend können Sie in der Bedingten Sichtbarkeit des Blockes payment_details das Ergebnis der JavaScript Variable abfragen:

tokens.has_to_pay;

tokens ist fester Bestandteil der Rules Engine API und ermöglicht den Zugriff auf alle von Ihnen definierten JavaScript Variablen nach dem Schema tokens.<Name der Variable>.

JavaScript Variablen im Text referenzieren:

JavaScript Variablen können ähnlich wie Platzhalter auch direkt in Text-Blöcke integriert werden.

Legen Sie hierfür zunächst eine neue JavaScript Variable mit dem Namen shirt_text an.

Fügen Sie nun den folgenden Code ein, um den Vornamen, Nachnamen und den Besuchertyp des Besuchers zu einem String zusammenzusetzen:

blocks.first_name.value + " " + blocks.last_name.value + ": " + blocks.registration_type.selectedOption.name + " Attendee"

value ist fester Bestandteil der Rules Engine API und ermöglicht für Texteingabe-Blöcke den Zugriff auf den eingegebenen Text.

name ist fester Bestandteil der Rules Engine API und gibt für Radio und Checkbox-Blöcke den Anzeige-Text der entsprechenden Auswahloption zurück.

Klicken Sie anschließend in den Text-Block, den Sie zuvor zum Anzeigen des T-Shirt Aufdrucks angelegt haben (Slug: shirt_text), und fügen Sie die Variable am Ende des Textes ein.

Die JavaScript Variable wird nun gelb unterlegt im Text angezeigt.

Abschließend möchten Sie nun auch die Teilnahmegebühr anzeigen, die sich für jeden Teilnehmenden individuell aus dem gewählten Besuchertyp und der Anzahl ausgewählter Workshops ergibt. So soll der reguläre Preis 300 Euro betragen, der VIP-Preis 400 Euro und der Preis für Vortragende 100 Euro, während Studierende und Helfer keine Grundgebühr zahlen. Zusätzlich sollen für jeden gebuchten Workshop weitere 50 Euro hinzukommen.

Erstellen Sie hierfür nun eine weitere Variable price mit folgendem JavaScript Code:

const base_prices = {
    "regular": 300,
    "vip": 400,
    "speaker": 100,
    "volunteer": 0,
    "student": 0 
};

const registration_type = blocks.registration_type.selectedOption.slug;
const number_of_workshops = blocks.workshop_selection.selectedOptions.length;
const workshop_price = 50 * number_of_workshops;
const total_price = base_prices[registration_type] + workshop_price;

total_price;

selectedOptions ist fester Bestandteil der Rules Engine API und gibt für Checkbox-Blöcke alle ausgewählten Auswahloptionen zurück.

Fügen sie die Variable price anschließend wie zuvor in den Text-Block price_text ein.

Schritt 5: Testen der Regeln in der Rules Engine Vorschau

Der Editor bietet Ihnen einen Vorschaumodus, mit dem Sie Ihre Regeln testen und deren Auswirkungen auf das Formular nachvollziehen können

Aktivieren Sie die Vorschau, indem Sie den entsprechenden Schalter in der Kopfzeile des Editors aktivieren.

Füllen Sie nun das Formular aus. Sowohl die Bedingten Sichtbarkeiten, als auch die Ergebnisse der JavaScript-Variablen werden während des Ausfüllens in Echtzeit aktualisiert.

Die aktuellen Berechnungsergebnisse der JavaScript-Variablen sind im Reiter “Regeln” einsehbar.

Auf dieser Seite

Rules Engine
Ein erstes Dokument mit Regeln versehen
Ihr erstes dynamisches Formular: Teilnehmerformular für eine Konferenz
Schritt 1: Erstellen der Formularfelder
Allgemeine Vorgehensweise:
Beispiele im Formular:
Schritt 2: Freischalten der Rules-Engine Funktionalität für den aktuellen Workspace
Schritt 3: Regeln für Bedingte Sichtbarkeit
Eine Regel für Bedingte Sichtbarkeit erstellen:
Beispiele im Formular:
Schritt 4: Regeln als Variablen
Eine Variable erstellen:
Beispiele im Formular:
Schritt 5: Testen der Regeln in der Rules Engine Vorschau