A job is a trigger, conditions and an ordered list of actions, set up under Customization › Orchestration in the admin; jobs were called hooks before the module was renamed, and the API's routes keep that name. What starts a job, what it can do, branches and loops, email, scheduled work, integrations with other systems, and every event and action.
L2–L3
Unit 08 · Reference
Job event reference
ReferencePage 30 of 31Updated
Every event that can start a job, one entry each: the record events every entity has, the six that particular entities add, web events, schedules and jobs started by other jobs. When each fires, what it carries, its loop risk, and an example.
Who this is for. Anyone wiring a job's trigger who needs one event's exact behaviour: what fires it, what it carries, and its loop risk. Afterwards you can pick the right event and read its data without guessing.
Every event that can start a job, one entry each. The event names are read from the platform's source: the three record methods every entity has, and the extra methods below. How to choose between them is on Events, what starts a job; this page is for looking one up.
In every job template the event is the variable event ($event in Smarty). For an entity event it offers getRecord(), getRecordId(), getMethod() and getPreEventData(); the other kinds are listed with their own entries.
Record events, on every entity
CreateRecord
Fires
When a record of the entity is saved for the first time, from the admin, the API or a front-end form
Receives
The new record, read when the batch runs
Loop risk
A synchronous job that creates a record of the same entity starts itself again. Records created by an asynchronous job fire no events
Example
Pages, CreateRecord → email the content team a link to the new page
UpdateRecord
Fires
When a saved record changes, once per save; also when a scheduled publish or unpublish date arrives
Receives
The record as it is when the batch runs, and getPreEventData() with the fields listed under the trigger's Pre-Event properties, as they were before the change
Loop risk
High for a synchronous job that writes the record it watches. Guard on the changed field: see Guarding against recursion
Example
Blog posts, UpdateRecord, Pre-Event {published} → post to social channels when published goes from empty to a date
DeleteRecord
Fires
When a record is deleted
Receives
The record id and name; the record itself no longer exists when the batch runs, so capture its fields with Pre-Event properties
Loop risk
None from the record itself
Example
Products, DeleteRecord, Pre-Event {externalId} → tell the ERP the product is gone
StartEditingRecord
Fires
When someone opens a record for editing in the admin, only on sites where that logging is switched on (Globals.admin.logRecordEditingStartEvent), and only if it was last saved more than Globals.admin.logRecordEditingStartEventDelay ago (10 seconds by default)
Receives
The record
Loop risk
None
Example
Pages, StartEditingRecord → notify the page's owner that someone else is editing it
Events particular to one entity
Completed (form submissions)
Fires
When a submission is completed: once, the first time, including the last step of a multi-step form. Not on later edits
Receives
The submission. Narrow the trigger to one form with its parent record id
Loop risk
None: editing the submission does not fire it again
Example
Form submissions, Completed, parent = the contact form → push to the CRM
Abandoned (carts)
Fires
When a background check finds a cart that has items and a shopper's email and has not changed for the abandoned threshold, an hour by default (Carts.abandonedThreshold, in seconds). Once per cart
Receives
The cart
Loop risk
None; it is raised by the check, not by a save
Example
Carts, Abandoned → send a reminder email with a link back to the cart
SendReceipt (invoices)
Fires
When an administrator uses Send receipt on an invoice in the admin
Receives
The invoice
Loop risk
None
Example
Invoices, SendReceipt → render the receipt template and email it to the customer
BackInStock (products, variants)
Fires
When a product's or a product variant's available stock, summed across all warehouses, rises above Products.interest.stockThreshold (0 by default). Once per crossing
Receives
The product or variant
Loop risk
None; it is raised by a stock change, not by a save
Example
Product variants, BackInStock → notify the people waiting for it and mark their interests completed
Login (users)
Fires
When a user signs in with a username and password through the platform's login, and only on sites where Globals.admin.logLoginEvent is switched on (off by default)
Receives
The user. A userId is queued with the event but is not kept on the run, so a job template cannot read it
Loop risk
An update to the user from a synchronous job starts the user's UpdateRecord jobs
Example
Users, Login → record the last sign-in on the member's person record
ExportPDF (books)
Fires
When a PDF export of a book is requested
Receives
The book
Loop risk
None
Example
Books, ExportPDF → notify the requester when the export is ready
Other ways a job starts
Web event
Fires
When an HTTP request with an allowed method reaches /cdna-api/webhook/<slug> and the job is published
A job that calls its own URL with an HTTP request action
Example
A payment provider's webhook, asynchronous → update the order. Full treatment: Custom endpoints
Scheduled
Fires
At each time of the job's recurring schedule (a cron expression in the client's timezone) or on each of its one-off dates. Needs a job limited to one site
Receives
The scheduler task that fired; no record
Loop risk
Overlap rather than a loop: the next run is queued whether or not the last one finished
Example
0 2 * * * → export the day's orders as CSV
Triggered by another job
Fires
When another job's Trigger job action runs: inside that batch if this job is synchronous, queued if not
Receives
getData() (the JSON the trigger action rendered), getSourceBatch(), getSourceHook()
Loop risk
Two jobs that trigger each other. Pass a depth or a marker in the data and stop on it
Example
"Order: completed → find warehouse" triggers "Job: after order → email warehouse"