Background Jobs
Learn how to add background job processing to your REST API using Motia's event system and cron scheduling. This guide covers automated pet care reminders and event-driven tasks.
In our previous tutorial, you built a complete REST API for managing pets with full CRUD operations. When users create pets through your API, the system responds immediately. But what about ongoing pet care? Real pet stores need to send feeding reminders, schedule grooming, and track vet checkups.
Now we'll extend your pet store API to handle these ongoing tasks automatically using background jobs. You'll learn how to trigger tasks when pets are created and schedule recurring reminders, all without blocking your API responses or requiring external services.
Background Job Concepts You'll Use
Before we start building, let's cover the key concepts for adding background jobs to your pet store API:
- Event Step – A step that listens for specific events (like "pet-created") and processes tasks asynchronously when those events occur.
- Cron Step – A step that runs on a schedule (daily, weekly, monthly) to handle recurring tasks like sending reminders.
- Event Emission – How your API steps trigger background jobs by emitting events after completing their main task.
- Job Scheduling – Using cron expressions to define when scheduled jobs should run (e.g., every day at 8 AM).
- Simulated Notifications – Logging structured messages that represent real-world notifications without external dependencies.
Background Job Architecture
Your pet store will use two types of background jobs working together:
Job Type | Trigger | Purpose | Motia Step Type |
---|---|---|---|
Adoption Follow-up | When pet is created via API | Send immediate welcome message to new pet owner | Event Step |
Daily Feeding Reminders | Every day at 8 AM | Remind owners to feed their pets | Cron Step |
Weekly Grooming Notifications | Every Monday at 9 AM | Remind owners about grooming appointments | Cron Step |
Monthly Vet Checkups | First day of month at 10 AM | Alert owners about veterinary checkups | Cron Step |
The Flow
When someone creates a pet through your REST API:
- API responds immediately with the created pet data
- Event gets emitted with the new pet information
- Adoption follow-up job runs and logs a welcome message
- Scheduled jobs continue running independently to send ongoing care reminders
This architecture keeps your API fast while ensuring pets get proper ongoing care through automated reminders.
Step 1: Add Event Emission to Your Pet API
First, we need to modify your existing POST /pets
endpoint from Tutorial 1 to emit events when pets are created. This will trigger the background jobs.
Open your existing steps/create-pet.step.ts
file and update it:
The key changes are:
- Added
emits: ['pet-created']
to the configuration - Added
emit
to the handler parameters - Added
await emit()
call after creating the pet
Now when you create a pet, your API will emit a pet-created
event that background jobs can listen for.
Step 2: Create the Adoption Follow-up Background Job
Now let's create an event step that listens for the pet-created
event and sends a welcome message to the new pet owner.
Create a new file for the adoption follow-up job:
File: steps/adoption-followup.step.ts
This event step demonstrates how background jobs work:
- Subscribes to
pet-created
- Automatically runs when the API emits this event - Processes immediately - Runs as soon as a pet is created
- Simulates real tasks - Logs welcome message and care package preparation
- No external dependencies - Uses only Motia's built-in logging
When you create a pet via the API, you'll see these welcome messages appear in your logs automatically.
Adoption Followup Message
Welcome Care Package
Step 3: Create Daily Feeding Reminders
Now let's create a cron step that runs every day to remind pet owners about feeding their pets.
Create a new file for the daily feeding reminders:
File: steps/daily-feeding-reminder.step.ts
This cron step demonstrates scheduled job patterns:
- Runs on schedule -
cron: '0 8 * * *'
means every day at 8 AM - Processes all pets - Loops through each pet to send reminders
- Different feeding schedules - Cats get 2 meals, dogs get 3 meals per day
- Structured logging - Each reminder is logged with detailed information
This job will run automatically every morning, ensuring all pets get their daily feeding reminders.
Daily Notification Job starting
Daily Notification Job completion
Step 4: Create Weekly Grooming Notifications
Let's create a cron step that runs every Monday to remind pet owners about grooming appointments.
Create a new file for the weekly grooming notifications:
File: steps/weekly-grooming-reminder.step.ts
This weekly cron step shows more advanced scheduling:
- Runs every Monday -
cron: '0 9 * * 1'
means 9 AM on day 1 (Monday) of every week - Breed-specific grooming - Different pets have different grooming needs
- Detailed task lists - Shows specific grooming tasks for each breed type
- Helper function - Demonstrates code organization within steps
This job ensures all pets get appropriate grooming reminders based on their specific needs.
Weekly Notification Job starting
Weekly Notification Job completion
Step 5: Create Monthly Vet Checkup Alerts
Finally, let's create a cron step that runs on the first day of every month to remind pet owners about veterinary checkups.
Create a new file for the monthly vet checkup alerts:
File: steps/monthly-vet-reminder.step.ts
This monthly cron step demonstrates the most complex scheduling pattern:
- Runs monthly -
cron: '0 10 1 * *'
means 10 AM on the 1st day of every month - Age-based care - Senior pets (7+) get enhanced monitoring, young pets need frequent checkups
- Urgency levels - Different pets have different health priorities
- Comprehensive logging - Includes month context and detailed health recommendations
Monthly Notification Job starting
Monthly Notification Job completion
This ensures all pets receive appropriate veterinary care based on their age and breed characteristics.