Renderings
Mit CSV-Import rendern
Rendern von Dokumenten mit CSV-Dateien als Datenquelle
Mit CSV-Import können Sie mehrere Dokumente gleichzeitig rendern, indem Sie eine CSV-Datei mit Kundendaten hochladen. Jede Zeile der CSV-Datei wird als separater Rendering-Request verarbeitet und erzeugt ein eigenes Dokument. Der Import wird asynchron über den Workflow verarbeitet und in Batches von 10 Zeilen bearbeitet.
CSV-Imports sind ideal für Massenrendering von Dokumenten, z.B. monatliche Rechnungen für alle Kunden. Die CSV-Datei verwendet ein Placeholder-System, um dynamische Werte aus den CSV-Spalten in Template-Identifier, External ID, Webhook-Identifier und andere Felder einzufügen.
Diese Seite zeigt eine Liste aller Elemente, und darüber diverse Aktionen, die du ausführen kannst:
Import-Liste
Die Liste zeigt alle CSV-Imports mit ihrem aktuellen Status. Jeder Import kann mehrere Rendering-Requests erzeugen, je nach Anzahl der Zeilen in der CSV-Datei.
ID, Typ, Externe ID, Format
ID | Typ | Externe ID | Format |
|---|---|---|---|
1 | csv | external_id |
ID
Eindeutige Identifikationsnummer des CSV-Imports im System.
Typ
Zeigt den Import-Typ an – hier immer "csv" für CSV-Datei-Imports.
Externe ID
Optionaler externer Identifikator, der beim Import übergeben wurde. Wird für die Zuordnung zu externen Systemen verwendet.
Format
Das gewünschte Ausgabeformat für die gerenderten Dokumente – meist "pdf".
Status, Processed Rows, Vorlage-Identifier
Status | Processed Rows | Vorlage-Identifier |
|---|---|---|
| start | identifier_template_<<CSVspaltenname>> |
Status
Aktueller Verarbeitungsstatus des Imports: start (gestartet), processed (in Verarbeitung), done (abgeschlossen). Der Import wird asynchron über den Workflow verarbeitet.
Processed Rows
Anzahl der verarbeiteten Zeilen im Format "X of Y". Der Import wird in Batches von 10 Zeilen verarbeitet, um Memory-Overflow bei großen Dateien zu vermeiden. Der Link führt zu einer gefilterten Liste der entsprechenden Rendering Requests.
Vorlage-Identifier
Der Identifier der docx-Vorlage, die für alle Zeilen des Imports verwendet wird. Kann Placeholder enthalten (z.B. <<templateType>>), die durch CSV-Spaltenwerte ersetzt werden.
Webhook-Identifier, Mailserver-Identifier
| Webhook-Identifier | Mailserver-Identifier | Renderdaten |
|---|---|---|
| webhook_identifier | Null | #9846843 |
Webhook-Identifier
Optionaler Identifier eines Webhooks, der nach erfolgreichem Rendering aufgerufen wird. Kann Placeholder enthalten (z.B. <<webhookType>>), die durch CSV-Spaltenwerte ersetzt werden. Hier ungeprüft als String angegeben.
Mailserver-Identifier
Optionaler Identifier eines E-Mail-Servers, der für E-Mail-Versand verwendet wird. Kann Placeholder enthalten (z.B. <<mailServerType>>), die durch CSV-Spaltenwerte ersetzt werden. Hier ungeprüft als String angegeben.
Renderdaten
Link auf die gespeicherten Renderdaten (bzw. Payload) für erneute Renderings.
Kommentar
Kommentar |
|---|
| Monatliche Customer Service Sonder-Ausgaben als Batch-Rendering |
Kommentar
Optionaler Kommentar zum Import, z.B. für interne Notizen oder Beschreibungen. Kann Placeholder enthalten (z.B. <<comment>>), die durch CSV-Spaltenwerte ersetzt werden.
Mandant
| Umgebungs-Mandant | Standard für Umgebungs-Mandanten | Benutzerdefinierte ID | Farbe |
|---|---|---|---|
| (1880) Submarke 1 | NO | Null | |
| Null | YES | <<payload.value>> |
Zugeordneter Mandant des/der Import. Ermöglicht Mandanten-spezifische Konfiguration.
Kennzeichnet Import als Standard und vererbt (verfügbar) für alle Umgebungs-Mandanten.
Optionale benutzerdefinierte Kennung nach dem Rendering für externe Systeme. Wird als Referenzen des/der Import bei Callbacks übergeben und beherrscht Vorlagen-Syntax inkl. Zugriff auf Payload-Daten.
Visuelle Kennzeichnung für schnelle Identifikation des/der Import. Vor allem nützlich für Dashboard-Statistiken und Charts.
Erstellt am, Aktualisiert am
| Validatoren | Pausiert | Aktiv | Erledigt am | Erstellt am | Aktualisiert am |
|---|---|---|---|---|---|
| Null | NO | Ja | |||
| missing_street | YES | Nein |
Zugewiesene Validierungsregeln für das Import. Prüfen Ihre Bedingungen vor der Verarbeitung und aktivieren/deaktivieren das Rendering entsprechend.
Temporäre Deaktivierung des Imports. Pausierte Elemente werden nicht verarbeitet.
Aktivierungsstatus des Imports. Nur aktive Elemente werden beim Rendern berücksichtigt.
Erledigt am
Zeitpunkt, an dem die Aktion abgeschlossen wurde (UTC, lokale Anzeige je Mandant).
Erstellt am
Zeitpunkt, an dem der Import erstellt wurde (UTC, lokale Anzeige je Mandant).
Aktualisiert am
Zeitpunkt der letzten Änderung am Import, z.B. bei Statusänderungen oder Fortschrittsupdates.
Aktionen
Aktions-Dropdown
Aktions-Dropdown
Klicken Sie auf das Drei-Punkte-Menü am Ende jeder Zeile für Aktionen mit dem jeweiligen Import.
Download File
Lädt die hochgeladene CSV-Datei des Imports auf Ihren Computer herunter.
Anzeigen
Öffnet eine reine Detailansicht der kompletten Meta-Informationen und Einstellungen des Import.
Ändern
Öffnet das Bearbeitungsformular für alle Einstellungen und den Upload einer neuen Import-Version.
Löschen
Entfernt das Import dauerhaft aus dem System. Diese Aktion kann nicht rückgängig gemacht werden.
Spalten konfigurieren
Passen Sie die Anzeige der Import-Liste für bessere Übersichtlichkeit an. Spalten können per Drag-and-Drop neu angeordnet und über Checkboxen ein-/ausgeblendet werden.
Für mich anwenden : Spalten-Konfiguration wird nur für Ihren Account gespeichert und beeinflusst andere Benutzer nicht.
Als Standard anwenden : Konfiguration wird für alle Benutzer der Instanz übernommen und als neue Standard-Ansicht gesetzt.
CSV-Dateiformat und Spalten
CSV-Spezifikation
Die CSV-Datei muss folgenden Anforderungen entsprechen:
- Format: CSV (Comma-Separated Values)
- Encoding: UTF-8 (empfohlen)
- Trennzeichen: Komma (
,) - Textqualifizierer: Anführungszeichen (
") bei Sonderzeichen oder Leerzeichen - Header-Zeile: Pflicht – erste Zeile enthält die Spaltennamen
- Datenzeilen: Ab Zeile 2 – jede Zeile erzeugt einen Rendering-Request
Numerische Spaltennamen werden automatisch maskiert: Eine Spalte mit dem Namen 123 wird intern als NBR_123 gespeichert und kann über <<NBR_123>> verwendet werden.
Placeholder-System
Das Placeholder-System ermöglicht es, Werte aus CSV-Spalten dynamisch in verschiedene Felder einzufügen:
Syntax:
<<spaltenname>>– Einfacher Wert aus CSV-Spalte<<spaltenname.subkey>>– Nested Access (wenn Wert JSON-Object)<<spaltenname[0]>>– Array-Index Access<<or.expression.function(args)>>– Expression Functions
Verwendungsorte:
- Template Identifier:
<<templateType>>-templateoder<<templateType>>-<<contractNumber>> - External ID:
<<externalId>>oder<<contractNumber>> - Webhook Identifier:
<<webhookType>> - Comment:
Processing contract <<contractNumber>> - Mail Server Identifier:
<<mailServer>>
Fehlende Placeholder-Keys führen zu einer AppException: Key {key} not found in provided data. Stellen Sie sicher, dass alle verwendeten Spaltennamen in der CSV-Datei vorhanden sind.
Beispiel-CSV und Spalten-Aufschlüsselung
firstName,lastName,email,contractNumber,templateType,externalId,note
John,Doe,john.doe@example.com,CNT-2024-001,contract,EXT-001,Initial contract
Jane,Smith,jane.smith@example.com,CNT-2024-002,invoice,EXT-002,Monthly invoice
Bob,Johnson,bob.johnson@example.com,CNT-2024-003,contract,EXT-003,Contract renewalSpalten-Aufschlüsselung
| Spaltenname | Typ | Verwendung | Beispiel |
|---|---|---|---|
firstName | Datenfeld | Verfügbar in Templates als <<firstName>> | John |
lastName | Datenfeld | Verfügbar in Templates als <<lastName>> | Doe |
email | Datenfeld | Verfügbar in Templates als <<email>> | john.doe@example.com |
contractNumber | Datenfeld / Placeholder | Kann in Placeholders verwendet werden: <<contractNumber>> | CNT-2024-001 |
templateType | Placeholder | Für Template Identifier: <<templateType>>-template | contract |
externalId | Placeholder | Für External ID: <<externalId>> | EXT-001 |
note | Placeholder | Für Comment: Processing <<note>> | Initial contract |
- Spaltennamen sind case-sensitive - verwenden Sie exakt die gleiche Schreibweise wie im Header
- Leerzeichen in Spaltennamen vermeiden oder durch
_oder-trennen - Alle Spaltenwerte werden in
RenderData.value(JSON) gespeichert und sind in Templates verfügbar - Leere Zellen werden als leere Strings behandelt
- Die erste Zeile (Header) ist Pflicht und definiert die verfügbaren Spalten
Import erstellen
Beim Erstellen eines neuen CSV-Imports müssen Sie eine CSV-Datei hochladen und die Rendering-Konfiguration festlegen. Die Konfiguration unterstützt Placeholder, um dynamische Werte aus den CSV-Spalten zu verwenden.
Die CSV-Datei muss eine Header-Zeile mit Spaltennamen enthalten. Spalten können als Datenfelder in Templates verwendet werden oder als Placeholder in Template-Identifier, External ID, Webhook-Identifier und anderen Feldern.
Aktions-Buttons zum Speichern und Verwalten der Import-Konfiguration.
Verwenden Sie "Erstellen und weiteres Element hinzufügen" für effizientes Batch-Erstellen mehrerer Elemente.
Formularfelder
Externe ID
Optionaler externer Identifikator für die Zuordnung zu externen Systemen. Unterstützt Placeholder (z.B. <<externalId>> oder <<contractNumber>>), die durch CSV-Spaltenwerte ersetzt werden.
Datei
Auswahl der Datei für die CSV-Import hochladen und verwalten. Nach dem Upload wird hier der Name der Datei im Dateisystem der Cloud angezeigt.
Format
Format
Das gewünschte Ausgabeformat für die gerenderten Dokumente. Verfügbare Formate: pdf, doc, docx, odt, rtf, html, txt.
Vorlage-Identifier
Der Identifier der docx-Vorlage, die für alle Zeilen des Imports verwendet wird. Kann Placeholder enthalten (z.B. <<templateType>>), die durch CSV-Spaltenwerte ersetzt werden.
Der Vorlage-Identifier unterstützt Payload-Placeholder (z.B. <<templateType>>-template), die durch CSV-Spaltenwerte ersetzt werden. Auch kann eine CSV-Spalte mit Spaltenname verwendet werden.
Webhook-Identifier
Optionaler Identifier eines Webhooks, der nach erfolgreichem Rendering aufgerufen wird. Unterstützt Placeholder (z.B. <<webhookType>>), die durch CSV-Spaltenwerte ersetzt werden.
Mailserver-Identifier
Optionaler Identifier eines E-Mail-Servers, der für den E-Mail-Versand verwendet wird. Unterstützt Placeholder (z.B. <<mailServer>>), die durch CSV-Spaltenwerte ersetzt werden.
Kommentar
Zusätzliche Notizen und Hinweise zum/r Import für interne Verwendung.
Der Kommentar unterstützt Placeholder (z.B. Processing contract <<contractNumber>>), die durch CSV-Spaltenwerte ersetzt werden.
Mandant
Zuordnung zu einem spezifischen Umgebungs-Mandanten oder Standard-Verwendung für alle Mandanten.
Verarbeitungslogik und Workflow
Der CSV-Import wird asynchron über den ImportWorkflow verarbeitet:
- Upload: CSV-Datei wird hochgeladen und im Client-spezifischen Verzeichnis gespeichert (
{client_identifier}/{import_id}.csv) - Header-Lesen: Erste Zeile wird als Spaltennamen gelesen
- Batch-Verarbeitung: Datei wird in Batches von 10 Zeilen verarbeitet (verhindert Memory-Overflow)
- Placeholder-Ersetzung: Für jede Zeile werden Placeholder durch CSV-Spaltenwerte ersetzt
- RenderingRequest-Erstellung: Jede Zeile erzeugt einen RenderingRequest mit
Origin: IMPORT - Workflow-Start: Asynchron über Symfony Messenger Queue
- Status-Übergänge:
start→processed→done
Die Verarbeitung erfolgt asynchron, sodass große CSV-Dateien den Browser nicht blockieren. Der Fortschritt wird über processedAmount / totalAmount getrackt und in der "Processed Rows"-Spalte angezeigt.
Hinweise für weiterführende Workflows
- Rendering Requests: Jede Zeile der CSV-Datei erzeugt einen separaten Rendering Request mit
Origin: IMPORT. Über die "Processed Rows"-Spalte können Sie direkt zu den entsprechenden Requests navigieren. Die Requests sind überRenderingRequest.importmit dem Import verknüpft und in EasyAdmin über Import-ID filterbar. - Dokumente: Nach erfolgreichem Rendering finden Sie die erzeugten Dokumente in der Dokumenten-Liste.
- E-Mails: Wenn E-Mail-Versand konfiguriert ist, werden die entsprechenden E-Mail-Prozesse erstellt.
- Prozess-Management: Den aktuellen Status aller Import-Prozesse können Sie im Prozess-Leitstand überwachen.
- Fehlerbehandlung: Fehlende Placeholder-Keys oder ungültige Expressions führen zu AppExceptions, die in den Workflow-Logs der Import-Entity dokumentiert werden.