How to Set Up Background Jobs and Scheduled Tasks
Why You Need Background Jobs
Some operations take too long to complete while a user is waiting for a response. If a customer uploads a CSV file with 10,000 contacts, processing every row during the HTTP request would time out. Instead, you accept the file immediately, queue a background job to process it, and let the user continue working while the job runs in the background.
Common SaaS operations that belong in background jobs:
- Processing uploaded files (CSV imports, document parsing)
- Sending bulk email or SMS campaigns
- Generating reports from large datasets
- Syncing data with external APIs
- Running AI analysis on customer data
- Cleaning up expired records or temporary data
How the Job Queue Works
The platform uses a job queue stored in the jobsData DynamoDB table. When your code needs to run something in the background, it creates a job record with the job type, the account ID, and any data the job needs. The cron system checks for queued jobs every minute and spawns a worker process for each one.
Your job function receives the same parameters as a regular command function: the account ID and the job data. It runs in an isolated process, so even if it takes several minutes, it does not affect any other user's requests.
How Scheduled Tasks Work
Scheduled tasks run automatically on a time-based schedule without anyone triggering them. You define schedules in your app configuration using a simple time format. Common schedule patterns:
- Every hour: Run at the top of every hour (useful for data sync, health checks)
- Once daily: Run at a specific hour (useful for daily reports, digest emails)
- Business hours only: Run hourly during 8 AM to 7 PM (useful for monitoring that does not need to run overnight)
- Every minute: The cron system checks every minute, so your shortest interval is one minute
When a scheduled task fires, the system runs your function for each account that has your app enabled and has scheduling turned on. This means one schedule definition in your app config can serve all of your SaaS customers automatically.
Building a Background Job
Add an entry to your appJobs configuration with a name and the function to call. This tells the job runner which function to execute when a job of this type is picked up.
Your function receives the account ID and the job data. Process the work, update the database with results, and return a status. Handle errors gracefully so a failure in one job does not affect others.
When a user action should trigger background processing (like uploading a file or requesting a report), your API endpoint creates a job record in the queue. The user gets an immediate response, and the job runs in the background.
When the job completes, update the user's data with the results. They can check the status in the admin panel, or you can send a notification email when the job finishes.
Practical Examples
CSV Import Job
User uploads a CSV file through the admin panel. Your API endpoint saves the file and queues a background job. The job reads the CSV row by row, validates each record, and inserts it into the database. When finished, it updates the account's data with the total imported count so the user can see the result.
Daily Report Job
A scheduled task runs at 8 AM every day. For each account, it queries the previous day's activity, generates a summary, and sends it via email using the email automation system. Customers wake up to a daily report without clicking anything.
Data Sync Job
A scheduled task runs every hour. For each account that has an external API configured, it pulls new data from the external system and updates the local database. This keeps your SaaS data fresh without requiring users to manually trigger a sync.
Background jobs and scheduled tasks built into the platform. Process uploads, send reports, and sync data automatically.
Get Started Free