Background jobs
Background job basics
Background jobs automate work on a schedule or in response to an entity record event. Configure them in Settings → Background Jobs. A job chooses source records, can filter them, and applies an action to those records or related records.
Scheduled jobs run only while the job runner is active. Event jobs can be configured for record create, update or delete triggers and use the same self or relation action patterns. Automatic event execution still needs to be connected to record saves, so do not rely on event jobs to run until that wiring is available.
| Prop | Type | Description |
|---|---|---|
| Trigger | When | A cron schedule for recurring work, or a record event such as create, update or delete. |
| Source entity | Where | The entity whose records the job examines. |
| Source filter | Which records | An optional comparison that limits the source records considered by the action. |
| Mode and action | What happens | A self action changes source records; relation mode performs an operation on related records. |
- Self mode updates or deletes matching source records.
- Relation mode acts on related records, with create, update, delete or upsert behavior.
- Filters and values choose which records qualify and what values actions write.
Create a background job
Create a job from Settings → Background Jobs using the form. The form guides you through the trigger, source, optional conditions and action fields; you do not need to write a job definition as JSON.
Add a job
Choose when it runs
Select the source
Configure the action
Save and review
In self mode, choose whether the matching source records should be updated or deleted, then set the fields to write for an update. In relation mode, choose the target relation and match behavior, then define what to do when a matching target record exists and when it does not.
Before saving, read the job from top to bottom: the trigger determines when it runs, the source and filter determine which records it sees, and the action determines the changes it makes. Keep jobs focused so the effect is easy to understand and review.
Schedule a background job
A scheduled job uses a five-field cron expression: minute, hour, day of month, month and day of week. The runner checks schedules each minute.
| Prop | Type | Description |
|---|---|---|
| Minute | 0–59 | The minute of the hour when the job should run. |
| Hour | 0–23 | The hour of the day, using a 24-hour clock. |
| Day of month | 1–31 | The calendar day in the month. |
| Month | 1–12 | The calendar month. |
| Day of week | 0–6 | The weekday; Sunday is 0. |
*/5 * * * * every five minutes
0 18 * * * every day at 18:00
0 9 * * 1-5 weekdays at 09:00
30 8 1 * * first day of each month at 08:30*means every allowed value.*/nmeans every n values.a-bmeans a range.a,b,cmeans a list of values.
Choose a schedule that matches how often the source data needs attention. Very frequent jobs can repeatedly process the same records if the action does not change the filter condition.
For example, 0 18 * * * runs daily at 18:00. The expression 0 9 * * 1-5 runs on weekdays at 09:00. Make sure the action is safe to repeat: a daily job should not create duplicate related records every time it runs unless the match/upsert logic prevents that.
Run and stop jobs
Saving a scheduled job defines its configuration. The job runner must be started before scheduled jobs execute. Use the Start and Stop controls on the Background Jobs settings page to control the runner.
- Start the runner after reviewing the configured jobs.
- The page shows whether the runner is active.
- Stop pauses scheduled job execution.
- Saving updated configurations while the runner is active refreshes the registered jobs.
Use Stop when you need to pause all scheduled work while editing a set of jobs or investigating an unexpected result. After changes, review the schedule and action fields, save, then start the runner again and confirm its status.
A saved schedule is not a running schedule
Values and filters
Filters narrow the source records a job processes. A condition compares a field with a value. Values can refer to the current source record or use a literal.
| Prop | Type | Description |
|---|---|---|
| $source.field | Reference | Reads a field from the source record being processed, for example $source.total. |
| today | Date | The current date. |
| now | Date-time | The current timestamp. |
| Literal | Text or number | A quoted string, numeric value or boolean such as true. |
Comparison operators include equals, not equals, greater than, greater than or equal, less than and less than or equal. For example, a filter can match status = pending or total >= 100.