Datenkontexte im Rendering | Output.Rocks Documentation

Dieselben Renderdaten tauchen an mehreren Stellen des Ablaufs auf, aber unter unterschiedlichen Namen und zu unterschiedlichen Zeitpunkten. Diese Übersicht hilft bei der Wahl einer Bedingung und beim Aufbau von Datenmapping-Regeln, Validatoren und Webhooks.

Ablauf und Datenstand

Rendering Request: Das eingehende data und die Request-Metadaten werden gespeichert.
Mapping: PHP-Mappings ändern Request-Felder und schreiben berechnete Werte nach data.or.
Request-Pre-Rendering und Zuordnung: Request-Pre-Rendering-Webhooks können Daten ergänzen. Wird ein Gruppen-Identifier angefordert, wählen Gruppenbedingungen anhand des jetzt verfügbaren Datenstands Vorlagen aus. Danach werden App-Daten für die gefundenen Vorlagen erzeugt und die passenden Webhooks zugeordnet.
Prozess-Pre-Rendering und Validierung: Pre-Rendering-Webhooks können die Daten des bereits zugeordneten Dokument- oder E-Mail-Prozesses ergänzen. Zugeordnete Validatoren prüfen anschließend dessen Renderdaten.
Rendering und Nachverarbeitung: Erst jetzt entstehen Dokumentdatei beziehungsweise E-Mail-Inhalt. Post-Rendering-Webhooks und Archivierung können diese Artefakte verwenden.

Gruppenbedingungen für Vorlagen und Webhooks werden nur beim passenden Gruppen-Identifier ausgewertet. Ein direkt angeforderter Template- oder Webhook-Identifier umgeht die Gruppenbedingung. Bei einer Gruppenauswahl kann ein Status, der erst später durch Validierung, Rendering oder E-Mail-Zustellung entsteht, die Auswahl nicht nachträglich ändern. Für spätere Fehler- und Zustellereignisse gibt es eigene Webhook-Typen beziehungsweise den Zustellstatus-Trigger.

Bedingungen mit ExpressionLanguage

Bedingungen für Gruppen, Mappings und Validatoren verwenden Arrays und die bedingte Syntax. Der genaue Inhalt richtet sich nach der Phase:

Variable	Inhalt	Beispiel
`data`	Aktuelle Renderdaten. Gruppenbedingungen sehen zusätzlich bereits berechnete App-Daten, soweit sie in dieser Phase vorhanden sind. Validatoren erhalten nur die Renderdaten (`Value`).	`(data['kunde']['typ'] ?? '') == 'premium'`
`metadata`	Metadaten des Rendering Requests.	`(metadata['quelle'] ?? '') == 'portal'`
`request`	Request- und gegebenenfalls Prozessfelder. Die Schlüssel hängen von der jeweiligen Bedingung ab.	`(request['template'] ?? '') == 'rechnung'`
`standard`	Für Mandant, Umgebungs-Mandant, Marke und Auflösungszeitpunkt aufgelöste Standardwerte.	`(standard['region'] ?? '') == 'Nord'`

Ein fehlender Schlüssel sollte mit ?? abgefangen werden. Klammern sind bei Vergleichen nötig: (data['kunde']['typ'] ?? '') == 'premium'. Die Punktnotation kunde.typ ist hier keine verfügbare Variable.

Bei der Vorlagenauswahl sind Komponenten noch nicht berechnet. Eine spätere Webhook- oder Anhangsbedingung kann dagegen bereits berechnete App-Daten sehen. Verlassen Sie sich daher bei einer Vorlagen-Gruppenbedingung auf Eingabedaten, Request-Pre-Rendering-Ergebnisse, Mapping-Werte und Standardwerte.

Eine Mapping-Bedingung läuft noch vor den Request-Pre-Rendering-Webhooks. Ergebnisse dieser Webhooks können daher die Zuordnung, aber nicht rückwirkend das Mapping beeinflussen.

