Hierarchien modularer Elemente

Output.Rocks bietet verschiedene Elemente für den modularen Aufbau von Dokumenten. Die Elemente sind in folgender Hierarchie organisiert (von oben nach unten):

So können die Elemente miteinander in einem .docx Dokument verwendet werden:

Verarbeitungsprozess

1. Das System stellt zuerst alle Standardwerte im Objekt <<standard>> bereit, zusammen mit allen im Backend hinterlegten Bildpfaden und Ihrem Daten-Payload (ohne übergeordnetes Objekt).
2. Anschließend werden alle Komponenten in einem virtuellen Word-Dokument vorgerendert. Sie werden geparst den bestehenden Daten hinzugefügt im <<component>>-Objekt.
3. Erst dann wird die Stamm-Vorlage gerendert, wobei alle eingebundenen Teil‑Vorlagen aus dem <<template>>-Objekt beachtet werden.

Die sich daraus ergebende Hierarchie folgt also dem Schema:

Stamm-Vorlage (Template) → Teil‑Vorlage → Komponente → Standardwert

Alle Elemente sind in darüber liegenden Hierarchie-Ebenen als <<ELEMENTOBJEKT.IDENTIFIER>> referenzierbar, wobei ELEMENTOBJEKT das Objekt mit allen Elementen der Ebene und IDENTIFIER der im Backend hinterlegte Identifier des individuellen Elements ist.

Identifier und Gruppen-Identifier

Jedes Element in Output.Rocks hat einen eindeutigen Identifier, der von Ihnen beim Anlegen vergeben wird. Dieser ist eine feste System-Bezeichnung. Unterschiedliche Elementtypen (z. B. Vorlagen, Bilder und Standardwerte) und getrennte Mandanten haben eigene Namensräume; dieselbe Zeichenkette als Identifier ist dort parallel möglich, da das System nur deren Kontext sieht.

Mehrere Vorlagen oder Elemente mit demselben Identifier in einem Namensraum schließen sich gegenseitig von der Nutzung aus! Von solchen Duplikaten wird immer nur eines automatisch genutzt. Ausgewählt vom System wird dieses anhand des activeFrom / Aktiv ab-Wertes: Das Element mit dem neuesten, nicht in der Zukunft liegenden Wert ist dann der Adressat des Systems.

Beispiel: gleicher Identifier, verschiedenes Aktiv ab

Drei sehr ähnliche docx-Vorlagen teilen sich den Identifier kundenanschreiben. Eine Render-Anfrage nutzt nur diesen Namen — welche .docx-Datei tatsächlich gerendert wird, hängt jetzt von Aktiv ab und dem Zeitpunkt der Anfrage ab (nicht von Erstell- oder Änderungsdatum):

Für sehr ähnliche Vorlagen sollten besser Vorlagen-Gruppen genutzt werden, um sie logisch zusammenzufassen. Diese nutzen ein zusätzliches Feld, welches Sie beim Anlegen vergeben, den sogenannten Gruppen-Identifier. Sie können dann die Elemente über Gruppenbedingungen auswählen lassen, um die jeweilige Vorlage auszuwählen.

Vorlagen und Teil‑Vorlagen

Stamm-Vorlagen und ihre Teil‑Vorlagen bilden die Grundlage für die Erstellung modularer Dokumente.

Eine Stamm-Vorlage (Main-Template) ist das zentrale .docx Template für eine bestimmte Dokumentenart. Es definiert typischerweise die Struktur und die grundlegenden Inhalte eines Dokumentes, inklusive Header und Footer.

Stamm-Vorlagen werden einfach im Backend unter Vorlagen-Management -> Vorlagen hinterlegt und mit einem eindeutigen Identifier versehen.

Teil‑Vorlagen

Im Gegensatz zu Stamm-Vorlagen sind Teil‑Vorlagen spezialisierte .docx Vorlagen, die je nach Grad der Modularisierung innerhalb einer oder mehrerer Stamm‑Vorlagen Platzhalter für die verschiedenen Abschnitte des Dokumentes darstellen. Dabei können sie auch auf Komponenten zugreifen, Low‑Code‑Logik ausführen und Daten aus dem Daten‑Payload lesen.

