Files in Pantarey

In Pantarey a file never sits inside a record or a process message; it lives in the file storage of the account. Records, messages, tasks and e-mails only carry a reference to it: a small JSON object with an id, a file name and a type. This one format applies everywhere, from the form field through every service to the AI assistant. Whoever knows it can pass files into any step, rename, collect and store them without dealing with the storage itself. This page describes the file object, the places where files are created, the hand-over within a process, the limits and the typical error messages.

The file object

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

Field	Meaning
`referenceId`	unique id of the file in the account's storage; assigned on upload or by the creating service. Intermediate results occasionally carry a prefix such as `temp_`.
`filename`	display name, for example for attachments, ZIP contents and downloads
`contentType`	MIME type such as `application/pdf`, `image/png`, `text/csv`
`thumbnail`	images only: small preview as Base64 text (without `data:` prefix); missing for unsupported image formats, without an error

When processing, Pantarey reads the file by its referenceId. filename and contentType are taken from the object and not checked against the storage; if they are missing, the services use fallbacks (for e-mail attachments the referenceId as name and application/octet-stream as type). That is why a file can be renamed simply by building a new object, see Renaming.

In the data schema a file field is an object with the sub-fields filename (required), contentType, referenceId and thumbnail (for images). The files of each account are kept separate from all other accounts; the storage is versioned.

Where files are created

Form fields

In the Data Designer the group Files offers four types; Multiple ("Multiple values (list)") turns each of them into a list of files.

Type	Description in the designer	Allowed	In the form
Image	JPG, PNG, WebP	`image/*`	upload with preview image (up to 200 × 200 px); a click opens the original
PDF	PDF document	`application/pdf`	upload with embedded preview and View & download PDF
CSV file	tabular file	`text/csv`	file picker
File	any file	everything	file picker

Custom forms (Formly JSON) offer the same field types image, pdf and file, plus dropzone: a drop area "Drag files here" / "or click to select" for several files with the preset acceptPreset all, pdf or images. The dropzone silently discards unsuitable files; a message appears only if no file is left. For the type file, mimeType sets the allowed type exactly; empty or application/octet-stream allows everything. Details of the fields under Forms.

The upload goes directly from the browser into the account's storage; the result is the file object in the form value and thus in the record or in the process message.

User start with file upload

A user start with the Category File upload shows a dropzone instead of a form. Two settings decide how it continues:

Setting	Values	Message
Execution mode	One process per file (default)	one instance per file with `{ "uploadedFile": { … }, "$$context": { … } }`
	One process for all files	one instance with `{ "uploadedFiles": [ … ], "$$context": { … } }`
Accepted file types	All files, PDF only, Images only	preset of the dropzone

For a file upload, $$context additionally contains fileUpload: true.

User task and external task

A user task uses the same form fields as the start. Enable PDF preview shows the person a PDF next to the form, for example the invoice to be checked.

An external task accepts files from people without Pantarey access via <upload-widget name="receipts" multiple accept="pdf">; accept is all, pdf or images. The server checks the file type and the number of uploaded files. The other way round, %%FILE:path%% shows a file from the task's input, for example <iframe src="%%FILE:invoicePdf%%"> on the PDF approval page; the link is valid for one hour and only works for files that are part of the task's input.

Services that create files

