Define a workflow
Add the workflow tojobs.workflows. Its handler calls registered tasks through tasks:
workflow instead of task:
tasks[slug](stepID, { input, retries? }) runs the task and resolves with its output. The step ID names this call within the job. Keep each ID unique and the same on every run, because FrogBot matches saved results by it. Descriptive IDs, such as send-email, also make the job log easier to read.
Inline steps
inlineTask runs a function that isn’t registered as a task. Its output is saved like any other step, but it isn’t typed or reusable.
task function receives input, job, req, tasks, and inlineTask, like a task handler.
Read step outputs
Use the value a step resolves with. Every step’s result is also onjob.taskStatus, keyed by task slug and step ID. Inline steps use the slug inline.
Failure and recovery
When a step throws, the job fails that attempt. If retries remain, the next attempt runs the handler again from the top:
Only the steps restore their saved results; any other code in the handler runs again on every attempt. Put database writes and external calls inside steps, and base decisions on
job.input and step outputs rather than the current time or random values.
Retries in workflows
Loops and parallel steps
Useforeach to run a step per item and parallel to run a few named steps at once. Both are workflow-handler arguments beside tasks and inlineTask. Each item or branch runs as an inlineTask with the ID `${name}:${key}`, so a retry or a resumed run returns its saved output without running it again.
- Names and keys. A
nameis a nonempty string without:, used once per run acrossforeachandparallel. Restore is by key, not position, so a reordered or shorter list restores the right outputs and runs only new keys. Branch names areparallel’s keys. A helper called inside an item or branch nests under it, with the ID`${itemID}:${name}:${key}`, so its name only has to be unique within that item. - Concurrency.
foreachruns one item at a time unless you raiseconcurrency;parallelstarts every branch at once. The limit is per call and in-process: it doesn’t count againstjobs.run({ limit })or workflowconcurrencykeys, so 10 jobs runningconcurrency: 10can mean 100 calls in flight. - Failure. When an item or branch throws, no new items start, the running ones finish and save, and the first error fails the run. Its retry skips the saved items. To carry on past a bad item, catch inside
taskand return an error inoutput. - No waits inside items.
waitForinside an item or branch throwsFrogBot waitFor can't run inside foreach '<name>' item '<key>'.; wait before, between or after helper calls instead, or use a plain loop ofwaitForcalls. - Storage. Every output is saved on the job row’s
log, so a long list makes the job record large. Keep outputs small, such as IDs.
Wait for approvals and dates
A workflow can pause for hours or days, without holding a worker, until someone responds to a link or a date passes. See Durable waits.Concurrency
Two jobs for the same record can race: a quick edit after a create queues a second sync while the first is still running. Aconcurrency key makes jobs with the same key run one at a time.
concurrency works the same on tasks and workflows. It takes a key function, or an object:
- Scope. A key is global across queues, runners, and processes. Include the queue in the key, as in
({ input, queue }) => `${queue}:sync:${input.documentId}`, to allow one job per queue. - Waiting. A blocked job stays pending and holds no lease. It runs after the job holding the key completes, fails, or pauses at
waitFor. - Superseding. Only pending jobs are deleted, including paused workflows, which frees their
jobIds and closes their waits. A job that is already running finishes, and the new job waits for it. - No key. Jobs without
concurrencyrun in parallel.
JSON workflows
Instead of a function,handler can be an array of steps. A JSON workflow has no waitFor, foreach, or parallel.
Steps don’t run in array order. Each pass runs, at the same time, every unfinished step whose condition passes, and passes repeat until a step marked completesJob has finished. Use condition to order steps, and mark the last one completesJob: true, or the job never completes.
Workflow options
Concurrency options
concurrency takes a key function or an object: