A workflow can emit Ash.Signals signals when its records move between steps. Other resources listen to those signals in their own signals_in section, so a reaction to an approval lives with the resource that reacts, and the workflow resource does not change when a reaction is added.
Naming a signals module
The signals option on the workflow section names an application-owned module that uses Ash.Signals. Every emit in the workflow names a signal declared there, and AshWorkflow.Verifiers.ValidateSignals rejects a name the module does not declare.
defmodule MyApp.Documents.Signals do
use Ash.Signals
signals do
signal :document_moved do
argument :id, :uuid, allow_nil?: false
argument :from_state, :atom
argument :to_state, :atom, allow_nil?: false
argument :triggered_by, :atom, allow_nil?: false
end
signal :review_started do
argument :id, :uuid, allow_nil?: false
argument :title, :string
end
signal :review_finished do
argument :id, :uuid, allow_nil?: false
argument :to_state, :atom, allow_nil?: false
end
signal :document_approved do
argument :id, :uuid, allow_nil?: false
argument :approver_id, :uuid
argument :outcome, :string
end
signal :review_overdue do
argument :id, :uuid, allow_nil?: false
end
end
endWhere emit goes
emit works at four levels. A signal must declare the :after_action phase, which is the Ash.Signals default.
workflow do
signals MyApp.Documents.Signals
# every state change, including the initial create
emit :document_moved
step :review do
# entering the step, or with `on: :exit`, leaving it
emit :review_started
emit :review_finished, on: :exit
# one transition
transition :approve do
to :published
emit :document_approved, fields: [approver_id: :reviewer_id], values: [outcome: "approved"]
end
transition :reject, to: :draft
# a timeout's or an every's own firing
timeout :overdue do
fire_after {3, :days}
action :send_overdue_notice
emit :review_overdue
end
end
step :published, terminal: true
step :draft, terminal: true
endA workflow-level emit fires on every state change, including the initial create, where from_state is nil. A step-level emit fires when a state change enters the step, or leaves it with on: :exit. An emit inside a transition fires when that transition runs from that step. An emit inside a timeout or an every fires when it does. An action timeout and an every firing do not change state, so they emit only their own signals, and no workflow-level or step-level signal.
A transition, timeout or every that contains an emit takes its other options inside the do block, as transition :approve does above.
Payloads
AshWorkflow.Changes.RecordEvent builds each payload from the fields the signal declares, and leaves out every other field. It fills them in this order, and a later source replaces an earlier one:
- The workflow fields
from_state,to_state,transition_name,triggered_byandoccurred_at.transition_nameandtriggered_byhold the same values as the transition log row. - Any signal field with the same name as an attribute of the resource, read from the record after the action.
fields, a keyword list ofsignal_field: :attributepairs, or a list of attribute names that keep their names.values, a keyword list of literal values.
Listening
Listening needs nothing from AshWorkflow. A transition action is an ordinary update action, so a workflow resource can list one in its signals_in section and move its records when another resource emits a signal. Under the default inline delivery, a listener whose record is not in one of the transition's from states fails, and that failure rolls back the action that emitted the signal. on_signal, below, selects only records in the step, so it avoids that failure.
Receiving signals
on_signal on a step moves a record on, or runs an update action, when a signal selects that record while it is in the step. It sits beside the step's transitions and timeouts, and whichever exit fires first wins:
workflow do
signals MyApp.Payments.Signals
step :awaiting_payment do
transition :mark_paid, to: :fulfilling
on_signal :payment_settled do
filter expr(id == ^signal(:order_id))
transition_to :fulfilling
inputs paid_at: :settled_at
end
on_signal :address_changed do
filter expr(id == ^signal(:order_id))
action :update_address
inputs [:address]
end
timeout :expire do
fire_after {3, :days}
transition_to :cancelled
end
end
step :fulfilling, terminal: true
step :cancelled, terminal: true
end| Option | Meaning |
|---|---|
| name (positional) | The signal. |
from | The Ash.Signals module that declares the signal. Defaults to the workflow's signals module. |
filter | An expression that selects the records, with ^signal(:field) for a field of the signal. |
read_action | A read action of the resource that selects the records instead of filter. Its arguments are set from signal fields of the same name. |
transition_to | The step to move to. |
action | An update action to run without leaving the step. |
inputs | Action inputs taken from signal fields, as input: :signal_field. |
delivery | How the signal reaches the handler, passed to the signals_in listener unchanged. |
Exactly one of filter and read_action is required, and exactly one of transition_to and action. AshWorkflow.Verifiers.ValidateOnSignal checks that the signal exists, that each ^signal(:field) names one of its fields, and that action names an update action.
A filter is an ordinary read filter, so it can follow a relationship, as in expr(customer.email == ^signal(:email)), or use exists/2. A filter that matches several records in the step moves all of them, so one :batch_cancelled signal can cancel every order in a batch.
AshWorkflow generates a read action :__signal_<step>_<signal>_read that adds the step to the selection, and a signals_in listener named :<step>_<signal> that runs the handler. With transition_to it also generates the update action :__signal_<step>_<signal>, whose log row has triggered_by: :signal and the signal's name as transition_name. With action, the named action records the event and leaves state_entered_at alone. A timeout or every cannot name the same action as an on_signal, since each would record its own event.
A signal for a record that is not in the step selects nothing and is ignored. That covers a record that a person or a timeout has already moved on. It also covers a record that has not reached the step yet, so a signal emitted before the record enters the step is lost.
With Ash.Policy.Authorizer, the generated read and transition actions are authorized by signal_in/2 for the handler's signal. The listener can then move a record that the emitting actor could not move directly. The action variant runs your own update action and gets no generated policy, so that action's own policies must allow the listener.
Under the default inline delivery, the handler runs inside the emitting action. A transition that fails, for example on a validation, fails the emitting action and rolls it back.
Limits
- Only
:after_actionsignals are emitted. A signal that declares another phase is rejected byAshWorkflow.Verifiers.ValidateSignals. - A bulk action emits one signal per record.
AshWorkflow.Changes.RecordEventdoes not batch them. AshWorkflow.Scheduler.ObanandAshWorkflow.Scheduler.Preciserun automatic steps, timeouts andeveryfirings with anilactor, and listeners run as the emitting action's actor. A listener's policies must allow anilactor for those signals.- A step's
on: :exitemit and the emits inside atransition,timeoutoreveryneed the state the record left. An atomic update has no loaded record, soAshWorkflow.Changes.RecordEventuses the transition's singlefromstate, or the last transition log row. An atomic update of an action with severalfromstates on a workflow without atransition_logdoes not know that state, and those emits do not fire. - A listener that fails under inline delivery fails the action that emitted the signal, and the transaction rolls back.