Service	Result	File name
Create PDF from template	file object	setting PDF file name with `$(…)`, default `document.pdf`
Generate invoice PDF (with calculation)	`{ "invoice": { … }, "pdf": { … } }`; `targetInvoicePath` also writes the reference into the invoice	required
Complete e-invoice	`{ "invoice": { … }, "pdf": { … } }`	configurable
Create e-invoice (ZUGFeRD)	file object with embedded `factur-x.xml`	name of the input PDF
Create SEPA direct debit file	`{ "file": { …, "contentType": "application/xml" } }`	optional, default `SEPA-Lastschrift_<CORE/B2B>_<messageId>.xml`
Generate QR code	file object `image/png` with `thumbnail`	optional, default `qrcode_<timestamp>.png`
Bundle files into ZIP	file object `application/zip`	`output_filename`, default `archive.zip`
Unzip ZIP file	`{ "files": [ … ], "groups": { "folder": [ … ] }, "count": n }`	from the archive, duplicates with `_2`, `_3`
Merge PDF files	file object	`filename_output`, no default
Fill PDF form	file object	name of the input PDF
Split PDF	`{ "files": [ … ], "count": n }`	per part or pattern, default `{name}_part-{n}.pdf`
Remove pages from PDF	file object with `removedCount`, `remainingCount`	name of the input PDF
Convert PDF to grayscale	`{ "document": { … }, "metadata": { … } }`	`<name>_bw.pdf`
Send E-Post letter	`letter_pdf`	name of the letter, required
HTTP Request (REST)	response as file under `file`	`filename`, otherwise from the response or `download-<timestamp>.<ext>`

There is no service that creates Excel files.

Services that read files

Service	Input field
Read CSV file into structured data	`csv_file`
Read Excel file	`document`
Read document (OCR)	`document`
Analyze PDF	`pdf`
Extract PDF text (Invoice)	file object at top level
Read PDF metadata	`pdf`
Convert XML file to JSON	`xml` (file object or XML text)
Extract PDF attachments	`pdf`; returns name and content of the attachments, no new file objects
Send fax	`document` (PDF, TIFF, GIF, PNG, HTML or text, at most 10 pages)
Upload file to FTP server	`fileReference`, optional `filenameOverwrite`
Upload file to SharePoint	`file_reference`, optional `overwrite_filename`
TeamBeam: Send documents	`fileReferences`
E-mail services (own domain, Microsoft Graph, SMTP, internal)	attachments as a list of file objects
HTTP Request (REST)	every file object in the body is transferred as content (JSON as Base64, `multipart` or `file`)

A webhook accepts JSON only; files enter the account through form upload, the external task or the response of an HTTP request.

Database, data export and AI assistant

Database: The record view shows images as a preview (a click opens the original), PDFs and files as a list; a click opens the file in a new tab. Uploads happen through the file fields in Edit or when creating a record. Share in the ⋮ menu copies a link to the JSON of the record, not to a file, see Database.
Data export: The switch Include file attachments in the data export puts the files into the ZIP under references/<referenceId>; file name and type are part of the JSON of the related record. The export of a single data structure contains no files.
AI assistant: The tool get_file returns a download link, valid for 15 minutes, to a file of a record; files are never transferred inside the conversation, and an upload via chat is not possible. Overview under Tools of the assistant.

How files are handed over

The file object is an ordinary value: it is copied when it gets into a record, a message, a task or an e-mail. All copies point to the same file in the storage.

In the message and in the record

A service that creates a file puts its result under the result path, for example invoice_pdf; the next step accesses it with invoice_pdf, see Data in the process. A database element writes the file into a file field of the record by placing the object at the right position in the input expression:

{
  "delivery_note_no": analysis.number,
  "document": uploadedFile
}

Renaming

Because services take the name from the object, a new object in the input expression of the following step is enough:

{
  "referenceId": invoice_pdf.referenceId,
  "filename": "Invoice " & invoice.number & ".pdf",
  "contentType": invoice_pdf.contentType
}

The new name applies to e-mail attachments, HTTP uploads, ZIP contents and the record. The file in the storage remains unchanged; for HTTP requests and ZIP archives filename is required, without a name the file is skipped there.

Several files

Several files are a list of file objects, for example a Multiple field, uploadedFiles of a batch start or files after unzipping. To process each file separately, the activity gets an input in the Loop section that returns the list; each iteration receives one element as its message, the result is the list of the individual results under the result path. Defaults are at most 1000 elements and 40 parallel runs, see Loops. A recipe is in the Cookbook.

E-mail attachments

