Tasks

You can register Tasks on the Payload config, and then create Jobs or Workflows that use them. Think of Tasks like tidy, isolated "functions that do one specific thing".

Payload Tasks can be configured to automatically retried if they fail, which makes them valuable for "durable" workflows like AI applications where LLMs can return non-deterministic results, and might need to be retried.

Tasks can either be defined within the jobs.tasks array in your payload config, or they can be defined inline within a workflow.

Defining tasks in the config

Simply add a task to the jobs.tasks array in your Payload config. A task consists of the following fields:

Option	Description
`slug`	Define a slug-based name for this job. This slug needs to be unique among both tasks and workflows.
`handler`	The function that should be responsible for running the job. You can either pass a string-based path to the job function file, or the job function itself. If you are using large dependencies within your job, you might prefer to pass the string path because that will avoid bundling large dependencies in your Next.js app. Passing a string path is an advanced feature that may require a sophisticated build pipeline in order to work.
`inputSchema`	Define the input field schema - payload will generate a type for this schema.
`interfaceName`	You can use interfaceName to change the name of the interface that is generated for this task. By default, this is "Task" + the capitalized task slug.
`outputSchema`	Define the output field schema - payload will generate a type for this schema.
`label`	Define a human-friendly label for this task.
`onFail`	Function to be executed if the task fails.
`onSuccess`	Function to be executed if the task succeeds.
`retries`	Specify the number of times that this step should be retried if it fails. If this is undefined, the task will either inherit the retries from the workflow or have no retries. If this is 0, the task will not be retried. By default, this is undefined.

The logic for the Task is defined in the handler - which can be defined as a function, or a path to a function. The handler will run once a worker picks picks up a Job that includes this task.

It should return an object with an output key, which should contain the output of the task as you've defined.

Example:

1export default buildConfig({
// ...
jobs: {
  tasks: [
    {
      // Configure this task to automatically retry
      // up to two times
      retries: 2,
9
      // This is a unique identifier for the task
11
      slug: 'createPost',
13
      // These are the arguments that your Task will accept
      inputSchema: [
        {
          name: 'title',
          type: 'text',
          required: true,
        },
      ],
22
      // These are the properties that the function should output
      outputSchema: [
        {
          name: 'postID',
          type: 'text',
          required: true,
        },
      ],
31
      // This is the function that is run when the task is invoked
      handler: async ({ input, job, req }) => {
        const newPost = await req.payload.create({
          collection: 'post',
          req,
          data: {
            title: input.title,
          },
        })
        return {
          output: {
            postID: newPost.id,
          },
        }
      },
    } as TaskConfig<'createPost'>,
  ]
}
50})

In addition to defining handlers as functions directly provided to your Payload config, you can also pass an absolute path to where the handler is defined. If your task has large dependencies, and you are planning on executing your jobs in a separate process that has access to the filesystem, this could be a handy way to make sure that your Payload + Next.js app remains quick to compile and has minimal dependencies.

Keep in mind that this is an advanced feature that may require a sophisticated build pipeline, especially when using it in production or within Next.js, e.g. by calling opening the /api/payload-jobs/run endpoint. You will have to transpile the handler files separately and ensure they are available in the same location when the job is run. If you're using an endpoint to execute your jobs, it's recommended to define your handlers as functions directly in your Payload Config, or use import paths handlers outside of Next.js.

In general, this is an advanced use case. Here's how this would look:

payload.config.ts:

1import { fileURLToPath } from 'node:url'
2import path from 'path'
3
4const filename = fileURLToPath(import.meta.url)
5const dirname = path.dirname(filename)
6
7export default buildConfig({
8  jobs: {
9    tasks: [
10      {
11        // ...
12        // The #createPostHandler is a named export within the `createPost.ts` file
13        handler: path.resolve(dirname, 'src/tasks/createPost.ts') + '#createPostHandler',
14      }
15    ]
16  }
17})

Then, the createPost file itself:

src/tasks/createPost.ts:

1import type { TaskHandler } from 'payload'
2
3export const createPostHandler: TaskHandler<'createPost'> = async ({ input, job, req }) => {
const newPost = await req.payload.create({
  collection: 'post',
  req,
  data: {
    title: input.title,
  },
})
return {
  output: {
    postID: newPost.id,
  },
}
16}

Configuring task restoration

By default, if a task has passed previously and a workflow is re-run, the task will not be re-run. Instead, the output from the previous task run will be returned. This is to prevent unnecessary re-runs of tasks that have already passed.

You can configure this behavior through the retries.shouldRestore property. This property accepts a boolean or a function.

If shouldRestore is set to true, the task will only be re-run if it previously failed. This is the default behavior.

If shouldRestore this is set to false, the task will be re-run even if it previously succeeded, ignoring the maximum number of retries.

If shouldRestore is a function, the return value of the function will determine whether the task should be re-run. This can be used for more complex restore logic, e.g you may want to re-run a task up to X amount of times and then restore it for consecutive runs, or only re-run a task if the input has changed.

Example:

1export default buildConfig({
// ...
jobs: {
  tasks: [
    {
      slug: 'myTask',
      retries: {
        shouldRestore: false,
      }
      // ...
    } as TaskConfig<'myTask'>,
  ]
}
14})

Example - determine whether a task should be restored based on the input data:

1export default buildConfig({
// ...
jobs: {
  tasks: [
    {
      slug: 'myTask',
      inputSchema: [
        {
          name: 'someDate',
          type: 'date',
          required: true,
        },
      ],
      retries: {
        shouldRestore: ({ input }) => {
          if(new Date(input.someDate) > new Date()) {
            return false
          }
          return true
        },
      }
      // ...
    } as TaskConfig<'myTask'>,
  ]
}
26})

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Tasks

Defining tasks in the config

Configuring task restoration

Workflows