Quick Start Example

Let's walk through a practical example of setting up a simple job queue. We'll create a task that sends a welcome email when a user signs up.

You might wonder: "Why not just send the email directly in the afterChange hook?"

• Non-blocking: If your email service takes 2-3 seconds to send, your API response would be delayed. With jobs, the API returns immediately.
• Resilience: If the email service is temporarily down, the hook would fail and potentially block the user creation. Jobs can retry automatically.
• Scalability: As your app grows, you can move job processing to dedicated servers, keeping your API fast.
• Monitoring: All jobs are tracked in the database, so you can see if emails failed and why.

Now let's build this example step by step.

First, create a task in your payload.config.ts:

This defines a reusable task with a unique slug, an inputSchema that validates and types the input data, and a handler function containing the work to be performed. The retries option ensures the task will automatically retry up to 3 times if it fails. Learn more about Tasks.

This uses payload.jobs.queue() to create a job instance from the task definition. The job is added to the queue immediately but runs asynchronously, so the API response returns right away without waiting for the email to send. Jobs are stored in the database as documents in the payload-jobs collection.

The autoRun configuration automatically processes queued jobs on a schedule using cron syntax. In this example, Payload checks for pending jobs every 5 minutes and executes them. Alternatively, you can manually trigger job processing with payload.jobs.run() or use the API endpoint for serverless platforms.

That's it! Now when users sign up, a job is queued and will be processed within 5 minutes without blocking the API response.

The previous example showed manual job queuing (jobs triggered by user actions). Now let's look at a job that runs automatically on a schedule without any user action.

We'll create a task that generates a daily analytics report every morning at 8 AM.

• Automated recurring tasks: No need to manually trigger them
• Predictable timing: Reports, cleanups, syncs run at exact times
• No manual intervention: Set it once and forget it

The schedule property defines when this job should run (every day at 8 AM).

To actually queue and execute scheduled jobs, you need to configure the autoRun property. This handles both queuing jobs based on their schedule and running them:

Here's the complete flow:

1. At 8:00 AM: The schedule configuration automatically queues a new job in the 'reports' queue
2. Within 1 minute: The autoRun cron checks the 'reports' queue and finds the job
3. Execution: The job runs and generates the report
4. The next day: The process repeats automatically at 8:00 AM

Here's the full config with both the task and runner:

For scheduled jobs with waitUntil:

This is different from the schedule property, which repeats automatically.

See Job Schedules for more details on scheduling options and advanced patterns.