Attachments are a list of file objects; only entries with a referenceId are attached. When sending via the own domain and via the internal Pantarey mail service, all attachments of one e-mail together may be at most 5 MB ("Total size max. 5 MB"); larger attachments go via Microsoft Graph or SMTP, which have no limit of their own in Pantarey.

Limits and behaviour

Topic	Behaviour
Upload	Forms and dropzone do not limit the file size. Attachments are limited: 5 MB for e-mail (own domain, internal), 20 MB for all files of one HTTP request together and for a file in the HTTP response.
ZIP	Bundling up to 5000 files and 2 GB; unzipping up to 500 MB unpacked and 1000 entries.
Message	Large messages are no problem; from 3000 characters Pantarey offloads them automatically.
Links	Download and upload links of the app and `%%FILE%%` links are valid for one hour, `get_file` for 15 minutes, the download of a data export for 5 minutes.
Deleting	When a record or a data structure is deleted, the files remain in the storage. Reset account deletes the files of the account together with the records.
Checks	There is no virus scan and no general block list for file types; restrictions only come from the presets of fields and widgets.

Typical error messages

Message	Cause
"expected a reference object like { referenceId, filename, contentType }, got …"	A service received something other than a file object, often the whole message or a text field. Point the input expression at the file field.
"reference.referenceId is missing or not a string. Received keys: …"	The object has no `referenceId`, for example because a form field stayed empty.
"Es wurde keine Datei unter der Referenz "…" gefunden."	The `referenceId` points to no file in the account, for example after a reset or with a hand-typed id.
"pdf with referenceId is required. Expected: { pdf: { referenceId: "..." } }"	Analyze PDF expects the file object under `pdf`.
"fileReference csv_file missing."	Read CSV file into structured data expects the file object under `csv_file`.
"Attachments exceed maximum total size of 5242880 bytes (5MB)."	E-mail attachments over 5 MB; choose another sending route.
"File "…" (… MB) exceeds the upload limit: all files of one request together may be at most 20.0 MB…"	HTTP request with files that are too large.
"Loop activity input must be an array, got …"	The loop did not receive a list, for example `uploadedFile` instead of `uploadedFiles`.
"This field is required. Please upload a file."	Required form field without a file (worded accordingly for image and PDF).
"Error during file upload. An invalid file format was uploaded."	The file type does not match the field.

Example

"Upload delivery notes" at Musterfirma GmbH begins with a user start of the category File upload, Execution mode "One process per file", Accepted file types "PDF only". The message contains uploadedFile. "Analyze PDF" receives the input { "pdf": uploadedFile } and stores the result under analysis. "Save delivery note" (database element) writes a record with { "delivery_note_no": analysis.number, "supplier": analysis.supplier, "document": uploadedFile }; result path delivery_note_db. "Send confirmation" (Send E-Post letter) takes the same object as the letter under a new name: { "referenceId": uploadedFile.referenceId, "filename": "Delivery note " & analysis.number & ".pdf", "contentType": "application/pdf" }. The file exists only once in the storage the whole time.

Frequently asked questions

How does a file get from the form into the service?

The form value already is the file object. In the service's input expression it is placed under the field the service expects, for example { "pdf": form.attachment }. Which field that is can be found on the service's page and in the Message schema.

Can the file name be changed without creating the file again?

Yes. A new object with the same referenceId and a different filename is enough, see Renaming.

Why is the e-mail not sent although the file is there?

Usually the sum of the attachments exceeds 5 MB. The message names the limit; for larger files use sending via Microsoft Graph or SMTP.

Are files deleted when the record is deleted?

No, they remain in the account's storage. Only Reset account removes them together with the records.

Can the AI assistant upload a file?

No. The assistant returns a download link with get_file; uploads go through forms, the file upload start or the external task.

How large may an uploaded file be?

Forms do not limit the size. Limits apply when files are handed over: 5 MB for e-mail attachments, 20 MB for HTTP requests.

Next step

Date and time: storage formats, time zones, date functions in JSONata, $fn and Handlebars, timers and deadlines.