Output.Rocks verwendet eine einheitliche API für die Erstellung von Dokumenten und E-Mails. Über einen einzigen POST Request an api/renderings/ werden sowohl Dokument- als auch E-Mail-Vorlagen mit demselben template-Identifier angesprochen.

Input & Output Flow

Kommt ein API Call bei Output.Rocks an, wird zuerst der darin angegebene Identifier überprüft.

Wenn Group Identifier bei E-Mail-Vorlagen und Dokument-Vorlagen identisch benannt sind, werden diese durch einen Request gleichzeitig ausgelöst und deren Bedingungen geprüft.

Die Weiterleitung erfolgt dann über konfigurierte Webhooks oder SMTP-Server.

Zugangsdaten-Verwaltung

Mit dem Backend-Bereich Zugangsdaten speichern Sie zentral alle Secrets, API-Schlüssel oder SFTP-Passwörter, die anschließend in Webhooks und Folgeaktionen verwendet werden. Damit müssen Integrationen keine sensitiven Strings mehr direkt im Webhook-Formular enthalten.

Auch für die Verwendung externer Email-Server können Sie so Zugangsdaten hinterlegen.

Syntax <<credentials.identifier>>

Verwenden Sie z.B. <<credentials.my_api_key>>, um den Wert des Zugangsdaten-Datensatzes my_api_key einzusetzen.

• Die Syntax funktioniert in allen Feldern, die als Text/JSON gespeichert werden und vor dem Request durch Platzhalter-Ersetzungen laufen.
• Sie lässt sich mit anderen Quellen kombinieren, z.B. https://api.partner.tld/<<credentials.partner_tenant>>/<<data.customer.id>>.

Einsatz im Backend

Für Standard- und OAuth2-Webhooks (z.B. Powercloud-Helper, SharePoint, DropBox, SFTP) können Sie so Zugangsdaten in allen Textfeldern wie Base-URL, Client-ID, Client-Secret oder Tokens nutzen, zBsp. der Webhooks im Backend.

E-Mail

E-Mails funktionieren nach demselben Prinzip wie Dokumente: Sie enthalten Platzhalter, Standardwerte, Logik und wiederverwendbare Komponenten.

Aber für den eigenen Rendering-Prozess werden E-Mails in den Sektionen E-Mail Grundgerüst und E-Mail-Vorlagen als HTML oder Reintext gespeichert und verwaltet – nicht als .docx Vorlagen. So können sie als Dateien entweder an einen externen Webhook-Endpunkt oder über einen konfigurierten SMTP-Server versendet werden.

E-Mail Rendering-Prozess

Für den E-Mail-Versand verfolgt Output.Rocks einen hierarchischen Ansatz, bei dem mehrere Ebenen von Vorlagen ineinandergreifen.

E-Mail-Vorlagen

Struktur einer E-Mail-Vorlage

E-Mail-Vorlagen haben etwas mehr Komplexität als Dokument-Vorlagen. Im Backend finden sich folgende wichtige Abschnitte:

<<{ifBlank(kunde.rechnungsemail, kunde.email)}>>

Syntax in E-Mail-Vorlagen

Die Syntax in E-Mail-Vorlagen ist ähnlich der in Dokumenten, mit einigen wichtigen Unterschieden:

<table>
  <!-- <<cs_{!isBlank(kunde.rechnungsemail)}>> -->
  <tr>
    <td>Rechnungsemail</td>
    <td><!-- <<kunde.rechnungsemail>> --></td>
  </tr>
  <!-- <<else>> -->
  <tr>
    <td>Email</td>
    <td><!-- <<kunde.email>> --></td>
  </tr>
  <!-- <<es_>> -->
</table>

<<cs_{refLookupExists("email_text_body")}>>
<<refLookup:email_text_body>>
<<es_>>

Tipps für E-Mail-Vorlagen

Bei der Erstellung effektiver E-Mail-Vorlagen sollten Sie folgende Punkte beachten:

• Verwenden Sie responsive HTML, das auf verschiedenen E-Mail-Clients und Geräten gut aussieht
• Halten Sie Betreffzeilen kurz, prägnant und relevant (40-50 Zeichen ideal)
• Nutzen Sie das E-Mail Grundgerüst für ein konsistentes Erscheinungsbild
• Testen Sie Ihre Vorlagen regelmäßig in verschiedenen E-Mail-Clients
• Verwenden Sie aussagekräftige Identifier für einfache Wartung
• Fügen Sie sinnvolle Fallback-Optionen für kritische Datenfelder hinzu
• Denken Sie an internationalisierte Inhalte für mehrsprachige Kommunikation

Review-Prozess für Dokumente und E-Mails

