Workflows

They're most helpful when you have multiple tasks in a row, and you want to configure each task to be able to be retried if they fail.

If a task within a workflow fails, the Workflow will automatically "pick back up" on the task where it failed and not re-execute any prior tasks that have already been executed.

Defining a workflow

The most important aspect of a Workflow is the handler, where you can declare when and how the tasks should run by simply calling the runTask function. If any task within the workflow, fails, the entire handler function will re-run.

However, importantly, tasks that have successfully been completed will simply re-return the cached and saved output without running again. The Workflow will pick back up where it failed and only task from the failure point onward will be re-executed.

To define a JS-based workflow, simply add a workflow to the jobs.wokflows array in your Payload config. A workflow consists of the following fields:

Option	Description
`slug`	Define a slug-based name for this workflow. This slug needs to be unique among both tasks and workflows.
`handler`	The function that should be responsible for running the workflow. You can either pass a string-based path to the workflow function file, or workflow job function itself. If you are using large dependencies within your workflow, 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 workflow. By default, this is "Workflow" + the capitalized workflow slug.
`label`	Define a human-friendly label for this workflow.
`queue`	Optionally, define the queue name that this workflow should be tied to. Defaults to "default".
`retries`	You can define `retries` on the workflow level, which will enforce that the workflow can only fail up to that number of retries. If a task does not have retries specified, it will inherit the retry count as specified on the workflow. You can specify `0` as `workflow` retries, which will disregard all `task` retry specifications and fail the entire workflow on any task failure. You can leave `workflow` retries as undefined, in which case, the workflow will respect what each task dictates as their own retry count. By default this is undefined, meaning workflows retries are defined by their tasks

Example:

1export default buildConfig({
// ...
jobs: {
  tasks: [
    // ...
  ]
  workflows: [
    {
      slug: 'createPostAndUpdate',
10
      // The arguments that the workflow will accept
      inputSchema: [
        {
          name: 'title',
          type: 'text',
          required: true,
        },
      ],
19
      // The handler that defines the "control flow" of the workflow
      // Notice how it uses the `tasks` argument to execute your predefined tasks.
      // These are strongly typed!
      handler: async ({ job, tasks }) => {
24
        // This workflow first runs a task called `createPost`.
26
        // You need to define a unique ID for this task invocation
        // that will always be the same if this workflow fails
        // and is re-executed in the future. Here, we hard-code it to '1'
        const output = await tasks.createPost('1', {
          input: {
            title: job.input.title,
          },
        })
35
        // Once the prior task completes, it will run a task
        // called `updatePost`
        await tasks.updatePost('2', {
          input: {
            post: job.taskStatus.createPost['1'].output.postID, // or output.postID
            title: job.input.title + '2',
          },
        })
      },
    } as WorkflowConfig<'updatePost'>
  ]
}
48})

Running tasks inline

In the above example, our workflow was executing tasks that we already had defined in our Payload config. But, you can also run tasks without predefining them.

To do this, you can use the inlineTask function.

The drawbacks of this approach are that tasks cannot be re-used across workflows as easily, and the task data stored in the job will not be typed. In the following example, the inline task data will be stored on the job under job.taskStatus.inline['2'] but completely untyped, as types for dynamic tasks like these cannot be generated beforehand.

Example:

1export default buildConfig({
// ...
jobs: {
  tasks: [
    // ...
  ]
  workflows: [
    {
      slug: 'createPostAndUpdate',
      inputSchema: [
        {
          name: 'title',
          type: 'text',
          required: true,
        },
      ],
      handler: async ({ job, tasks, inlineTask }) => {
        // Here, we run a predefined task.
        // The `createPost` handler arguments and return type
        // are both strongly typed
        const output = await tasks.createPost('1', {
          input: {
            title: job.input.title,
          },
        })
26
        // Here, this task is not defined in the Payload config
        // and is "inline". Its output will be stored on the Job in the database
        // however its arguments will be untyped.
        const { newPost } = await inlineTask('2', {
          task: async ({ req }) => {
            const newPost = await req.payload.update({
              collection: 'post',
              id: '2',
              req,
              retries: 3,
              data: {
                title: 'updated!',
              },
            })
            return {
              output: {
                newPost
              },
            }
          },
        })
      },
    } as WorkflowConfig<'updatePost'>
  ]
}
52})

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.

Workflows

Defining a workflow

Running tasks inline

Jobs