Events

React to changes: webhooks, e-mails, records - directly or queued.

Events react to changes (Administration › Events, admins only): what they listen to (source), the actions, an optional condition and the steps.

source Actions The record of the event
entity (with entity) create, update, delete, publish, unpublish, restore the record of the entity
media create (upload), update (renamed, kept or not), delete the file as the API presents it (id, name, url, mime_type …)
variables create, update, delete the variable (name, value, translations)
event execute only the records of the run that started it, plus the values of its step (see below)

For media and variables the condition is checked on the data itself (eq, ne, gt, gte, lt, lte, in, like, null, plus _changed and _old), e.g. {"name": "url", "_changed": ["value"]}. The cleanup of unused files (./yii cleanup) starts no events.

{
  "name": "Variant for a new product",
  "entity": "products",
  "actions": ["create", "publish"],
  "condition": { "draft": false, "price": { "gte": 10 } },
  "mode": "direct",
  "steps": [
    { "type": "create", "entity": "variants", "data": { "product": "{{record.id}}", "title": "{{record.title}} – Standard" } },
    { "type": "webhook", "url": "https://shop.example.com/hook", "secret": "…" },
    { "type": "email", "to": "team@example.com", "subject": "New: {{record.title}}", "body": "{{project.url}}", "digest": true }
  ]
}
  • Condition: the filter language of the content API, checked in the database against the record - every operator and filters on references work. _changed: ["price"] matches when one of the fields changed, _old: {"price": {"lt": 10}} checks the state before. For delete the condition is checked before the record is gone. Empty = always.
  • Before a change: entities also have the actions before_validate (before the values are checked), before_create, before_update (checked, right before saving) and before_delete. Such an event runs right away and the write waits for it: values a step changes in the record (a script: set record.slug = record.title.slug()) are written instead of those sent - after before_create / before_update they are checked again. The step cancel, a script with return fail("…") or any step that fails without a connection from its output error cancels the change: saving answers 422 (event_cancelled) with the message. The condition sees the record as it would be (sent fields over the stored ones), {{old.…}} the stored one. These events run for the admin app, the content API and the steps of events - not for imports. They cannot be mixed with the other actions and never run in the queue; their runs are shown like the others.
  • When read: the action after_find runs when the content API answers with records (lists, trees, one record, the answer of a write - previews too). Its steps change the values of the answer, the stored records stay as they are: a script (set record.price_text = record.price.formatNumber(2, ",", ".") + " €") adds or changes values for the records its condition matches. Only steps that neither write nor send are allowed - condition, find and steps of plugins - as they run on every read. No runs are saved; a step that fails leaves the records as they are. The content cache keeps the changed answer and is emptied when such an event changes.
  • Steps as a flow (steps: {"nodes": [...], "edges": [...]}): a start node and step nodes, connected from an output of one node to another node. Every step has the outputs out (done) and error (it failed); a condition has yes and no instead of out. Several connections from one output: every branch runs. A flow has no circles. A list of steps (as before, and as the API, plugins and the AI may still send them) is a chain: start → 1 → 2 …
    • cancel {message}: stops the run with the message (placeholders filled in) - in events before a change, the change too. Best behind a condition.
    • Every step may have a description (at most 300 characters): what it does in words, shown in the overview and on the canvas instead of its settings.
    • condition {condition}: a filter like the condition of the event, on the record and the values of earlier steps - the records that match go on along yes, the others along no.
    • webhook {url, secret?, digest?, auth?}: one POST with all records of the run (digest, the default) or one per record. The payload has the project, the event, the entity (slug, name, fields) and the records with their data and their state before. It is signed with X-Excellent-Signature: sha256=<HMAC> when a secret is set, and the URL may use placeholders. auth protects the receiver: {"type": "bearer", "token": "…"} sends Authorization: Bearer …, and {"type": "basic", "username": "…", "password": "…"} is basic auth, for example an .htaccess login.
    • email {to, subject, body, digest?}: one mail per record, or one for all with digest.
  • Secrets from the .env: the secret, the token and the basic auth fields take a value or a reference $SHOP_TOKEN to a variable of the .env. The URL takes $SHOP_TOKEN anywhere in it, for example https://shop.example.com/hook?token=$SHOP_TOKEN. The name ends at the first character that is no letter, digit or _. The value is URL-encoded and resolved before the record placeholders, so a $NAME inside a record value stays text. It is resolved only when the step runs, so the value is never stored. $$abc is the value $abc. Unknown or empty variables are refused when saving. The core secrets (JWT_SECRET, APP_ENCRYPTION_KEY, DB_*, CRON_KEY, MAILER_DSN) are never resolved; every other variable can be used, so treat event permissions like access to the .env. Events are for administrators only. In the admin app, typing $ suggests the variables (GET /api/v1/admin/env-vars returns their names and whether they are set, never their values). The service behind it (EnvVariables) is meant for every setting that needs secrets.
    • create {entity, data}, update {entity, where, data}, delete {entity, where}: per record; where is a filter.
    • find {entity, where, as, all?}: per record of the run, the first record of entity that matches where (drafts too, every field). The next steps get it as {{<as>.<field>}}, e.g. with "as": "author" and "where": {"user": "{{record.created_by}}"} the name of the author is {{author.name}}. Nothing found: empty. With "all": true it is a list of at most 100 ({{authors[0].name}}), e.g. for each in a script. It only reads.
    • ai {input, as, agent?, fields?}: asks an AI agent with input (placeholders filled in) - the answer as {{<as>}} or, with fields, {{<as>.<field>}} for the next steps. See AI.
    • log {message, level?, log?}: an entry per record in a log of the project (Log in the admin app), with the event, run and record. level: info (default), warning, error; log: cms (default) or a name of its own (trailer) - a log exists as soon as it has an entry. Placeholders are filled in, $NAME of the .env is not (no secrets in logs). Scripts write with log(message, level?, log?). Entries older than LOG_DAYS days (default 30) are removed by the cleanup; GET /api/v1/admin/logs lists the logs, GET …/logs/{log}?level=&q=&page= their entries, DELETE …/logs/{log} clears one.
    • event {event, data?}: starts an event of the source event (Started by other events) with the records of this run. data adds values to each of them, with placeholders, e.g. {"note": "from {{event.name}}"} - in the started event they are {{record.note}} next to the fields of the record. Its condition is checked on that, and it runs one level deeper in the chain.
  • Values of earlier steps: steps of plugins can pass values on to the steps after them, e.g. the step Modify values of the plugin script: set record.short = record.name.split().first().uppercase() makes {{record.short}}, set names = record.name.split() makes {{names[0]}}, {{names[1]}}. Items of lists are written {{names[0]}} or {{names.0}}.
  • Lookups: for just the id, without a step of its own: a value {"_lookup": {"entity": "authors", "where": {"user": "{{record.created_by}}"}}} in data or where is the id of the first record that matches the filter (null: none). With "all": true it is the list of the ids of all matches, e.g. for a repeatable reference. Example: Blog with author profiles.
  • Placeholders: {{record.title}}, {{record.image.url}}, {{record.created_by}} / {{record.updated_by}} (user:<id> or client:<id>), {{old.price}}, {{event.name}}, {{event.action}}, {{project.url}} or {{url}} (project variables), {{count}}. A value that is only a placeholder keeps its type (number, list, object). In a webhook URL, record values are URL-encoded. In the where of an update or delete step, a placeholder that comes out empty stops the step instead of matching every record with an empty field.
  • One run per request: everything an event collects in one request is one run. An import of 100 rows is one webhook call with 100 records.
  • Direct or queue: direct runs start after the answer went out. Queue runs wait for the worker (./yii queue:run events, see Deployment).
  • Progress: every run shows its status and the progress of each step (e.g. create 37/100). A failing step with a connection from its error output is handled: the records go on that way with the message as {{error}}, and the run counts as done. Without one its branch stops and the run fails - unless it has Continue if this step fails ("continue_on_error": true): then the next steps run anyway and the run counts as failed. Retry starts it again and skips the steps that are done. The newest 100 runs per event are kept.
  • Chains: steps that write records start the events of those entities, one level deeper, at most 3 levels, and an event never starts itself again in its own chain. The admin app shows them as workflow.
  • Events as building blocks: an event with the source event has no trigger of its own - it runs only when the step event of another event starts it. Steps that several events share (notify the team, sync with a shop …) are kept in one place this way. The step fails if the event is switched off, already runs in this chain (a loop) or the chain is 3 levels deep. Its test run takes the values as JSON, e.g. {"title": "Test"}.
  • Changes made by steps are saved as event:<id> (shown as Event: name), entity permissions do not apply. Failed requests start nothing.
  • Editing: an event has a page of its own in the admin app (Events › New, or a click on an event). Its steps are a canvas: drag a step from the palette (or click it: it is added after the chosen step), connect an output (right, error at the bottom in red) to the input of a step (left), click a step for its form. Delete removes the chosen step or connection; JSON shows the whole flow. Keys the form does not know stay.
  • Test run: for one record, whether the condition matches and what the steps would do. Nothing is sent or saved.
GET/POST        /api/v1/admin/events             PUT/DELETE /api/v1/admin/events/{id}
GET             /api/v1/admin/events/{id}/runs   POST /api/v1/admin/events/{id}/test {"record": "<id>"}
POST            /api/v1/admin/event-runs/{id}/retry