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
end

Where 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
end

A 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:

  1. The workflow fields from_state, to_state, transition_name, triggered_by and occurred_at. transition_name and triggered_by hold the same values as the transition log row.
  2. Any signal field with the same name as an attribute of the resource, read from the record after the action.
  3. fields, a keyword list of signal_field: :attribute pairs, or a list of attribute names that keep their names.
  4. 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
OptionMeaning
name (positional)The signal.
fromThe Ash.Signals module that declares the signal. Defaults to the workflow's signals module.
filterAn expression that selects the records, with ^signal(:field) for a field of the signal.
read_actionA read action of the resource that selects the records instead of filter. Its arguments are set from signal fields of the same name.
transition_toThe step to move to.
actionAn update action to run without leaving the step.
inputsAction inputs taken from signal fields, as input: :signal_field.
deliveryHow 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_action signals are emitted. A signal that declares another phase is rejected by AshWorkflow.Verifiers.ValidateSignals.
  • A bulk action emits one signal per record. AshWorkflow.Changes.RecordEvent does not batch them.
  • AshWorkflow.Scheduler.Oban and AshWorkflow.Scheduler.Precise run automatic steps, timeouts and every firings with a nil actor, and listeners run as the emitting action's actor. A listener's policies must allow a nil actor for those signals.
  • A step's on: :exit emit and the emits inside a transition, timeout or every need the state the record left. An atomic update has no loaded record, so AshWorkflow.Changes.RecordEvent uses the transition's single from state, or the last transition log row. An atomic update of an action with several from states on a workflow without a transition_log does 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.