Teil‑Vorlagen werden im Backend unter Vorlagen-Management -> Vorlagen hinterlegt und mit einem eindeutigen Identifier versehen.

Teil‑Vorlagen unterscheiden sich von Stamm‑Vorlagen:

• durch fehlende Header und Footer
• durch die Überschreibbarkeit von bestimmten Formatierungen
  • v.a. globale Fonts und Farben

Sie unterscheiden sich außerdem von Komponenten indem:

• sie nicht vorgerendert, sondern mit der Stamm-Vorlage zusammengeführt bearbeitet werden
• sie komplexe Formatieren enthalten können, wie z.B.
  • formatierte Absätze
  • lokale Fonts und Farben
  • Grafiken und Bilder
  • Tabellen und Diagramme
• sie globale Variablen enthalten können, die für die gesamte Stamm-Vorlage gelten

Teil‑Vorlagen logisch verwenden

Mit bedingter Logik können Sie dynamisch das passende Template basierend auf Datenwerten auswählen. Im folgenden Beispiel wird anhand des Werts vertragsart das entsprechende Rahmenwerk-Template ausgewählt.

    <<cs_{vertragsart='standard'}>>
    <<$ausgewaehltes_template=template.standardvertrag>>
    <<else_{vertragsart='premium'}>>
    <<$ausgewaehltes_template=template.premiumvertrag>>
    <<es_>>
    <<$ausgewaehltes_template>>

Komponenten

Komponenten sind wiederverwendbare und funktionale Textbausteine, die im App-Backend unter Vorlagen-Management -> Vorlagenkomponenten definiert und mit einem eindeutigen Identifier versehen werden.

Komponenten können Standardwerte enthalten, können Output.Rocks low-code Logik ausführen und sie sind in der Lage, Daten aus dem Daten-Payload zu lesen. Daher eignen sich Komponenten vor allem für die Verwaltung von zentralen aber komplexeren Informationen wie z.B.

• Impressum-Blöcken
• Kontakt- und Ansprechpartner-Informationen
• Berechnungen von Preisen oder anderen Werten

Komponenten eignen sich auch hervorragend, um zentrale Logik auszuführen, die in verschiedenen Stamm‑Vorlagen und Teil‑Vorlagen verwendet werden soll. Das erleichtert nicht nur deren Pflege, sondern sorgt auch für sauberere und übersichtlichere Templates.

Standardwerte

Standardwerte sind einfache Text- oder Zahlenwerte, die im App-Backend unter Vorlagen-Management -> Standardwerte definiert und mit einem eindeutigen Identifier versehen werden.

Sie eignen sich vor allem für die Verwaltung von Konstanten Ihrer Organisation wie z.B. Namen, Daten oder Zahlen, die in verschiedenen Stamm‑Vorlagen, Teil‑Vorlagen und Komponenten verwendet werden sollen. So können schnell und zentral Änderungen über Ihre gesamte Dokumentenstruktur hinweg vorgenommen werden. Typische Beispiele für Standardwerte sind:

• Zentrale Namen wie Markennamen, CEO oder Geschäftsführer, etc.
• Adressen wie z.B. Firmensitz, Postfach oder Anschrift
• Bankverbindungen wie IBAN und BIC
• Kontaktdaten wie Telefonnummern und E-Mail-Adressen
• URLs wie z.B. Social-Media-Kanäle, Webseiten oder Kampagnen-URLs
• zentrale Kennzahlen wie Kontaktzeiten, Bearbeitungstage, etc.

Standardwerte sollten kleinteilig und nicht zu komplex sein, um eine einfache Verwaltung und Wiederverwendung zu gewährleisten. Für komplexere Anwendungsfälle sollten Sie stattdessen Komponenten verwenden, in denen Standardwerte auch zusammengeführt werden können.

Validierungen und Automatisierungen

Sie können Ihre eingehenden Daten überprüfen und entsprechende Templates und Emails anschließend automatisch generieren.

