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.

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:

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

Jobs can be queued from anywhere in your application. Here are the most common scenarios:

The most common place - queue jobs in response to document changes:

Queue jobs based on specific field changes:

Queue jobs from your API routes:

Queue jobs from Next.js server actions:

When queuing a job, you can pass additional options:

• waitUntil - Schedule the job to run at a specific date/time in the future
• queue - Assign the job to a specific queue (defaults to 'default')
• log - Add custom log entries for debugging or tracking
• req - Pass the request context for access control

After queuing a job, you can check its status:

Each job document contains:

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:

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:

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.

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

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