Was sind funktionale Daten?

Ihre Daten können in Output.Rocks Vorlagen intelligent verarbeitet werden, um Ihre Kunden- und Systemdaten nach genau Ihren Anforderungen zu präsentieren. Mit Formeln, Bedingungen und Logik-Funktionen können Sie dynamische Dokumente erstellen, die sich automatisch an verschiedene Szenarien anpassen.

Wie funktioniert's?

Das Grundprinzip ist einfach: Sie nutzen spezielle Syntax-Elemente in Ihren Vorlagen, um:

Berechnungen durchzuführen (z.B. Verbrauchswerte, Preise)
Bedingungen zu prüfen (z.B. Kundenstatus, Vertragstyp)
Daten zu formatieren (z.B. Zahlen, Datumsangaben)
Wiederholungen zu steuern (z.B. Listen, mehrere abgerechnete Produkte)

Die ersten Schritte

Expressions und mathematische Operationen
Bedingte Logik
Wiederholende Abschnitte
Praktische Beispiele

1. Expressions und mathematische Operationen

Alle Beispiele in diesem Abschnitt basieren auf diesem JSON-Datensatz:

{
  "kunde": {
    "vorname": "Max",
    "nachname": "Mustermann",
    "nummer": "K12345",
    "typ": "privat",
    "adresse": "Energieweg 42, 12345 Stromstadt",
    "seit": "2022-05-01",
  },
  "verbrauch": {
    "aktuell": 3500,
    "vorjahr": 3200,
    "zaehlerstaende": [
      {
        "datum": "2023-01-01",
        "wert": 24002
      },
      {
        "datum": "2023-06-01",
        "wert": 25754
      },
      {
        "datum": "2024-01-01",
        "wert": 27502
      }
    ]
  },
  "tarif": {
    "name": "Ökostrom Basis",
    "grundpreis": 12.50,
    "arbeitspreis": 0.32
  }
}

Erinnerung: Platzhalter und Variablen

Der einfachste Weg, Daten in Ihr Dokument einzufügen, sind Platzhalter, die sich auf ihr JSON-Objekt beziehen.

Variablen dagegen funktionieren nur lokal in einer Vorlage und können externe Daten und Text beinhalten oder ganze Objekte referenzieren.

<<$kundenName=kunde.vorname + ' ' + kunde.nachname>>

Sehr geehrte(r) <<$kundenName>>,
Ihre Kundennummer lautet: <<kunde.nummer>>

Mathematische Operationen

Sie können Berechnungen aus ihren Datendirekt in den Vorlagen durchführen:

Ihr Mehrverbrauch beträgt: 
<<verbrauch.aktuell - verbrauch.vorjahr>> kWh

Für komplexere Berechnungen sollten Sie die Expression-Syntax mit geschweiften Klammern verwenden: <<{verbrauch.aktuell * tarif.arbeitspreis}>>

Dabei stehen Ihnen folgende mathematische Operationen zur Verfügung:

Grundlegende Operationen

+ Addition
- Subtraktion
* Multiplikation
/ Division
% Modulo (Rest)
^ Potenzierung

Vergleichsoperatoren

== Gleichheit
!= Ungleichheit
> Größer als
< Kleiner als
>= Größer oder gleich
<= Kleiner oder gleich

Logische Operatoren

&& UND
|| ODER
! NICHT

Mathematische Funktionen

abs(x) Absoluter Wert
ceil(x) Aufrunden
floor(x) Abrunden
round(x) Runden
min(x,y) Minimum
max(x,y) Maximum
sqrt(x) Quadratwurzel

Beispiele für komplexe Berechnungen:

Durchschnitt: <<$durchschnitt=(wert1 + wert2 + wert3)/3>>
Prozentuale Änderung: <<$aenderung=((neu-alt)/alt)*100>>
Bedingte Berechnung: <<$preis=grundpreis + (verbrauch > 1000 ? (verbrauch-1000)*zusatzpreis : 0)>>
Minimum/Maximum: <<$min=min(wert1, min(wert2, wert3))>>

Formatierung von Werten

Zahlen und Datumsangaben können formatiert werden:

