Skip to main content
A task is one function with typed input and output. Queue it as a job on its own, or call it from a workflow as one step.

Define a task

Add the task to jobs.tasks:
Then queue it:
The job waits in the database until a runner claims it. See Queue and run jobs.

Handler arguments

The handler returns { output }, where output matches outputSchema. Throw to fail the attempt.

Generated types

inputSchema and outputSchema take the same fields as a collection. FrogBot generates an interface for each task, named Task plus the capitalized slug unless you set interfaceName. jobs.queue then checks input against it, and handler gets a typed input. Pass IDs, not whole records. The task reads what it needs when it runs, so it always sees current data, and the job record stays small.

Failures and retries

A task fails when its handler throws. Throw an Error with a message that says what went wrong; FrogBot saves it on the job.
Tasks don’t retry by default. Set retries to retry a failed attempt: A retry is a new run of the job: it waits in the queue until the backoff passes and a runner claims it again. After the last attempt fails, the job is failed for good: hasError is true and error holds the last error. See Check a job’s status. Each retry runs the handler again from the start, so write tasks that are safe to repeat. Use the destination service’s idempotency key for charges, emails, and other external effects. A crashed worker doesn’t use up a retry; see Leases and crash recovery.

Callbacks

Both receive { input, job, req, taskStatus } and are awaited.

Restore a task that already succeeded

When a workflow retries, a task that already succeeded returns its saved output instead of running again. Set retries.shouldRestore to change that:

Nested tasks

A task handler can run steps of its own with tasks and inlineTask. Each step saves its output on the job, so a retry of the outer task restores finished steps:
The first argument is a step ID, unique within the job. Keep it the same across retries. For many steps or longer flows, use a workflow.

Load a handler from a file

handler can be a module path instead of a function: '/abs/path/to/file.ts' for the default export, or '/abs/path/to/file.ts#exportName' for a named export. FrogBot imports the file when the task runs, which keeps heavy dependencies out of your web bundle.
The file must exist at that path, in a form your runtime can import, wherever jobs run. That suits a worker process better than a bundled web server. Task handlers loaded from a file get the request without req.frogbot.

Task options

Retry options

retries takes a number of retries or an object: