Skip to main content
A workflow runs several steps as one job. When a step fails, the retry skips the steps that already succeeded and picks up at the failed one. Use a task for one operation. Use a workflow when steps depend on each other and one of them can fail on its own, such as signing a user up: create the profile, send the welcome email, add them to a mailing list. If the email service is down, the retry sends the email without creating a second profile.

Define a workflow

Add the workflow to jobs.workflows. Its handler calls registered tasks through tasks:
Queue it like a task, with 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.
The 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 on job.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

Use foreach 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 name is a nonempty string without :, used once per run across foreach and parallel. Restore is by key, not position, so a reordered or shorter list restores the right outputs and runs only new keys. Branch names are parallel’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. foreach runs one item at a time unless you raise concurrency; parallel starts every branch at once. The limit is per call and in-process: it doesn’t count against jobs.run({ limit }) or workflow concurrency keys, so 10 jobs running concurrency: 10 can 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 task and return an error in output.
  • No waits inside items. waitFor inside an item or branch throws FrogBot waitFor can't run inside foreach '<name>' item '<key>'.; wait before, between or after helper calls instead, or use a plain loop of waitFor calls.
  • 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. A concurrency 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 concurrency run 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: