io.runTask()

Creates and runs a Task inside a Run.

A Task is a cached unit of work in a Job Run that are logged to the Trigger.dev UI. You can use io.runTask() to create and run a Task inside a Run.

Any interaction with an external service (database or API) should be wrapped in a Task. Failing to do so could result in repeated work when runs are resumed.

Parameters

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

callback · function · required

The callback that will be called when the Task is run, this is where your logic should go. The callback receives the Task and the IO as parameters.

Show arguments

task · Task

The Task that is running. It has some useful properties like idempotencyKey and attempts.

io · IO

IO holds Integrations and useful actions you can perform.

options · object

The options of how you’d like to run and log the Task.

Show options

name · string

This is displayed on the Task in the logs.

delayUntil · date

The Task will wait and only start at the specified Date.

retry · object

Retry options.

Show options

limit · number

The maximum number of times to retry the request.

minTimeoutInMs · number

The minimum amount of time to wait before retrying the request.

maxTimeoutInMs · number

The maximum amount of time to wait before retrying the request.

factor · number

The exponential factor to use when calculating the next retry time.

randomize · boolean

Whether to randomize the retry time.

icon · string

The icon for the Task, it will appear in the logs. You can use the name of a company in lowercase, e.g. “github”. Or any icon name that Tabler Icons supports.

description · string

A description of the Task.

properties · array

Properties that are displayed in the logs.

Each property has the following fields:

Show property fields

label · string · required

The label for the property.

text · string · required

The value of the property.

url · string

The URL to link to when the property is clicked.

params · any

The input params to the Task, will be displayed in the logs.

style · object

The style of the log entry.

Show style

style · string

The style: normal or minimal.

variant · string

A variant of the style.

redact · RedactOptions

An optional object that specifies which fields to redact from the logs. This is useful for sensitive data like API keys.

Hide redact

paths · string[]

An array of paths to redact. A path is a dot separated string, e.g. user.email. Currently does not support wildcards.

callback · object

An optional object that exposes settings for the remote callback feature.

Enabling this feature will expose a callbackUrl property on the callback’s Task parameter. Additionally, io.runTask() will now return a Promise that resolves with the body of the first request sent to that URL.

Show property fields

enabled · boolean · required

Whether to enable the remote callback feature.

timeoutInSeconds · number · required

The value of the property.

onError · function

An optional callback that will be called when the Task fails. You can perform logic in here and optionally return a custom error object. Returning an object with { retryAt: Date, error?: Error } will retry the Task at the specified Date. You can also just return a new Error object to throw a new error. Returning null or undefined will rethrow the original error. If you want to force retrying to be skipped, return { skipRetrying: true }.

Show arguments

error · unknown

The underlying error that was thrown inside the Task callback.

task · Task

The Task that failed.

Returns

A Promise that resolves with the returned value of the callback.

If the remote callback feature options.callback is enabled, the Promise will instead resolve with the body of the first request sent to task.callbackUrl.

Run a task

client.defineJob({
  id: "alert-on-new-github-issues",
  name: "Alert on new GitHub issues",
  version: "1.0.0",
  trigger: github.triggers.repo({
    event: events.onIssueOpened,
    owner: "triggerdotdev",
    repo: "trigger.dev",
  }),
  run: async (payload, io, ctx) => {
    const record = await io.runTask(
      "sync-github-issue",
      async (task) => {
        return prisma.githubIssues.create({
          data: {
            number: payload.issue.number,
            title: payload.issue.title,
            body: payload.issue.body,
            url: payload.issue.html_url,
            repo: payload.repository.full_name,
            owner: payload.repository.owner.login,
          },
        });
      },
      //this is optional
      { name: "Sync GitHub Issue", icon: "github" }
    );
  },
});