ZIP-Datei entpacken

Der Service Task „ZIP-Datei entpacken" extrahiert ein ZIP-Archiv und gibt die enthaltenen Dateien als neue Datei-Referenzen zurück. Zusätzlich werden die Dateien nach Ordnerstruktur gruppiert, sodass Folgeaufgaben gezielt auf bestimmte Unterordner zugreifen können. So lassen sich z. B. ZIP-Exporte aus Drittsystemen oder mehrere hochgeladene Dateien in einem Rutsch in den Prozess übernehmen.

Input-Parameter

Die folgenden Felder werden als Eingabe für den Task benötigt:

{
  "zip_file": {
    "referenceId": "...",
    "filename": "archiv.zip",
    "contentType": "application/zip"
  },
  "filter": "*.pdf",
  "output_prefix": "",
  "maxUncompressedBytes": 524288000,
  "maxFiles": 1000,
  "maxCompressionRatio": 100
}

Erläuterung:

zip_file: Datei-Referenz auf das zu entpackende ZIP-Archiv (Pflichtfeld).
filter: Glob-Muster oder Array von Glob-Mustern, um nur bestimmte Einträge zu extrahieren (optional). Unterstützt:
- * – beliebige Zeichen außer /
- ** – beliebige Zeichen inklusive / (rekursiv)
- ? – genau ein Zeichen
- Vergleich erfolgt case-insensitive.
- Beispiele: "*.pdf", ["*.pdf", "*.csv"], "rechnungen/**".
output_prefix: Präfix, das jedem ausgegebenen Dateinamen vorangestellt wird (optional, Standard: leer).
maxUncompressedBytes: Maximale unkomprimierte Gesamtgröße in Bytes (optional, Standard: 524288000 = 500 MB). Wird der Wert überschritten, bricht der Task mit einem Fehler ab.
maxFiles: Maximale Anzahl Einträge im ZIP (optional, Standard: 1000).
maxCompressionRatio: Schutz vor Zip-Bomben. Überschreitet die Kompressionsrate (unkomprimiert/komprimiert) diesen Wert, wird der Task abgebrochen (optional, Standard: 100).

Keine Filter angegeben

Ohne filter werden alle Dateien im Archiv extrahiert. Verzeichniseinträge selbst werden grundsätzlich übersprungen – nur Dateien werden ausgegeben.

Output

Der Task gibt eine flache Liste aller entpackten Dateien sowie eine nach Ordnern gruppierte Struktur zurück.

{
  "files": [
    {
      "referenceId": "...",
      "filename": "R2024-001.pdf",
      "contentType": "application/pdf"
    },
    {
      "referenceId": "...",
      "filename": "B-042.csv",
      "contentType": "text/csv"
    }
  ],
  "groups": {
    "rechnungen": [
      {
        "referenceId": "...",
        "filename": "R2024-001.pdf",
        "contentType": "application/pdf"
      }
    ],
    "buchungen": [
      {
        "referenceId": "...",
        "filename": "B-042.csv",
        "contentType": "text/csv"
      }
    ],
    "": []
  },
  "count": 2,
  "skipped": 0
}

Erläuterung:

files: Flache Liste aller extrahierten Dateien im Standard-Datei-Schema (referenceId, filename, contentType). Diese Einträge können direkt an andere Service Tasks wie „CSV-Datei strukturiert auslesen" oder „PDF aufteilen" weitergegeben werden.
groups: Dateien gruppiert nach ihrem ZIP-Ordner. Der Schlüssel ist der Ordnerpfad innerhalb des Archivs; "" enthält Dateien, die direkt im Wurzelverzeichnis liegen.
count: Anzahl der extrahierten Dateien.
skipped: Anzahl der Einträge, die durch den Filter ausgeschlossen wurden.

Namenskonflikte

Existieren im Archiv mehrere Dateien mit demselben Namen (z. B. rechnung.pdf in verschiedenen Ordnern), wird automatisch ein Zähler angehängt: rechnung.pdf, rechnung_2.pdf, rechnung_3.pdf. Die Zuordnung in groups bleibt dabei korrekt.

JSONata-Beispiele

Komplettes Archiv entpacken:

{
  "zip_file": $.archiv
}

Nur PDFs extrahieren:

{
  "zip_file": $.archiv,
  "filter": "*.pdf"
}

Mehrere Typen gleichzeitig zulassen:

{
  "zip_file": $.archiv,
  "filter": ["*.pdf", "*.csv"]
}

Nur Dateien aus einem bestimmten Ordner:

{
  "zip_file": $.archiv,
  "filter": "rechnungen/**"
}

Typische Anwendungsfälle

Datenmigration aus Drittsystemen: Ein ZIP-Export enthält Ordner wie rechnungen/, buchungen/, belege/. Über groups.rechnungen werden gezielt die Rechnungen weiterverarbeitet, groups.buchungen geht an einen anderen Zweig.
Batch-Upload: Mehrere PDFs werden als ZIP hochgeladen. Jede Datei wird anschließend in einem Multi-Instance-Subprozess separat verarbeitet.
Datenimport: Ein ZIP enthält mehrere CSV-Dateien im Wurzelverzeichnis. Über groups[""] werden die Root-CSVs an „CSV-Datei strukturiert auslesen" übergeben.

Weiterverarbeitung im Prozess

Die Gruppen lassen sich direkt in Multi-Instance-Subprozessen als Kollektion verwenden:

{
  "collection": $.groups.rechnungen
}

Jede Rechnung wird so einzeln an den Subprozess übergeben und kann dort z. B. durch „PDF-Text extrahieren (Rechnung)" laufen.

Für einfache Fälle ohne Ordnerstruktur reicht die flache Liste:

{
  "collection": $.files
}

Hinweise

Die ausgegebenen Datei-Referenzen enthalten ausschließlich referenceId, filename und contentType. Die Ordner-Information liegt ausschließlich in den Schlüsseln von groups.
Verzeichniseinträge im ZIP werden übersprungen; nur Dateien werden extrahiert.
Einträge mit Path-Traversal-Mustern (.., absolute Pfade, Backslashes) werden aus Sicherheitsgründen abgewiesen.
Einträge mit verdächtig hoher Kompressionsrate (über maxCompressionRatio) werden als Zip-Bombe interpretiert und führen zum Abbruch.
Die Gesamtgröße und Anzahl der Einträge werden vor der Extraktion aus dem Central Directory geprüft – so wird das Archiv nicht erst vollständig entpackt, bevor ein Limit greift.

Tipp

In Kombination mit einem Multi-Instance-Subprozess lässt sich dieser Service ideal für parallele Verarbeitung nutzen: groups.rechnungen als Kollektion, Element-Variable rechnung – und jede Rechnung durchläuft eigenständig Extraktion, Prüfung und Buchung.