Defines a recurring action entity with its configuration schema.
every is not a timeout: nothing is timing out. It is a recurring action
that runs on an interval for as long as a record sits in its step. Firing
never leaves the step — there is no transition_to — so every always
requires an action.
Storage
AshWorkflow.Transformers.AddAttributes adds one nilable
:utc_datetime_usec attribute per every, holding the instant it last
fired. Its interval is measured against that column, not against
state_entered_at, so two every entities on the same step — and any
timeout sharing the step — no longer share one anchor that one firing
resets out from under the others.
Named <step>_<every>_last_fired_at by default, or explicitly with
last_fired_field:
every :reminder do
interval {1, :hours}
action :send_reminder
last_fired_field :reminder_last_fired_at
endNot field — AshWorkflow.Entities.Timeout's field names an anchor
AshWorkflow reads and never writes. last_fired_field names a column
AshWorkflow owns and writes on every fire. Reusing the name would give it
two opposite meanings.
A record whose column is still nil has never fired this every, and the
interval is then measured from state_entered_at, so the first firing lands
one whole interval after the record entered the step rather than on entry.
Both the generated Oban trigger and
AshWorkflow.Scheduler.Precise.Timeline apply that fallback.
Bounding an every with until
every alone fires forever. until stops it after a fixed amount of
wall-clock time since the record entered the step:
every :reminder do
interval {2, :days}
action :send_review_reminder
until {8, :days}
enduntil is measured against state_entered_at directly. An every's own
firing writes its last_fired_field, not state_entered_at, so
state_entered_at stays put for as long as the record occupies the step —
nothing moves the anchor until measures against. See
AshWorkflow.Verifiers.ValidateEvery for why until must be strictly
longer than interval.
Reaching the bound only stops the firing. It does not transition state —
compose a second, ordinary timeout with a fire_after equal to the bound
for "give up and move on".
Bounding an every with max_fires
max_fires stops it after a number of fires in the current step visit:
every :reminder do
interval {2, :days}
action :send_review_reminder
max_fires 3
endSpacing fires out with backoff
backoff grows the gap between fires. The first fire still lands one
interval after entry. After fire n, the next lands interval plus
AshWorkflow.Entities.Retry.delay_ms/2 for attempt n later, so a fixed
duration adds the same delay to every later gap and :exponential adds
Oban's n^4 + 15 seconds.
Both options add a <step>_<every>_fires integer column holding the fires
in the current step visit. A fire recorded before state_entered_at belongs
to an earlier visit, so the count restarts on re-entry.
Summary
Functions
The integer attribute counting this every's fires in the current step
visit, <step_name>_<every_name>_fires, or nil when the every declares
neither max_fires nor backoff and so needs no count.
The gap in milliseconds between fire number fires and the next one.
The attribute this every writes its last-fired instant to, and measures
interval against: last_fired_field if given, otherwise
<step_name>_<every_name>_last_fired_at.
The instant this every is next due, given the record's last-fired instant,
its fire count and its state_entered_at.
Types
@type duration_unit() :: AshWorkflow.Duration.unit()
@type t() :: %AshWorkflow.Entities.Every{ __spark_metadata__: term(), action: atom(), backoff: AshWorkflow.Entities.Retry.backoff() | nil, check_interval: String.t() | nil, emits: [AshWorkflow.Entities.Emit.t()], interval: {pos_integer(), duration_unit()}, last_fired_field: atom() | nil, max_fires: pos_integer() | nil, name: atom(), retry: AshWorkflow.Entities.Retry.t() | nil, self_scheduled?: boolean(), until: AshWorkflow.Duration.t() | nil }
Functions
The integer attribute counting this every's fires in the current step
visit, <step_name>_<every_name>_fires, or nil when the every declares
neither max_fires nor backoff and so needs no count.
@spec gap_ms( AshWorkflow.Duration.t(), AshWorkflow.Entities.Retry.backoff() | nil, non_neg_integer() ) :: non_neg_integer()
The gap in milliseconds between fire number fires and the next one.
fires of 0 is the gap from step entry to the first fire, which is
interval whatever the backoff.
The attribute this every writes its last-fired instant to, and measures
interval against: last_fired_field if given, otherwise
<step_name>_<every_name>_last_fired_at.
@spec next_due_at( AshWorkflow.Duration.t(), AshWorkflow.Entities.Retry.backoff() | nil, DateTime.t() | nil, non_neg_integer() | nil, DateTime.t() ) :: DateTime.t()
The instant this every is next due, given the record's last-fired instant,
its fire count and its state_entered_at.
A nil last fire measures interval from state_entered_at. A last fire
from an earlier step visit counts as zero fires in this one.