Arbeitspreis: <<cs_number_format:tarif.arbeitspreis:0.00>> EUR/kWh
Kunde seit: <<{dateFormat(kunde.seit, 'dd.MM.yyyy', 'yyyy-MM-dd')}>>

2. Bedingte Logik

Bedingte Logik wird entweder mit <<cs_>> (condition start), <<else>> (else) und <<es_>> (end section) definiert.

Einfache Bedingungen

<<cs_{verbrauch.aktuell > verbrauch.vorjahr}>>
  Ihr Stromverbrauch ist gestiegen.
<<else>>
  Ihr Stromverbrauch ist gesunken.
<<es_>>

Verschachtelte Bedingungen

Bei verschachtelten Bedingungen werden weitere Bedingungen angehängt, indem beliebig viele 'else' Sektionen mit der Syntax <<else_{condition}>> versehen werden.

Eine letzte 'else' Sektion kann dann ohne Bedingen den Fall abdecken, dass alle vorherigen Bedingungen nicht zutreffen.

<<cs_{verbrauch.aktuell > 5000}>>
  Hoher Verbrauch
<<else_{verbrauch.aktuell > 3000}>>
  Mittlerer Verbrauch
<<else>>
  Niedriger Verbrauch
<<es_>>

Sie können auch komplexe Bedingungen mit logischen Operatoren erstellen und verbinden: <<cs_{kunde.typ='privat' && verbrauch.aktuell < 4000}>> Inhalt wenn 2 Bedingungen wahr sind <<es_>>

3. Wiederholende Abschnitte

Wiederholende Abschnitte werden mit <<rs_>> (repeat section) und <<es_>> (end section) definiert.

Sich wiederholende Abschnitte sind datenabhängige Schleifen, die ihren Bezugsrahmen aus einem Objekt oder einer Liste von Objekten beziehen. Diese werden in den definierenden Tags mitgegeben, ähnlich wie bei Bedingungen in der Form <<rs_objekt>>...<<es_objekt>>.

Eine Schleife durchläuft im Standardfall alle Elemente eines Objekts. Dadurch stehen ihr auch alle Werte und Objekte innerhalb des deklarierten Namens zur Verfügung, so dass diese relativ zum aktuellen Element angesprochen werden können.

Die Werte <<verbrauch.zaehlerstaende[i].datum>> können so innerhalb der Schleife <<rs_verbrauch.zaehlerstaende>>...<<es_verbrauch.zaehlerstaende>> einfach als <<datum>> angesprochen werden.

Hier zum Beispiel eine Liste von Ablesungen:

Ihre letzten Ablesungen:

<<rs_verbrauch.zaehlerstaende>>
  <<$itemnum>>. Ablesung am <<{dateFormat(datum, 'dd.MM.yyyy', 'yyyy-MM-dd')}>>: <<wert>> kWh
<<es_verbrauch.zaehlerstaende>>

In Schleifen stehen Ihnen spezielle Variablen zur Verfügung:

<<$itemnum>>: Aktuelle Position (1-basiert)
<<$itemidx>>: Aktuelle Position (0-basiert)
<<$size>>: Gesamtanzahl der Elemente

4. Praktische Beispiele

Verbrauchsanalyse

Hier ein Beispiel für eine Verbrauchsanalyse, bei der Durchschnitt und prozentuale Änderung des Verbrauchs zum Vorjahr berechnet werden.

<<$durchschnitt=(verbrauch.aktuell+verbrauch.vorjahr)/2>>
<<$prozentaenderung=((verbrauch.aktuell-verbrauch.vorjahr)/verbrauch.vorjahr)*100>>

Durchschnittsverbrauch der letzten 2 Jahre: <<cs_number_format:$durchschnitt:#,##0>> kWh
Änderung zum Vorjahr: <<cs_number_format:$prozentaenderung:+#,##0.0;-#,##0.0>>%

Verbrauchswarnung und Tarifwechsel-Hinweis

Hier ein Beispiel für eine Verbrauchswarnung und Tarifwechsel-Hinweis, bei der die aktuelle Verbrauchsdaten mit dem Durchschnitt des Tarifes verglichen werden.

