Key takeaways
- Restrict uploads to document types the chosen conversion path actually supports.
- Convert the accepted source to PDF before exporting it to a case- or project-specific Box path.
- Keep Box access in Template Credentials and keep folder selection under trusted application control.
Document intake often starts with a mix of DOCX, PPTX, ODT, and other office formats while reviewers expect a stable PDF. Sending the original directly to a collaboration folder leaves conversion rules and naming inconsistent. A saved workflow makes the PDF derivative and its destination predictable without turning Box into the upload-processing service.
What matters most
- Leave create_sharing_link false unless a separate authorization decision permits a share link.
- Use unique destination paths so retries and same-named uploads do not overwrite unrelated records.
- Record both the source identity and exported PDF result in the application’s durable document record.
Choose a narrow document intake contract
A folder full of “documents” is not one technical format. Define the input formats, byte limit, page expectations, and fidelity requirements before accepting uploads. /document/convert can create PDFs from supported office, text, HTML, and presentation formats.
Keep existing PDFs out of this conversion branch because /document/convert is not a generic PDF-to-anything tool. If the product accepts both PDFs and convertible office files, route them deliberately: preserve accepted PDFs and convert only the formats that need normalization.
Build the PDF-to-Box Template
The Template receives one uploaded document as :original, converts it to PDF, and passes only that PDF to /box/store. The destination path includes an application-approved case or project identifier plus unique Assembly values. This prevents two users uploading report.docx from overwriting one another.
Set create_sharing_link to false. A collaboration share link is an authorization and retention decision, not a conversion side effect. If the product later needs one, create it only after the application confirms the Box destination, intended audience, and expiry or revocation policy.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 104857600
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"review_pdf": {
"use": ":original",
"robot": "/document/convert",
"format": "pdf"
},
"box_export": {
"use": "review_pdf",
"robot": "/box/store",
"credentials": "box-documents",
"path": "cases/${fields.case_id}/${unique_prefix}/${file.url_name}",
"create_sharing_link": false,
"result": true
}
}
}Control paths, credentials, and durable identities
Store Box access in Template Credentials and reference the credential name from the saved Template. Do not let an untrusted client choose a credential, arbitrary folder, or replacement path. The server should authorize the user against the case or project record and provide a bounded identifier that the Template can include in its path.
Folder names are presentation, not durable identity. Keep the application document ID, source version, Assembly ID, Box result identity, and workflow version together. Those fields survive a later folder move and let operators distinguish a replay from a new document version.
Application identity
The stable document, case, tenant, and version identifiers.
Processing identity
The workflow version and Assembly ID that produced the PDF.
Storage identity
The Box file identity and path returned by the successful export.
Verify conversion before marking the document ready
A green Assembly is necessary but not sufficient for high-stakes documents. Have the application inspect the exported PDF’s MIME type and page count, then use representative fixtures to inspect fonts, tables, page breaks, headers, footers, links, and non-Latin text. A successful /document/convert job does not by itself establish that the result matches the source application. Decide whether a mismatch blocks the workflow or routes the file to manual review.
Complete the application record only after the Box export exists and corresponds to the expected Assembly. Process webhooks idempotently, and reconcile active records against Assembly Status when a notification is delayed or missed.
Exercise storage and recovery failures
Test revoked or invalid Box Server Authentication app credentials, a missing destination folder, insufficient write permission, same-named uploads, unsupported source formats, conversion failure, and a successful conversion followed by an export failure. The safe retry should reuse the existing source and operation state rather than asking the user to upload again whenever possible.
Define retention for the source upload, PDF derivative, and application record separately. Box may be the durable collaboration copy, but the application still needs enough identity and audit state to explain how it was produced and whether it is current.
Keep the source and PDF roles explicit
A normalized PDF may be the collaboration copy while the editable office file remains the authoritative source. Alternatively, a records process may designate the reviewed PDF as the fixed rendition. Document that choice in the application instead of allowing whichever file appears in Box to become authoritative by accident.
When a source is replaced, create a new application version and destination identity or apply a deliberate overwrite contract. Never assume a same-named upload represents the same business document, and do not delete the prior source until retention and rollback requirements have been satisfied.
Technical details worth knowing
- /document/convert can convert supported office and text formats to PDF. PDF is not a supported input, so route existing PDFs around the conversion Step.
- /box/store accepts a path containing Assembly Variables and defaults to a unique-prefix path when no path is supplied.
- The Box export option create_sharing_link defaults to false. Enabling it replaces the result file’s url property with the sharing URL.
- Box Template Credentials use Server Authentication with JWT. Application administrators must keep that app authorization and its key material valid.
- Template Credentials keep Box access out of the Template JSON and browser bundle, while the application must still authorize the target folder.
- The exported PDF is a new derivative. Retaining or deleting the original upload is a separate product and records-management decision.
A practical approach
- 1
Define supported office formats, maximum size, destination folder policy, and retention.
- 2
Create scoped Box Template Credentials and save the locked three-Step Template.
- 3
Upload representative documents and verify page layout, fonts, filenames, and Box placement.
- 4
Test unsupported PDFs, duplicate names, revoked Box app authorization, and partial export failures.
When Transloadit is useful
Use this workflow for per-user interactive intake into a Box collaboration folder. Use /upload/handle for user intake, /document/convert for supported office-to-PDF conversion, and /box/store for the durable export. Keep Box access in Template Credentials, use an application-approved folder path, and leave sharing-link creation disabled unless the product explicitly needs it.
Architecture boundary
Transloadit converts and exports the uploaded document. The application remains responsible for user permission, case or project identity, retention, legal classification, Box collaboration settings, and whether a resulting document may be shared.
Frequently asked questions
Can this Template accept PDFs as input?
/document/convert does not accept PDF input. Route existing PDFs around conversion or use a separate workflow appropriate to the required PDF operation.
Should /box/store create a sharing link?
Usually not during intake. Keep create_sharing_link false and make sharing a later authorized action with an explicit audience and revocation policy.
Does conversion preserve every office-document feature?
No. Verify representative fonts, layout, formulas, links, and complex application-specific features before relying on the PDF as an authoritative rendition.
Can the browser choose the Box folder?
The browser may submit a bounded application identifier, but a trusted server should authorize it and the locked Template should control the actual destination path.
What should be stored in the application database?
Keep the source document and version identity, workflow version, Assembly ID, Box file identity, destination path, and terminal workflow state.