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" }
    );
  },
});