Dafür gibt es zwei verschiedene Möglichkeiten:

1. Vorlagen-Gruppen werden genutzt, um ähnliche Vorlagen zu gruppieren und dynamisch auszuwählen.
2. Validierungen werden genutzt, um Daten vor der Generierung von Dokumenten zu überprüfen und eventuell das Rendering zu verhindern.

Zusätzlich können Sie Terminierungen von Elementen definieren, um z.B. neue Templates koordiniert zu wechseln oder bestimmte Regeln nur temporär zu aktivieren.

Conditional Syntax

Für die Bedingungen in Vorlagen-Gruppen und Validierungen verwendet Output.Rocks die Symfony Expression Language. Diese leistungsstarke Syntax ermöglicht es Ihnen, komplexe Bedingungen auf Basis Ihrer Daten zu formulieren.

Vorlagen-Gruppen

Vorlagen-Gruppen mit ihrem Group Identifier und dann einzelnen Group Conditions eignen sich hervorragend für Vorlagen, die funktionell ähnlich sind, sich aber in mehr Details unterscheiden, als über Teil‑Vorlagen und Komponenten hinaus komfortabel zu handhaben wäre. Das betrifft häufig mandanten‑ oder marken‑spezifische Vorlagen, die zwar dieselbe Kundenstory bedienen, aber visuell komplett unterschiedlich auftreten.

Bei System-Events wie dem Empfang neuer Daten oder der Anforderung eines Dokuments wird normalerweise nach dem exakten Identifier einer Vorlage gesucht. Wenn das System keinen exakten Identifier findet, kommen die sogenannten Group Identifier ins Spiel, die Templates zugewiesen werden können.

Validierungen

Output.Rocks bietet ein flexibles Validierungskonzept, um sicherzustellen, dass E-Mails und Dokumente nur bei gültigen Daten gerendert werden. Sie können beliebig viele Datenvalidierungsbedingungen definieren und diese Dokument- und E-Mail-Vorlagen zuweisen (n:n-Beziehung).

Validierungsregeln erlauben dabei eine zentral verwaltete Überprüfung von Datenformaten für Ihre Templates. Sie sind template-unabhängig und verhindern das Rendering eines Requests bei ungültigen Daten.

Durch die zentrale Verwaltung von Validierungsregeln können Sie Datenqualitätsstandards organisationsweit durchsetzen und somit die Qualität Ihrer Dokumente sicherstellen.

Ungültige Prozesse verwalten

Wenn Validierungsbedingungen fehlschlagen, wird der Rendering-Prozess im Status "ungültig" gestoppt. Diese ungültigen Prozesse können Sie über das Dashboard verwalten:

• Erneut validieren: Überprüfung der Daten mit den aktuellen Validierungsregeln
• Erzwingen: Rendering trotz fehlgeschlagener Validierung durchführen
• Löschen: Ungültige Prozesse aus dem System entfernen

Terminierungen von Elementen

Mit Terminierungen können Sie präzise steuern, wann bestimmte Elemente im System aktiv sind. Dies ist besonders nützlich für:

• Zeitlich begrenzte Aktionen wie Kampagnen oder saisonale Angebote
• Koordinierte Releases neuer Vorlagen oder Komponenten
• Geplante Aktualisierungen ohne manuelle Eingriffe

In den Backend-Einstellungen steht für fast alle Elemente ein Terminierungsfeld zur Verfügung:

Diese Funktion kann auf eine breite Palette von Elementen angewendet werden:

• Vorlagen und Teil‑Vorlagen – Für den koordinierten Wechsel zu neuen Dokumentversionen
• Komponenten – Für schrittweise Updates von wiederverwendbaren Bausteinen
• Standardwerte – Für die Aktualisierung zentraler Informationen zu einem bestimmten Zeitpunkt
• Validierungen – Für temporäre oder neue Prüfregeln
• Medien-Elemente – Bilder, QR-Codes, Anhänge und Grafiken können zeitgesteuert ausgetauscht werden
• Formulare – Für die Aktualisierung von Eingabefeldern oder -strukturen