Jobs

Now that we have covered Tasks and Workflows, we can tie them together with a concept called a Job.

For example, let's say we have a Workflow or Task that describes the logic to sync information from Payload to a third-party system. This is how you'd declare how to sync that info, but it wouldn't do anything on its own. In order to run that task or workflow, you'd create a Job that references the corresponding Task or Workflow.

Jobs are stored in the Payload database in the payload-jobs collection, and you can decide to keep a running list of all jobs, or configure Payload to delete the job when it has been successfully executed.

Queuing a new job

In order to queue a job, you can use the payload.jobs.queue function.

Here's how you'd queue a new Job, which will run a createPostAndUpdate workflow:

1const createdJob = await payload.jobs.queue({
// Pass the name of the workflow
workflow: 'createPostAndUpdate',
// The input type will be automatically typed
// according to the input you've defined for this workflow
input: {
  title: 'my title',
},
9})

In addition to being able to queue new Jobs based on Workflows, you can also queue a job for a single Task:

1const createdJob = await payload.jobs.queue({
2  task: 'createPost',
3  input: {
4    title: 'my title',
5  },
6})

Access Control

By default, Payload's job operations bypass access control when used from the Local API. You can enable access control by passing overrideAccess: false to any job operation.

To define custom access control for jobs, add an access property to your Jobs Config:

1import type { SanitizedConfig } from 'payload'
2
3const config: SanitizedConfig = {
// ...
jobs: {
  access: {
    // Control who can queue new jobs
    queue: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
    // Control who can run jobs
    run: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
    // Control who can cancel jobs
    cancel: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
  },
},
21}

Each access control function receives the current req object and should return a boolean. If no access control is defined, the default behavior allows any authenticated user to perform the operation.

To use access control in the Local API:

1const req = await createLocalReq({ user }, payload)
2
3await payload.jobs.queue({
4  workflow: 'createPost',
5  input: { title: 'My Post' },
6  overrideAccess: false, // Enable access control
7  req, // Pass the request with user context
8})

Cancelling Jobs

Payload allows you to cancel jobs that are either queued or currently running. When cancelling a running job, the current task will finish executing, but no subsequent tasks will run. This happens because the job checks its cancellation status between tasks.

Cancel a Single Job

To cancel a specific job, use the payload.jobs.cancelByID method with the job's ID:

1await payload.jobs.cancelByID({
2  id: createdJob.id,
3})

Cancel Multiple Jobs

To cancel multiple jobs at once, use the payload.jobs.cancel method with a Where query:

1await payload.jobs.cancel({
where: {
  workflowSlug: {
    equals: 'createPost',
  },
},
7})

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."

Get the resources you need to start building today