Schedules and other triggers

Schedules, credits running low, a run starting and record changes.

Schedules

{ "kind": "schedule", "every": "1d", "at": "09:00" }. every is one of 15m, 30m, 1h, 6h, 12h, 1d or 1w, so no schedule runs more often than every fifteen minutes. at is a UTC time (00:00 when unset) and pairs with 1d or 1w; 1w also needs on, the weekday, in lowercase ("monday" to "sunday"). A weekly digest is one relay: { "kind": "schedule", "every": "1w", "on": "monday", "at": "09:00" }.

A schedule ticks once per period. A relay created mid-period first fires next period. After a gap, the most recent missed period runs late, and older missed periods land as dead events you can replay.

A schedule has no person, so grant_access, revoke_access, email_person and to: "person" are refused on it when the file is validated.

Credits running low

{ "kind": "credits_low", "below": 20 }. It runs once each time a person's spendable credits fall from below or more to under it: a spend, a refund's clawback, an expiry, or a reservation for a run. It never runs on a rise, so a person who tops up and runs low again triggers it again. below is a whole number from 1 to 1,000,000,000. It records one event per crossing per relay.

The person is the event's person, so email_person and grant_credits have someone to act on. The payload's event is { balance, before, below }, read in templates as {{event.balance}}.

A grant_credits action on this trigger refills the person. This repeats every time the person runs low.

A run starting

{ "kind": "run_started", "tool": "poster" }. It runs once when a person starts a run on any tool (every one, or the one tool names), whatever its provider. It reacts to the run and takes no part in delivering it. The person is the run's person, so email_person has someone to write to. The payload's event carries the run, read in templates as {{event.run.id}} and {{event.run.tool}}. It records one event per run per relay, ever.

Person actions work on it: an email_person notice, or start_run to chain the next tool for the same person. A tool on provider external sends its own run to your pipeline without a relay (see External tools), so this trigger needs no action beside it.

Record changes

{ "kind": "data_change", "collection": "bookings", "on": ["created"], "where": { "status": "won" } }. on is any of created, updated and deleted. where filters the record's own data fields: per field, a literal (an exact match) or an object of operators, the list's own filter grammar (see Data).

published filters on whether the record is public after the write: "published": false fires only for drafts (on a collection whose posts wait for approval, a post that is waiting for you), "published": true only once the record is public. Leave it out to hear both. It is a separate key, not part of where, because published is not one of the record's data fields. { "kind": "data_change", "collection": "posts", "on": ["created", "updated"], "published": false } tells you each time a post starts waiting. Any value other than true or false is refused when the relay is saved.

openField names one of the collection's open fields (a like, a vote, an acknowledgement) and fires only when a reader changes that field; it needs updated in on. direction narrows it to "added", "taken back" or "set". A trigger with openField never fires on content edits, and one without it never fires on open-field changes.

It fires for writes from your app, from the dashboard's editor and from Stripe receipts, at most once per write per relay. It never fires for a relay's own writes, and never for an account erasure, so an erased person's data never fans out. A call_url that writes back through the SDK does fire it, so avoid a loop through your own host. A definition change applies within five seconds. The person is the record's owner, otherwise its recipient.