AshWorkflow.Changes.RecordEvent (AshWorkflow v0.12.0)

Copy Markdown View Source

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 to true) — whether the change writes state_entered_at. A timeout must not reset it, because every other deadline on the step measures after from the same attribute, so moving it would push a pending transition_to timeout out of reach. An every's own firing does not reset it either — see :every_field below — so this is true only 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 to nil) — the attribute an every's firing writes its last-fired instant to, named by AshWorkflow.Entities.Every.last_fired_field/2. Set only on the change AshWorkflow.Transformers.AddActions injects into an every's action, this is how that firing re-arms its own trigger for the next interval without touching state_entered_at, which every other deadline on the step measures from.
  • :every_fires_field (optional, defaults to nil) — the integer attribute counting the every's fires in the current step visit, named by AshWorkflow.Entities.Every.fires_field/2. Incremented on each fire, and restarted at 1 when :every_field holds a fire from before state_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 the AshWorkflow.Entities.Timeout.fired_field/2 columns of that step's timeouts that run this action. Only the current step's columns are written. Set only on the change AshWorkflow.Transformers.AddActions injects into an action timeout's action. An action timeout does not change state, so this write is what stops it matching again. See AshWorkflow.Scheduler.Work.not_fired/1 for the guard that reads it.
  • :transition_name (optional) — the name recorded on the log row. Defaults to changeset.action.name, which is enough for most sites, but several of the actions AddActions generates 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 by AshWorkflow.Transformers.AddActions when the workflow names a signals module. Each entry is a map with :signal, :fields, :values and :when, where :when is :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.