Records a workflow event: writes through state_entered_at and, if a
transition_log is configured, appends one row describing what happened.
Replaces the five copy-pasted set_attribute(:state_entered_at, ...) call
sites AshWorkflow.Transformers.AddActions used to inject — one per kind of
workflow event — plus the resource-global :initial row on create. The
change is always injected regardless of whether logging is configured; the
log append is a single conditional at the leaf, not a fork in the
transformer.
Options
:triggered_by(required) — one of:initial,:manual,:automatic,:timeout,:error_path,:undo,:signal.:touch_state_entered_at(optional, defaults totrue) — whether the change writesstate_entered_at. A timeout must not reset it, because every other deadline on the step measuresafterfrom the same attribute, so moving it would push a pendingtransition_totimeout out of reach. Anevery's own firing does not reset it either — see:every_fieldbelow — so this istrueonly for a genuine step entry: a manual transition, an automatic step completion, a transition timeout, an undo and the initial create.:every_field(optional, defaults tonil) — the attribute anevery's firing writes its last-fired instant to, named byAshWorkflow.Entities.Every.last_fired_field/2. Set only on the changeAshWorkflow.Transformers.AddActionsinjects into anevery's action, this is how that firing re-arms its own trigger for the next interval without touchingstate_entered_at, which every other deadline on the step measures from.:every_fires_field(optional, defaults tonil) — the integer attribute counting theevery's fires in the current step visit, named byAshWorkflow.Entities.Every.fires_field/2. Incremented on each fire, and restarted at 1 when:every_fieldholds a fire from beforestate_entered_at, which belongs to an earlier visit.:timeout_fields(optional, defaults to%{}) — the columns an action timeout's firing writes, as a map from step name to theAshWorkflow.Entities.Timeout.fired_field/2columns of that step's timeouts that run this action. Only the current step's columns are written. Set only on the changeAshWorkflow.Transformers.AddActionsinjects into an action timeout's action. An action timeout does not change state, so this write is what stops it matching again. SeeAshWorkflow.Scheduler.Work.not_fired/1for the guard that reads it.:transition_name(optional) — the name recorded on the log row. Defaults tochangeset.action.name, which is enough for most sites, but several of the actionsAddActionsgenerates use an internal hidden name (e.g.__on_error_process) that would be confusing in history, so those sites pass a human-facing name explicitly. An undo takes the name of the row it reverses, so the pair reads as one decision and its reversal rather than as two unrelated events.:emits(optional, defaults to[]) — the workflow signals this change may emit, set byAshWorkflow.Transformers.AddActionswhen the workflow names asignalsmodule. Each entry is a map with:signal,:fields,:valuesand:when, where:whenis:state_change,{:enter, step},{:exit, step},{:from, step}or:always.
Undo
AshWorkflow.Changes.UndoTransition puts the row being reversed into the
changeset context, and this change writes its primary key to the log's
undoes foreign key. That pointer is what makes an undo additive: the
reversed row is left exactly as written, and both readings of history stay
derivable from the same rows — see AshWorkflow.TransitionLog.effective/1.
Telemetry
This change is also where the [:ash_workflow, :transition] span is emitted,
for the same reason it is where the log row is written: it runs on every
action AshWorkflow generates, so one place covers a manual transition, an
automatic step, a timeout, an error path, an undo and the initial create. See
AshWorkflow.Telemetry for the events and their metadata.
Signals
When the workflow names a signals module, this change emits the :emits
entries that match the event with Ash.Signals.emit/5, in the same
after_action hook as the log append. A listener error fails the action and
rolls it back. On an atomic update of an action with several from states
and no transition log, the from state is unknown, so on: :exit,
transition, timeout and every emits do not fire.
Telling the scheduler
Entering a step is when the deadlines ahead of a record become known, so this
change also calls AshWorkflow.Scheduler.notify_state_change/2. A scheduler
that arms timers needs that call to be precise. A scheduler that polls uses
it to run an automatic step as soon as a record enters it. A step's action
that routes the record back into the same step does not count as entering
it, so a polling scheduler leaves that record for its next poll.
It runs in the same after_action hook as the log append and the span's stop
event, which means it runs after the data layer has committed the new state.
A timer armed before the commit could fire against a record still holding the
old state.
Upserts
A create action that upserts onto an existing row leaves that row in the
step it was in. This change writes no log row for it, emits no signal and
does not call AshWorkflow.Scheduler.notify_state_change/2. The telemetry
span still opens and closes, because its :start event fires before the
data layer reports whether the row was inserted.
Atomicity
This change implements atomic/3 rather than falling back to
require_atomic? false. state_entered_at is set with the now() Ash
expression so it stays part of the atomic update, and the log append is
attached as an after_action hook either way — hooks run after the data
layer action completes whether or not the attribute update itself was
atomic, so there is nothing about appending the log row that requires
opting out of atomicity. This is the "try atomic first" route the design
doc calls out as the likeliest source of bugs; see
test/ash_workflow/changes/record_event_test.exs for the direct atomicity
test it asks for.