Dateien in Pantarey

Eine Datei liegt in Pantarey nie in einem Datensatz oder in einer Prozessnachricht, sondern im Dateispeicher des Kontos. Datensätze, Nachrichten, Aufgaben und E-Mails tragen nur einen Verweis darauf: ein kleines JSON-Objekt mit Kennung, Dateiname und Typ. Dieses eine Format gilt überall, vom Formularfeld über jeden Service bis zum KI-Assistenten. Wer es kennt, kann Dateien in jeden Schritt hineinreichen, umbenennen, sammeln und speichern, ohne sich um den Speicher selbst zu kümmern. Diese Seite beschreibt das Datei-Objekt, die Orte, an denen Dateien entstehen, die Weitergabe im Prozess, die Grenzen und die typischen Fehlermeldungen.

Das Datei-Objekt

{
  "referenceId": "01JCW3M4V5X6Y7Z8A9B0C1D2E3",
  "filename": "lieferschein-4711.pdf",
  "contentType": "application/pdf"
}

Feld	Bedeutung
referenceId	eindeutige Kennung der Datei im Speicher des Kontos; wird beim Upload oder vom erzeugenden Service vergeben. Zwischenergebnisse tragen gelegentlich ein Präfix wie temp_.
filename	Anzeigename, zum Beispiel für Anhänge, ZIP-Inhalte und Downloads
contentType	MIME-Typ wie application/pdf, image/png, text/csv
thumbnail	nur bei Bildern: kleine Vorschau als Base64-Text (ohne data:-Präfix); bei nicht unterstützten Bildformaten fehlt sie, ohne Fehler

Beim Verarbeiten liest Pantarey die Datei anhand der referenceId. filename und contentType werden aus dem Objekt übernommen und nicht gegen den Speicher geprüft; fehlen sie, nehmen die Services Ersatzwerte (bei E-Mail-Anhängen die referenceId als Name und application/octet-stream als Typ). Deshalb lässt sich eine Datei allein durch ein neues Objekt umbenennen, siehe Umbenennen.

Im Datenschema ist ein Dateifeld ein Objekt mit den Unterfeldern filename (Pflicht), contentType, referenceId und thumbnail (bei Bildern). Die Dateien jedes Kontos liegen getrennt von allen anderen Konten; der Speicher ist versioniert.

Wo Dateien entstehen

Formularfelder

Im Daten Designer bietet die Gruppe Dateien vier Typen; Mehrfach („Mehrere Werte (Liste)“) macht aus jedem eine Liste von Dateien.

