Jobs are how a Core dna site reacts without code in the theme: send a notification when a form is completed, push an order to a warehouse, export products every night, answer a partner's call on a web event. This guide covers building them so they do what you meant, once, and can be read when they do not.

Who this guide is for

Site builders and integration engineers who build jobs, and developers who write the templates inside them. It assumes you can write a template in Smarty or Twig (Template languages); the last units also assume you have called an HTTP API before. Every template example is given in both engines.

The units, in order

  1. The job model: what a job is made of, reading a run, moving jobs between environments, and testing without live data. Read it first.
  2. What starts a job: record events, web events, schedules and other jobs, and guarding against recursion.
  3. What a job does: every kind of action, what it leaves for the next one, and how it fails.
  4. Branches, loops and re-runs: conditions, loops, and jobs that can run twice safely.
  5. Email: what Send mail queues, templates for the body, deliverability and testing.
  6. Scheduled jobs: the scheduler and the job queue, watermarks and chunking, and noticing when a scheduled job stops.
  7. Jobs and other systems: the integration patterns, retries and dead letters, field ownership, and a complete integration to copy.
  8. Reference: every event that can start a job and every action it can run.

Five things to know first

  1. Read the run before changing the job. Every run records what each action did, in order; it answers most questions faster than the job's settings do (Reading a job run).
  2. A job can start itself. A job that updates a record on that record's update event can trigger itself again; put a condition on the field that changed (Guarding against recursion).
  3. JSON is built, not typed. Every value interpolated into a JSON body goes through |json_encode, or one quote in a name breaks the request (Anatomy of a job).
  4. Every job that writes runs twice one day. A re-run after a fix, a retried call or an overlapping schedule; design the second run to change nothing (Idempotency and replay).
  5. Test without live data. Run a new job against test records before it meets real ones (Testing a job without touching live data).

Testing a job before it goes live is on Testing a job without touching live data.

Covered elsewhere