request ist kein überall identisches Objekt. Bei der Vorlagen- und Webhook-Zuordnung stehen unter anderem externalId, template, format, webhook, comment, emailServer, metadata und brandIdentifier bereit. Bei einer Bedingung für einen bereits angelegten Dokumentprozess können zusätzlich processTemplate und processTemplateGroup vorhanden sein. Eine Validatorbedingung erhält nur template, format, webhook und mailServer.

PHP-Datenmapping

Ein Custom Mapping hat eigene PHP-Variablen. $data enthält die Renderdaten (Value), $request die Felder externalId, template, format, webhook, comment, emailServer und metadata. $standardValues enthält die aufgelösten Standardwerte. Die PHP-Variablen heißen also anders als die Variablen einer ExpressionLanguage-Bedingung.

$mappedData = [
    'kanal' => $request['metadata']['quelle'] ?? 'unbekannt',
    'region' => $standardValues['region'] ?? '',
];

return ['request' => $request, 'mappedData' => $mappedData];

Das Ergebnis liegt danach unter data['or']['kanal'] und data['or']['region'] beziehungsweise in der Vorlage unter <<or.kanal>> und <<or.region>>. Das Mapping muss alle Request-Felder und ein Array mappedData zurückgeben. Gleichnamige Schlüssel unter or werden ersetzt; nicht gesetzte Schlüssel bleiben erhalten. Nachfolgende Mappings sehen die Änderungen.

Datenvalidierung

Validatoren laufen nach Pre-Rendering und vor dem eigentlichen Rendering. Ihre Bedingung sieht in data nur die gespeicherten Renderdaten (Value), einschließlich or aus Mappings und erfolgreicher Pre-Rendering-Webhooks. Berechnete App-Daten (AppValue, etwa Komponenten) gehören nicht zu diesem data. metadata enthält die Request-Metadaten; standard enthält aufgelöste Standardwerte.

(data['kunde']['email'] ?? '') != ''

Bei normaler Logik ist das Ergebnis true gültig. Mit Ungültig, wenn die definierte Bedingung "true" zurückgibt kehrt sich das Ergebnis um. Ein fehlgeschlagener Validator macht den Prozess invalid und hinterlegt die fehlgeschlagenen Validatoren. Ein technischer Fehler bei der Auswertung oder im Rendering führt dagegen zu blocked. Die Datenvalidierung wird nur ausgeführt, wenn das Modul Datenvalidierung für den Mandanten aktiv ist und der Vorlage Validatoren zugeordnet sind.

Webhooks und Archiv

Bei Custom- und Custom-OAuth2-Webhooks werden Platzhalter in URL, Headern und Payload aus den zum Ausführungszeitpunkt verfügbaren Renderdaten aufgelöst. Die Renderdaten liegen direkt an der Wurzel des Platzhalterkontexts: Aus { "kunde": { "nummer": "C-42" } } wird <<kunde.nummer>>. Daneben sind <<metadata>> und <<metadata.quelle>> für Request-Metadaten verfügbar; der bisherige Alias <<or.metadata.quelle>> funktioniert weiterhin. Ein einzelner Platzhalter als JSON-Wert kann auch ein ganzes Objekt ergeben. Ein Request-Pre-Rendering-Webhook hat noch kein Dokument und keine E-Mail; <<document.*>> und <<email.*>> stehen erst beim entsprechenden Prozess nach dem Rendering zur Verfügung.

Für einen invalid- oder blocked-Callback gibt es Fehler-Webhook-Typen mit und ohne OAuth2. Sie bieten <<error.status>>, <<error.phase>>, <<error.message>>, <<error.requestId>>, <<error.processId>> und <<error.failedValidators>>. Ein solcher Callback kann schon ohne fertige Datei laufen. Die genaue Konfiguration und die Webhook-Typen stehen auf der Webhook-Seite.

Die Archivierung hat ein eigenes Archiv-Metadaten-Mapping. Dort bezeichnet <<data.*>> die zusammengeführten Render- und App-Daten des Prozesses, <<metadata.*>> dessen Metadaten. <<document.*>> und <<email.*>> ergänzen je nach Archivquelle Datei- und E-Mail-Felder. Nur explizit konfigurierte Werte werden als Archiv-Metadaten gespeichert.