Typ	Beschreibung im Designer	Erlaubt	Im Formular
Bild	JPG, PNG, WebP	image/*	Upload mit Vorschaubild (bis 200 × 200 px); ein Klick öffnet das Original
PDF	PDF-Dokument	application/pdf	Upload mit eingebetteter Vorschau und PDF ansehen & herunterladen
CSV-Datei	Tabellarische Datei	text/csv	Dateiauswahl
Datei	Beliebige Datei	alles	Dateiauswahl

In eigenen Formularen (Formly-JSON) stehen dieselben Feldtypen image, pdf und file zur Verfügung, dazu dropzone: ein Ablagebereich „Dateien hierher ziehen“ / „oder klicken zum Auswählen“ für mehrere Dateien mit der Vorgabe acceptPreset all, pdf oder images. Unpassende Dateien sortiert die Dropzone still aus; eine Meldung erscheint nur, wenn keine Datei übrig bleibt. Beim Typ file legt mimeType den erlaubten Typ exakt fest; leer oder application/octet-stream erlaubt alles. Details zu den Feldern unter Formulare.

Der Upload läuft direkt aus dem Browser in den Speicher des Kontos; als Ergebnis steht das Datei-Objekt im Formularwert und damit im Datensatz oder in der Prozessnachricht.

Benutzer-Start mit Datei-Upload

Ein Benutzer-Start mit der Kategorie Datei-Upload zeigt statt eines Formulars eine Dropzone. Zwei Einstellungen bestimmen, wie es weitergeht:

Einstellung	Werte	Nachricht
Ausführungsmodus	Pro Datei ein Prozess (Standard)	je Datei ein Vorgang mit { "uploadedFile": { … }, "$$context": { … } }
	Ein Prozess für alle Dateien	ein Vorgang mit { "uploadedFiles": [ … ], "$$context": { … } }
Akzeptierte Dateitypen	Alle Dateien, Nur PDF, Nur Bilder	Vorgabe der Dropzone

$$context enthält beim Datei-Upload zusätzlich fileUpload: true.

Benutzeraufgabe und externe Aufgabe

In einer Benutzeraufgabe gelten dieselben Formularfelder wie beim Start. PDF-Vorschau aktivieren zeigt der bearbeitenden Person neben dem Formular ein PDF, etwa die zu prüfende Rechnung.

Eine externe Aufgabe nimmt Dateien von Personen ohne Pantarey-Zugang über <upload-widget name="belege" multiple accept="pdf"> entgegen; accept ist all, pdf oder images. Der Server prüft Dateityp und Anzahl der hochgeladenen Dateien. Umgekehrt zeigt %%FILE:pfad%% eine Datei aus dem Input der Aufgabe, zum Beispiel <iframe src="%%FILE:rechnungPdf%%"> auf der Seite PDF-Freigabe; der Link ist eine Stunde gültig und funktioniert nur für Dateien, die im Input der Aufgabe stehen.

Services, die Dateien erzeugen

Service	Ergebnis	Dateiname
PDF erstellen aus Template	Datei-Objekt	Einstellung PDF-Dateiname mit $(…), Standard document.pdf
Rechnungs-PDF erstellen (mit Berechnung)	{ "invoice": { … }, "pdf": { … } }; targetInvoicePath schreibt den Verweis zusätzlich in die Rechnung	Pflicht
Komplette E-Rechnung	{ "invoice": { … }, "pdf": { … } }	konfigurierbar
E-Rechnung erstellen (ZUGFeRD)	Datei-Objekt mit eingebetteter factur-x.xml	Name des Eingangs-PDF
SEPA-Lastschriftdatei erstellen	{ "file": { …, "contentType": "application/xml" } }	optional, Standard SEPA-Lastschrift_<CORE/B2B>_<messageId>.xml
QR-Code generieren	Datei-Objekt image/png mit thumbnail	optional, Standard qrcode_<zeitstempel>.png
Dateien in ZIP verpacken	Datei-Objekt application/zip	output_filename, Standard archive.zip
ZIP-Datei entpacken	{ "files": [ … ], "groups": { "ordner": [ … ] }, "count": n }	aus dem Archiv, Dubletten mit _2, _3
PDF-Dateien zusammenführen	Datei-Objekt	filename_output, kein Standardwert
PDF-Formular ausfüllen	Datei-Objekt	Name des Eingangs-PDF
PDF aufteilen	{ "files": [ … ], "count": n }	je Teil oder Muster, Standard {name}_part-{n}.pdf
Seiten aus PDF entfernen	Datei-Objekt mit removedCount, remainingCount	Name des Eingangs-PDF
PDF in Graustufen umwandeln	{ "document": { … }, "metadata": { … } }	<name>_bw.pdf
E-Post Brief versenden	letter_pdf	Name des Briefs, Pflicht
HTTP-Anfrage (REST)	Antwort als Datei unter file	filename, sonst aus der Antwort oder download-<zeitstempel>.<ext>

Einen Service, der Excel-Dateien erzeugt, gibt es nicht.

Services, die Dateien lesen

Service	Eingabefeld
CSV-Datei strukturiert auslesen	csv_file
Excel-Datei auslesen	document
Dokument auslesen (OCR)	document
PDF analysieren	pdf
PDF Text extrahieren (Rechnung)	Datei-Objekt auf oberster Ebene
PDF-Metadaten lesen	pdf
XML-Datei in JSON umwandeln	xml (Datei-Objekt oder XML-Text)
PDF-Anhänge extrahieren	pdf; liefert Name und Inhalt der Anhänge, keine neuen Datei-Objekte
Fax versenden	document (PDF, TIFF, GIF, PNG, HTML oder Text, höchstens 10 Seiten)
Datei auf FTP-Server hochladen	fileReference, optional filenameOverwrite
Datei auf SharePoint hochladen	file_reference, optional overwrite_filename
TeamBeam: Dokumentenversand	fileReferences
E-Mail-Services (eigene Domain, Microsoft Graph, SMTP, intern)	Anhänge als Liste von Datei-Objekten
HTTP-Anfrage (REST)	jedes Datei-Objekt im Body wird als Inhalt übertragen (JSON als Base64, multipart oder file)

Ein Webhook nimmt nur JSON entgegen; Dateien kommen über Formular-Upload, externe Aufgabe oder die Antwort einer HTTP-Anfrage ins Konto.

Datenbank, Datenexport und KI-Assistent

• Datenbank: Die Datensatz-Ansicht zeigt Bilder als Vorschaubild (Klick öffnet das Original), PDFs und Dateien als Liste; ein Klick öffnet die Datei in einem neuen Tab. Hochgeladen wird über die Dateifelder in Bearbeiten oder beim Anlegen. Teilen im Menü ⋮ kopiert einen Link auf das JSON des Datensatzes, nicht auf eine Datei, siehe Datenbank.
• Datenexport: Der Schalter Dateianhänge einschließen im Datenexport legt die Dateien unter references/<referenceId> ins ZIP; Dateiname und Typ stehen im JSON des zugehörigen Datensatzes. Der Export einer einzelnen Datenstruktur enthält keine Dateien.
• KI-Assistent: Das Werkzeug get_file liefert einen 15 Minuten gültigen Download-Link zu einer Datei eines Datensatzes; Dateien werden nie im Gespräch selbst übertragen, ein Upload per Chat ist nicht möglich. Übersicht unter Werkzeuge des Assistenten.

Wie Dateien weitergereicht werden

Das Datei-Objekt ist ein normaler Wert: Es wird kopiert, wenn es in einen Datensatz, eine Nachricht, eine Aufgabe oder eine E-Mail gelangt. Alle Kopien zeigen auf dieselbe Datei im Speicher.

In der Nachricht und im Datensatz

Ein Service, der eine Datei erzeugt, legt sein Ergebnis unter dem Ergebnispfad ab, etwa rechnung_pdf; der nächste Schritt greift mit rechnung_pdf darauf zu, siehe Daten im Prozess. Ein Datenbank-Element schreibt die Datei in ein Dateifeld des Datensatzes, indem das Objekt im Input-Ausdruck an die richtige Stelle gesetzt wird:

{
  "lieferschein_nr": analyse.nummer,
  "dokument": uploadedFile
}

Umbenennen

Weil Services den Namen aus dem Objekt nehmen, reicht ein neues Objekt im Input-Ausdruck des Folgeschritts:

{
  "referenceId": rechnung_pdf.referenceId,
  "filename": "Rechnung " & rechnung.nummer & ".pdf",
  "contentType": rechnung_pdf.contentType
}

Der neue Name gilt für E-Mail-Anhänge, HTTP-Uploads, ZIP-Inhalte und den Datensatz. Die Datei im Speicher bleibt unverändert; für HTTP-Anfragen und ZIP-Archive ist filename Pflicht, ohne Namen wird die Datei dort übersprungen.

Mehrere Dateien

Mehrere Dateien sind eine Liste von Datei-Objekten, etwa ein Mehrfach-Feld, uploadedFiles beim Batch-Start oder files nach dem Entpacken. Soll jede Datei einzeln verarbeitet werden, bekommt die Aktivität im Abschnitt Schleife einen Input, der die Liste liefert; jede Iteration erhält ein Element als Nachricht, das Ergebnis ist die Liste der Einzelergebnisse unter dem Ergebnispfad. Standard sind höchstens 1000 Elemente und 40 parallele Durchläufe, siehe Schleifen. Ein Rezept dazu steht im Kochbuch.

E-Mail-Anhänge

Anhänge sind eine Liste von Datei-Objekten; nur Einträge mit referenceId werden angehängt. Beim Versand über die eigene Domain und beim internen Versand über Pantarey dürfen alle Anhänge einer E-Mail zusammen höchstens 5 MB groß sein („Gesamtgröße max. 5 MB“); größere Anhänge gehen über Microsoft Graph oder SMTP, die keine eigene Grenze in Pantarey haben.

Grenzen und Verhalten

Thema	Verhalten
Upload	Formulare und Dropzone begrenzen die Dateigröße nicht. Begrenzt werden Anhänge: 5 MB bei E-Mail (eigene Domain, intern), 20 MB für alle Dateien einer HTTP-Anfrage zusammen und für eine Datei in der HTTP-Antwort.
ZIP	Packen bis 5000 Dateien und 2 GB; Entpacken bis 500 MB entpackt und 1000 Einträge.
Nachricht	Große Nachrichten sind kein Problem; ab 3000 Zeichen lagert Pantarey sie automatisch aus.
Links	Download- und Upload-Links der App sowie %%FILE%%-Links gelten eine Stunde, get_file 15 Minuten, der Download eines Datenexports 5 Minuten.
Löschen	Wird ein Datensatz oder eine Datenstruktur gelöscht, bleiben die Dateien im Speicher erhalten. Account zurücksetzen löscht mit den Datensätzen auch die Dateien des Kontos.
Prüfung	Es gibt keine Virenprüfung und keine allgemeine Sperrliste für Dateitypen; eingeschränkt wird nur über die Vorgaben der Felder und Widgets.

Typische Fehlermeldungen

Meldung	Ursache
„expected a reference object like { referenceId, filename, contentType }, got …“	Ein Service hat statt eines Datei-Objekts etwas anderes bekommen, oft die ganze Nachricht oder ein Textfeld. Den Input-Ausdruck auf das Dateifeld richten.
„reference.referenceId is missing or not a string. Received keys: …“	Das Objekt hat keine referenceId, etwa weil ein Formularfeld leer blieb.
„Es wurde keine Datei unter der Referenz "…" gefunden.“	Die referenceId zeigt auf keine Datei im Konto, zum Beispiel nach einem Zurücksetzen oder bei einer von Hand getippten Kennung.
„pdf with referenceId is required. Expected: { pdf: { referenceId: "..." } }“	PDF analysieren erwartet das Datei-Objekt unter pdf.
„fileReference csv_file missing.“	CSV-Datei strukturiert auslesen erwartet das Datei-Objekt unter csv_file.
„Attachments exceed maximum total size of 5242880 bytes (5MB).“	E-Mail-Anhänge über 5 MB; anderen Versandweg wählen.
„File "…" (… MB) exceeds the upload limit: all files of one request together may be at most 20.0 MB…“	HTTP-Anfrage mit zu großen Dateien.
„Loop activity input must be an array, got …“	Die Schleife hat keine Liste bekommen, etwa uploadedFile statt uploadedFiles.
„Dieses Feld ist erforderlich. Bitte eine Datei hochladen.“	Pflichtfeld im Formular ohne Datei (bei Bild und PDF entsprechend formuliert).
„Fehler beim Datei-Upload. Es wurde ein ungültiges Dateienformat hochgeladen.“	Der Dateityp passt nicht zum Feld.

Beispiel

„Lieferscheine hochladen“ der Musterfirma GmbH beginnt mit einem Benutzer-Start der Kategorie Datei-Upload, Ausführungsmodus „Pro Datei ein Prozess“, Akzeptierte Dateitypen „Nur PDF“. Die Nachricht enthält uploadedFile. „PDF analysieren“ bekommt den Input { "pdf": uploadedFile } und legt das Ergebnis unter analyse ab. „Lieferschein speichern“ (Datenbank-Element) schreibt mit { "lieferschein_nr": analyse.nummer, "lieferant": analyse.lieferant, "dokument": uploadedFile } einen Datensatz; Ergebnispfad lieferschein_db. „Bestätigung senden“ (E-Post Brief versenden) nimmt als Brief dasselbe Objekt unter neuem Namen: { "referenceId": uploadedFile.referenceId, "filename": "Lieferschein " & analyse.nummer & ".pdf", "contentType": "application/pdf" }. Die Datei liegt die ganze Zeit nur einmal im Speicher.

Häufige Fragen

Wie kommt eine Datei aus dem Formular in den Service?

Der Formularwert ist bereits das Datei-Objekt. Im Input-Ausdruck des Services wird es unter dem Feld abgelegt, das der Service erwartet, etwa { "pdf": formular.anlage }. Welches Feld das ist, steht auf der Seite des Services und im Nachrichtenschema.

Kann der Dateiname geändert werden, ohne die Datei neu zu erzeugen?

Ja. Ein neues Objekt mit derselben referenceId und einem anderen filename reicht, siehe Umbenennen.

Warum wird die E-Mail nicht versendet, obwohl die Datei da ist?

Meist ist die Summe der Anhänge größer als 5 MB. Die Meldung nennt die Grenze; für größere Dateien den Versand über Microsoft Graph oder SMTP nutzen.

Werden Dateien gelöscht, wenn der Datensatz gelöscht wird?

Nein, sie bleiben im Speicher des Kontos. Nur Account zurücksetzen entfernt sie zusammen mit den Datensätzen.

Kann der KI-Assistent eine Datei hochladen?

Nein. Der Assistent liefert mit get_file einen Download-Link; Uploads laufen über Formulare, den Datei-Upload-Start oder die externe Aufgabe.

Wie groß darf eine hochgeladene Datei sein?

Formulare begrenzen die Größe nicht. Grenzen gelten erst beim Weiterreichen: 5 MB für E-Mail-Anhänge, 20 MB bei HTTP-Anfragen.

Nächster Schritt

Datum und Zeit: Speicherformate, Zeitzonen, Datumsfunktionen in JSONata, $fn und Handlebars, Timer und Fristen.