Ein optionaler Review-Prozess ergänzt sowohl Dokument- als auch E-Mail-Vorlagen um das Feld Review Condition / Freigabe-Bedingung. Standardwert ist false; Sie können dort mit der Symfony Expression Language jede Bedingung hinterlegen, die zBsp. auch für Group Conditions zulässig ist.

• Aktivierung: Liefert die Review Condition bei der Auswertung der Rendering-Daten true, wird das Dokument oder die E-Mail zwar gerendert, aber noch nicht versendet oder an Webhooks ausgeliefert.
• Dashboard-Hinweis: Im Dashboard des Backends erscheint dann eine Meldung, die direkt in die Liste „Review erforderlich“ führt. Dort sehen Sie Identifier, Mandant/SubClient, Priorität und Zeitstempel der angehaltenen Renderings.
• manuelle Review-Entscheidung im Backend:
  • Freigeben löst unmittelbar alle ursprünglich zugeordneten Webhooks in der hinterlegten Priorität aus; E-Mails verlassen die Queue und werden versendet.
  • Ablehnen überspringt sämtliche Versandprozesse. Das Rendering wechselt ohne weitere Aktionen in den Status done, bleibt aber auditierbar dokumentiert.

Mit dieser Review-Schicht lassen sich Vier-Augen-Prüfungen, manuelle Stichproben oder regulatorische Freigaben in bestehenden Workflows verankern, ohne zusätzliche Templates oder Mandantenduplikate verwalten zu müssen.

Webhooks

Webhooks sind leistungsstarke Integrationspunkte, die Output.Rocks mit Ihren bestehenden Systemen und Diensten verbinden. Mit über 30 vordefinierten Webhook-Typen bietet Output.Rocks Integrationen für diverse Anwendungsfälle – von Cloud-Speicher-Uploads (DropBox, SharePoint, SFTP und Druckserver) über Branchenlösungen (Powercloud, Chargecloud) bis hin zu Workflow-Automatisierungen (N8N).

Jeder Webhook-Typ ist für spezifische Ereignisse optimiert, wie Dokumentengenerierung, E-Mail-Versand, Fehlerbehandlung oder Nutzerinteraktionen, und ermöglicht so eine nahtlose Kommunikation zwischen Systemen ohne manuelles Eingreifen.

Webhooks funktionieren nach dem Prinzip der asynchronen Kommunikation. Sobald ein bestimmtes Ereignis in Output.Rocks eintritt – wie die erfolgreiche Generierung eines Dokuments oder der Versand einer E-Mail – sendet das System automatisch eine POST-Anfrage an eine von Ihnen definierte URL.

Ähnlich wie bei Vorlagen-Gruppen können auch Webhooks mit bedingter Logik konfiguriert werden. Jeder Webhook benötigt einen eindeutigen Identifier und kann optional mit einem Group Identifier versehen werden. Mehrere Webhooks mit demselben Group Identifier werden durch ihre Group Condition unterschieden. Diese Bedingungen werden in der Symfony Expression Language formuliert und greifen sowohl auf Daten im JSON-Payload (über data) als auch auf Metadaten (über metadata) zu.

Typische Webhook-Bedingungen (Group Conditions)

Verfügbare Webhook-Integrationen

Output.Rocks bietet eine umfangreiche Sammlung vorkonfigurierter Webhook-Integrationen, die Sie für verschiedene Anwendungsfälle nutzen können. Jede Integration bietet spezifische Konfigurationsmöglichkeiten, die auf den jeweiligen Anwendungsfall zugeschnitten sind.

Die Integration von Webhooks in Ihren Workflow bietet erhebliche Vorteile für die Automatisierung. Durch die Konfiguration von Webhook-Endpunkten in Ihrem System können Sie nahtlos Aktionen wie Versand oder Archivieren von E-Mails auslösen, das Aktualisieren von Kundendatensätzen, Folgeprozessen oder die Benachrichtigung relevanter Stakeholder, sobald ein Dokument erstellt oder andere Bedingungen erfüllt sind.

Beispiel: Credentials im E-Mail-Webhook einsetzen

Wenn E-Mails per Webhook (z.B. Mailgun, Powercloud Custom API oder interne REST-Endpunkte) zugestellt werden, können Sie die in Zugangsdaten gespeicherten Secrets direkt in den Request einbinden:

{
  "config": {
    "options": {
      "headers": {
        "Authorization": "Bearer <<credentials.mailgun_api_key>>"
      },
      "json": {
        "recipient": "<<data.customer.email>>",
        "template_id": "<<or.template.identifier>>"
      }
    }
  }
}

Der Authorization-Header greift auf das Credential mailgun_api_key zu, während andere Felder weiterhin Payload-Daten (data.*) oder App-Werte (or.*) nutzen. Dadurch bleiben API-Schlüssel zentral verwaltet und können rotiert werden, ohne dass einzelne Webhooks angepasst werden müssen.