defineJob()

Defines a job

These are the docs for Trigger.dev v2 which will be deprecated on January 31st, 2025. You probably want the v3 docs.

A Job is used to define the Trigger, metadata, and what happens when it runs.

example

client.defineJob({
  id: "github-integration-on-issue",
  name: "GitHub Integration - On Issue",
  version: "0.1.0",
  trigger: github.triggers.repo({
    event: events.onIssue,
    owner: "triggerdotdev",
    repo: "empty",
  }),
  run: async (payload, io, ctx) => {
    await io.logger.info("This is a simple log info message");
    return { payload, ctx };
  },
});

Parameters

options · object · required

Hide properties

id · string · required

The id property is used to uniquely identify the Job. Only change this if you want to create a new Job.

name · string · required

The name of the Job that you want to appear in the dashboard and logs. You can change this without creating a new Job.

version · string · required

The version property is used to version your Job. A new version will be created if you change this property. We recommend using semantic versioning, e.g. 1.0.3.

trigger · object · required

The trigger property is used to define when the Job should run. There are currently the following Trigger types:

• invokeTrigger
• cronTrigger
• intervalTrigger
• eventTrigger
• DynamicTrigger
• DynamicSchedule
• integration Triggers, like webhooks. See the integrations page for more information.

run · function · required

This function gets called automatically when a Run is Triggered. It has three parameters:

1. payload – The payload that was sent to the Trigger API.
2. io – An object that contains the integrations that you specified in the integrations property and other useful functions like delays and running Tasks.
3. context – An object that contains information about the Organization, Job, Run and more.

This is where you put the code you want to run for a Job. You can use normal code in here and you can also use Tasks.

You can return a value from this function and it will be sent back to the Trigger API.

integrations · object

Imports the specified integrations into the Job. The integrations will be available on the io object in the run() function with the same name as the key. For example:

client.defineJob({
  //... other options
  integrations: {
    slack,
    gh: github,
  },
  run: async (payload, io, ctx) => {
    //slack is available on io.slack
    io.slack.postMessage(...);
    //github is available on io.gh
    io.gh.addIssueLabels(...);
  }
});

enabled · boolean

The enabled property is an optional property that specifies whether the Job is enabled or not. The Job will be enabled by default if you omit this property. When a job is disabled, no new runs will be triggered or resumed. In progress runs will continue to run until they are finished or delayed by using io.wait.

concurrencyLimit · number | ConcurrencyLimit

The concurrencyLimit property is an optional property that specifies the maximum number of concurrent run executions. If this property is omitted, the job can potentially use up the full concurrency of an environment. You can also create a limit on a group of jobs by defining a ConcurrencyLimit object.

onSuccess · function

The onSuccess property is an optional property that specifies a callback function to run when the Job finishes successfully. The callback function receives a Run Notification object as it's only parameter.

onFailure · function

The onFailure property is an optional property that specifies a callback function to run when the Job fails to complete successfully. The callback function receives a Run Notification object as it's only parameter.

logLevel · log | error | warn | info | debug

The logLevel property is an optional property that specifies the level of logging for the Job. The level is inherited from the client if you omit this property.

• log - logs only essential messages
• error - logs error messages
• warn - logs errors and warning messages
• info - logs errors, warnings and info messages
• debug - logs everything with full verbosity

Returns

Job instance · Job