Organisation
Erstellen & Versenden
Sicherheit
API
Rules Engine
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.
- 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.
- Ein weiterer Radio-Block, mit welchem freiwillige Helfer ihre Wunsch-Schicht angeben können.
Slug: cert_enrollment
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
- Ö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.
Schritt 3: Regeln für Bedingte Sichtbarkeit
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.
- 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.
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:
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
- 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