Key takeaways
- Limit the import prefix to supported office formats; a mixed bucket is not a conversion contract.
- Paginate recursive imports and checkpoint each completed page instead of assuming one Assembly covers the library.
- Write PDFs to a separate prefix so subsequent import runs do not consume their own results.
Supabase Storage can hold product documents without being the system that converts them. A batch workflow is useful when an application has accumulated office files that need a consistent PDF representation for review, download, or downstream indexing. The safe design treats conversion as a versioned derivative job rather than rewriting the original object.
What matters most
- Use separate read and write Template Credentials or narrowly scoped S3 access keys where practical.
- Record source path, source version, Assembly ID, output path, and workflow version in the application database.
- Treat the stored object’s bucket permissions as the access control, and record the destination path rather than a result URL as the document’s identity.
Create a convertible document inbox
Do not point recursive import at a mixed production bucket. Create an inbox prefix whose contract is limited to the office and text formats selected for PDF conversion. Images, archives, and unrelated application objects are outside this workflow’s scope, so route or exclude them explicitly. PDF is not a supported input for /document/convert, so route existing PDFs around this Step.
Write the contract into the upload or application path that populates the inbox. Validate filename, detected type, size, tenant ownership, and document state before scheduling processing. A storage object’s extension is useful routing data but not authoritative content validation.
Paginate and checkpoint recursive imports
/supabase/import can recurse through a directory and paginate with page_number and files_per_page. Treat each page as a bounded execution. Store the page request and the source objects observed in the application so a crash or retry can resume without assuming the bucket stayed unchanged.
Keep the normalized output prefix outside the imported inbox. Otherwise a later recursive run can encounter its own PDFs, which this conversion branch is not designed to accept. A separate bucket is even clearer when retention or permissions differ.
Inbox
Contains only source formats eligible for the current conversion policy.
Normalized output
Contains versioned PDFs and is excluded from every inbox traversal.
Database record
Maps each source version to its Assembly, output object, and workflow state.
Build the Supabase PDF Template
The Template imports the bounded inbox prefix, converts each emitted office document to PDF, and stores each result beneath a normalized path containing Assembly uniqueness. /supabase/store requires a file path rather than a directory, so the path must end in a concrete filename expression.
The sample references separate read and write credential names. Supabase exposes an S3-compatible Storage connection; keep its endpoint and access keys in Template Credentials. Store the output bucket and path as the durable identity. Set sign_urls_for only when the application needs an expiring signed_ssl_url; when it is omitted, no URL signing is done.
{
"allow_steps_override": false,
"steps": {
"office_inbox": {
"robot": "/supabase/import",
"credentials": "supabase-document-read",
"path": "documents/office-inbox/",
"recursive": true,
"page_number": 1,
"files_per_page": 100
},
"normalized_pdf": {
"use": "office_inbox",
"robot": "/document/convert",
"format": "pdf"
},
"supabase_output": {
"use": "normalized_pdf",
"robot": "/supabase/store",
"credentials": "supabase-document-write",
"path": "documents/normalized-pdf-v1/${assembly.id}/${unique_prefix}/${file.url_name}",
"result": true
}
}
}Verify the PDF and application record
Test DOCX, ODT, PPTX, XLSX, HTML, and Markdown fixtures only if the product promises those inputs. Review page count, fonts, tables, formulas, links, headers, and non-Latin text. Unsupported or fidelity-sensitive files should enter a visible review state rather than being silently marked normalized.
After export, update the application database idempotently with the source path and version, workflow version, Assembly ID, output bucket and path, and terminal state. Supabase Storage does not update the database row that represents the document; the application must reconcile that relationship.
Design retries and retention per object
One bad document should not require replaying a complete directory page. Track success and failure per source identity, then retry only the source objects the application has not recorded as complete. The sample path is unique per run, so processing the same source again writes a new object; de-duplication comes from the application’s source-to-result record, checked before another Assembly is created.
Keep originals until the application’s retention policy permits deletion and the normalized PDFs have passed review. Record separately whether the PDF is a viewing rendition or the reviewed record copy, instead of allowing the output prefix to decide that business role.
Observe the batch independently of user traffic
Run large normalization batches through a queue or scheduled worker rather than an interactive request. Monitor page checkpoints, object-level failures, Assembly duration, output bytes, and Supabase export errors. Surface an operator-visible list of unresolved source objects instead of burying provider responses in logs.
Throttle work so recursive imports, document conversion, and writes do not overwhelm application databases or storage access. Use a small representative rollout first, then increase concurrency only after completion, retry, and webhook behavior are measured under realistic files.
Technical details worth knowing
- /supabase/import accepts one path, an array of paths, or a directory path. Recursive imports use page_number and files_per_page.
- /document/convert supports office and text formats including DOCX, ODT, PPTX, XLSX, HTML, and Markdown, with PDF available as an output.
- PDF is not a supported input for /document/convert. Route existing PDFs around conversion and convert only supported source formats.
- /supabase/store requires a file path rather than a directory path and can include Assembly Variables in that path.
- /supabase/store defaults the Content-Type header to the processed file’s detected MIME type. Set sign_urls_for to return an expiring signed_ssl_url; when it is omitted, no URL signing is done.
- Supabase import and store use its S3-compatible Storage connection. Template Credentials keep the endpoint and access keys out of the saved Instructions.
A practical approach
- 1
Define the convertible inbox, output prefix, pagination size, and application record transition.
- 2
Create scoped Supabase credentials and save the import–convert–store Template.
- 3
Convert representative DOCX, PPTX, and ODT files and review layout and metadata.
- 4
Run bounded pages with checkpoints, idempotent records, and a retry path for failed objects.
When Transloadit is useful
Use this workflow for batch normalization of a document library already held in Supabase Storage. Use /supabase/import for a bounded file or paginated prefix, /document/convert for supported office-to-PDF conversion, and /supabase/store for the resulting object. Keep the inbox limited to convertible formats, separate input and output prefixes, and reconcile each exported path with its Supabase database record.
Architecture boundary
Supabase Storage owns the source and output objects, while the application owns tenant access, database records, document status, retention, and publication. Transloadit processes only the objects selected by the saved workflow and does not update application rows automatically.
Frequently asked questions
Can the inbox contain existing PDFs?
No. PDF is not a supported input for /document/convert. Keep PDFs outside this office-file inbox or route them around the conversion Step.
Can one Assembly convert an entire bucket?
Recursive imports can cover directories, but bounded pages with durable checkpoints are safer for large or changing libraries.
Why use a separate output prefix?
It prevents recursive imports from reading generated PDFs as new source documents and makes retention, rollback, and permissions easier to reason about.
Which result URL should the application store?
Store the destination bucket and path as the durable identity, not a result URL. Set sign_urls_for when the application needs an expiring signed_ssl_url; when it is omitted, /supabase/store does not sign a URL.
Does Transloadit update our Supabase database row?
No. The application must reconcile the Assembly result with its own tenant, document, and version records.