<<if verbrauch.aktuell > 2000>>
    [Im .docx als Warnung formatiert]
    Achtung: Ihr Verbrauch von <<cs_number_format:verbrauch.aktuell:#,##0>> kWh ist um <<cs_number_format:((verbrauch.aktuell-2000)/2000)*100:+#,##0.0;-#,##0.0>>% über dem Durchschnitt von 2000 kWh ihres Tarifes <<tarif.name>>. 
    
    Wir empfehlen daher einen Tarifwechsel.
    [/Warnung]
<<endif>>

Tipps für die Entwicklung

Testen Sie Ihre Vorlagen im Vorlageneditor
Nutzen Sie <<dump:$top>> um tatsächlich verwendete Daten zur Fehlersuche zu sehen
Dokumentieren Sie komplexe Berechnungen
Verwenden Sie aussagekräftige Variablennamen

Verarbeitung von Datumsangaben

Hier ein Beispiel für die Verarbeitung und Formatierung von Datumsangaben, bei der die erste und letzte Ablesung sowie die Anzahl der Tage zwischen ihnen berechnet werden.

Alle Optionen und die Syntax zur Formatierung von Datumsangaben sind unter Ausdrücke -> Datumsfunktionen beschrieben.

<<$ersteAblesungDatum={dateFormat(verbrauch.zaehlerstaende[F].datum,'dd.MM.yyyy', 'yyyy-MM-dd')}>>
<<$letzteAblesungDatum={dateFormat(verbrauch.zaehlerstaende[L].datum,'dd.MM.yyyy', 'yyyy-MM-dd')}>>
<<$tageSeitErsterAblesung={dateDiff(verbrauch.zaehlerstaende[F].datum, verbrauch.zaehlerstaende[L].datum, 'days', 'yyyy-MM-dd')}>>

Die erste Ablesung war am <<$ersteAblesungDatum>>.
Die letzte Ablesung war am <<$letzteAblesungDatum>>.
Zwischen der ersten und letzten Ablesung liegen <<$tageSeitErsterAblesung>> Tage.

Wichtige Datumsfunktionen:

dateFormat(datum, outputFormat, inputFormat, outputLocale, inputLocale): Formatiert ein Datum
$nowUTC: Gibt das aktuelle Datum und die Uhrzeit in UTC zurück
dateDiff(datum1, datum2, units, inputFormat): Berechnet die Differenz zwischen zwei Datumswerten in der angegebenen Einheit (z.B. 'days')
dateAdd(datum, anzahl, units): Addiert eine bestimmte Zeit zu einem Datum
dateSub(datum, anzahl, units): Subtrahiert eine bestimmte Zeit von einem Datum

Hinweis: Die Ausgabe von Datumsfunktionen sollte als Expression bei der Variablendeklaration erfolgen: <<$variable={dateFormat(...)}>>

Bilder mit Logik in Komponenten dynamisch einbinden

Bilder und Grafiken können logisch reagieren auf eingehende Daten, wobei es oft nützlich ist diese komplexe Logik in einer separaten Komponente zu verwalten.

Die Verwendung von Komponenten wird in der Dokumentation unter Module & Validierungen beschrieben.
Das dynamische Einbinden von Bildern wird in der Einführung zum Templating beschrieben.

Beachten Sie, dass die Variable in der Vorlage den Bildpfad übergeben muss, nicht den Namen des Identifiers des Bildes. Deswegen enthält die Komponente als Output den Identifier des Bildes (welcher für den Bildpfad steht) in der Objekt-Form <<bildIdentifier>> (und nicht als String 'bildIdentifier').

Die ist ein Beispiel für eine Komponente, die ein Bild anhand der Vertragsart eines Kunden dynamisch auswählt und anzeigt. Die hier verwendeten Bilder müssen mit den Identifiern logo_oekostrom, logo_oekostrom_plus und logo_default im Backend angelegt sein.

<<$logoIdentifier=component.tarifLogo>> 

[Bildplatzhalter mit Textmarke: img_var_logoIdentifier]

Funktionale Daten: Formeln und Bedingungen