Key takeaways
- Model the workflow as a graph whose
userelationships make ordering explicit. - Keep stable processing policy in a saved Template and expose only validated fields.
- Run independent derivatives in parallel. Per-file Steps process every file emitted by the upstream Steps they read; only merge or bundling Steps wait for a complete set.
A customizable workflow should expose the few values that legitimately change per job while keeping its processing graph controlled. Transloadit Assembly Instructions express that graph as named Steps, and a saved Template lets an application run it repeatedly without resending storage credentials or transformation policy.
What matters most
- Reference stored Template Credentials instead of putting cloud secrets in Assembly Instructions.
- Record the Template ID, application workflow label, Assembly ID, inputs, and terminal result for every run.
Draw dependencies before writing JSON
Start with files and decisions, not Robot names. Identify the files and derivatives the workflow produces, the validation policies it enforces, the destinations it writes to, and the failure cases the product must handle, such as rejected input or an export failure. Then give each operation a Step name that describes its outcome. In Assembly Instructions, the use value creates the edge between an upstream Step and its consumer; the order of keys in the JSON object does not create an execution sequence.
Independent Steps can read the same upstream file and run concurrently. Two resize Steps that both draw from one shared filter Step do not wait for each other; each begins when the filter emits a file. The concrete JSON for this shape appears in the next section. Each derivative is exported to its own prefix, so the parallel renditions never share a key. A merge Robot is different: it may need a bundled set of named inputs before it can produce anything. Model that dependency explicitly instead of relying on apparent JSON order.
Nodes are Steps
Each named Step invokes one Robot with a bounded set of parameters.
Edges come from use
The declared upstream input determines readiness and data flow.
Branches can overlap
Derivatives that share an input can run independently instead of becoming a serial chain.
Separate fixed policy from runtime fields
Keep validation, allowed Robots, output roles, and destinations in a saved Template. Values that truly vary per request can arrive as fields and be referenced through ${fields.*} variables. A tenant ID, requested rendition profile, or stable asset ID may be reasonable; an arbitrary Robot name, destination credential, or unrestricted output dimension usually is not.
Set allow_steps_override to false in the Template when an untrusted caller must not merge new Steps into the saved graph. That setting protects the graph, not the meaning of every field. Validate fields in the application before creating the Assembly: authorize the tenant, accept only known profiles, clamp numeric ranges, and reject unknown keys. The Template should also use safe defaults or filters where a bad value could create excessive work. The complete Template below includes input validation, export, and notification parameters that the following sections explain.
{
"allow_steps_override": false,
"max_number_of_files": 1,
"max_size": 52428800,
"notify_url": "https://app.example.com/webhooks/transloadit",
"steps": {
":original": {
"robot": "/upload/handle"
},
"accepted_images": {
"use": ":original",
"robot": "/file/filter",
"accepts": [
["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp|image/avif)$"]
],
"error_on_decline": true,
"error_msg": "Upload a JPEG, PNG, WebP, or AVIF image."
},
"web_image": {
"use": "accepted_images",
"robot": "/image/resize",
"width": 1600,
"height": 1200,
"resize_strategy": "fit",
"format": "webp"
},
"thumbnail": {
"use": "accepted_images",
"robot": "/image/resize",
"width": 320,
"height": 320,
"resize_strategy": "fillcrop",
"format": "webp"
},
"export_web": {
"use": "web_image",
"robot": "/s3/store",
"acl": "private",
"credentials": "media-output",
"path": "${fields.tenant_id}/${assembly.id}/web/${unique_prefix}/${file.url_name}"
},
"export_thumb": {
"use": "thumbnail",
"robot": "/s3/store",
"acl": "private",
"credentials": "media-output",
"path": "${fields.tenant_id}/${assembly.id}/thumb/${unique_prefix}/${file.url_name}"
}
}
}// Illustrative fragment: these objects come from your application, not the SDK.
const assembly = await transloadit.createAssembly({
files: { image: inputPath },
params: {
template_id: process.env.TRANSLOADIT_TEMPLATE_ID,
fields: {
tenant_id: tenant.id,
},
},
})
await jobs.attachAssembly({
jobId: job.id,
assemblyId: assembly.assembly_id,
})Stable policy
Robot choices, validation, export destinations, and result roles belong in controlled configuration.
Bounded variation
Fields expose a small contract rather than making the entire graph caller-controlled.
Two validation layers
Application authorization and Template safeguards address different failure and abuse paths.
Validate inputs before expensive processing
Put cheap, deterministic checks before derivative generation. Assembly- and Template-level max_size caps the combined size of the whole upload—the entire upload is canceled if the total exceeds it, even when every individual file is under it—and max_number_of_files caps how many files the request may contain. For a per-file size limit, use /file/filter on ${file.size}, which evaluates each file individually and can also inspect server-detected MIME type and extracted metadata. When unsupported input should fail the whole job, set error_on_decline and provide a message that tells the user what to change.
The sample deliberately caps the walkthrough at one uploaded file. Raising max_number_of_files makes multi-file decline behavior relevant. Prefer an explicit allowlist such as JPEG, PNG, WebP, and AVIF when the downstream operation only supports browser images. A broad image/* rule accepts formats the destination may not render, while a filename extension and browser-reported MIME value are only client claims. Decide separately whether a rejected file should fail an entire multi-file Assembly, disappear from one branch, or enter another branch; those are product behaviors, not incidental filter settings.
Cheap checks first
Reject unsuitable inputs before paid or slow transformations begin.
Server-detected properties
Use extracted MIME and metadata rather than trusting extensions alone.
Explicit rejection behavior
Choose whether one declined file ends the job or simply stops flowing through a branch.
Export with credentials and paths you can rotate
Create Template Credentials for the storage destination and reference their name from the export Robot. The Assembly Instructions then contain a stable credential label rather than an access key and secret. Rotating the stored credential updates future runs without copying a new secret into source code, browser parameters, or every Template that uses it. /s3/store defaults acl to public-read, so set it to private unless the exported files are meant to be publicly readable.
Build destination paths from validated tenant or asset identifiers, the Assembly ID, the rendition role, and Transloadit’s platform-generated ${unique_prefix}. This unique 33-character per-file prefix contains a forward slash, so it expands to a two-level subdirectory in the storage key and prevents same-named inputs within one Assembly from colliding. Give every parallel derivative a distinct rendition-role path segment, such as web/ or thumb/, so their exports never collide on the same key. Do not use an unsanitized upload filename as the only key, and decide what a retry should do if the object already exists. An idempotent export either writes the same intended object or checks and reconciles the destination before creating another. Record the final storage key for every result so deletion and replacement can find all copies later.
Credential label
Separates secret rotation from the workflow JSON that refers to it.
Stable path inputs
Tenant, asset, Assembly, and rendition identifiers make outputs traceable.
Overwrite contract
Define whether an existing destination key is replaced, rejected, versioned, or reconciled.
Operate every run as an asynchronous state machine
Store an application job record before starting the Assembly. Include the actor, tenant, input file identifier, Template ID, validated fields, application workflow label, and a stable operation key. The application workflow label and operation key are local-only identifiers stored in your own database; they are never sent to Transloadit. Add the Assembly ID as soon as it is returned. This record lets retries ask whether equivalent work is already active or complete instead of creating a second export after a timeout.
Configure notify_url when the job should finish in the background; as shown in the Template above, set it in the stored Template so each run inherits it. Verify the notification signature with the Auth Secret belonging to the Auth Key used for that Assembly, return HTTP 200 promptly for a valid delivery, and process duplicates idempotently. A periodic reconciliation job should compare locally active work with Assembly Status so a lost callback cannot strand a record. Monitor latency, failure class, bytes processed, outputs, and webhook retries by the application workflow label.
Operation key
Prevents a caller retry from silently creating duplicate processing and exports.
Verified webhook
Authenticates completion data while allowing the original request to end quickly.
Reconciliation
Repairs local state when notifications are delayed, duplicated, or missed.
Test changes with representative fixtures
A workflow is only as stable as the inputs used to test it. Keep small fixtures for every accepted format, boundary dimensions, transparency, orientation, animation, oversized input, and an explicitly rejected type. Assert the output role, format, dimensions, storage path, and terminal state rather than only checking that the Assembly completed. Include a destination failure and a duplicate notification so the recovery path is exercised before an incident.
Record the intended behavior in application configuration or source control and associate that label with each run. When the saved Template changes, test it in a non-production Workspace or with isolated destinations, inspect cost and metadata, and move a bounded share of traffic first. If results regress, route new work back to the previous controlled behavior and reconcile any Assemblies already in flight instead of assuming they stopped.
Format matrix
Covers the inputs and metadata variations the product promises to accept.
Failure fixtures
Prove rejection, export failure, duplicate delivery, and replay behavior as well as success.
Bounded rollout
Limits cost and customer impact while a changed workflow is measured under real traffic.
Technical details worth knowing
- A per-file Step begins as soon as an upstream Step named in its
usevalue emits a file; only merge or bundling Robots wait for a complete set of named inputs. A Step’s position in the JSON object does not determine execution order. - Assembly Variables such as
${fields.tenant_id},${assembly.id}, and${file.url_name}—a URL-safe (slugged) version of the current Step file’s name, including its extension—are resolved at execution time and can parameterize dimensions, paths, and other Robot values. In the sample export paths,${assembly.id}provides per-run uniqueness and the slash-containing${unique_prefix}keeps files within a run distinct. - Setting
allow_steps_overrideto false in a saved Template prevents callers from merging replacement Steps into that Template. Runtime fields still need application-side validation and authorization. - /file/filter can compare server-detected file properties with array conditions. A specific MIME allowlist is safer than trusting a filename extension or client-reported type.
- Template Credentials keep destination secrets separate from the Template JSON and can be updated without copying keys through every integration.
- Assembly Notifications are retried when the receiver does not return HTTP 200. Consumers must verify the signature and tolerate duplicate, delayed, or out-of-order delivery.
A practical approach
- 1
Draw the required inputs, derivatives, Steps that read from multiple derivatives, exports, and failure boundaries.
- 2
Save and lock a Template whose variable inputs are deliberately limited.
- 3
Submit one representative file and inspect every Step in Assembly Status.
- 4
Add verified webhook handling, idempotent persistence, fixtures, and a controlled rollout.
When Transloadit is useful
Use a saved Template to connect /upload/handle, /file/filter, parallel /image/resize Steps, and /s3/store. Lock the processing graph by setting allow_steps_override to false, pass bounded fields at runtime, and reconcile completion through Assembly Status and verified webhooks.
Architecture boundary
Assembly Templates describe file processing and movement. They do not own product approvals, tenant authorization, business state, or an application’s configuration history; keep those decisions in the system that starts and records each job.
Frequently asked questions
Does the order of Steps in the JSON control execution?
No. The use dependencies control when a Step can run. Independent Steps can run in parallel even when one appears later in the object.
Can a locked Template still accept custom values?
Yes. allow_steps_override: false prevents callers from replacing the processing Steps. The application can still send fields used by ${fields.*} variables, and it must validate and authorize those values.
Should cloud storage keys appear in Assembly Instructions?
No. Store them as Template Credentials and reference the credential name from the storage Robot. This keeps secrets out of the workflow JSON and makes rotation independent.
How should a workflow change safely?
Keep the application workflow label and configuration history in your own system, test changes with representative fixtures, and shift traffic deliberately. Preserve enough information on every job to explain which behavior produced its outputs.
What happens when a webhook is delivered twice?
Treat duplicate delivery as normal. Verify the signature, look up the Assembly or operation key, and make the same terminal update safe to apply again without duplicating assets or user-visible events.