# `AshWorkflow.Changes.RecordEvent`
[🔗](https://github.com/team-alembic/ash_workflow/blob/v0.12.0/lib/ash_workflow/changes/record_event.ex#L1)

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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
