mix ash_workflow.gen.approval adds an approval workflow to a resource. A request is opened against a record, one or more approvers approve or reject it, and the request can be marked overdue when nobody decides in time.

The command

mix ash_workflow.gen.approval MyApp.Expenses.Expense \
  --approver MyApp.Accounts.User \
  --required-approvals 1 \
  --overdue-after 2d
OptionDefaultEffect
--approverrequiredThe actor resource. Decisions and the requester belong to it.
--module<Subject>ApprovalName of the generated approval resource.
--domainnoneDomain for a subject the task creates. Required when the subject does not exist, and ignored when it does: the approval resources then join the subject's domain.
--required-approvals1Number of approvals a request needs. Each request stores the count, and the :request action does not accept it, so a requester cannot lower their own quorum.
--overdue-afternoneMoves a waiting request to :overdue after this long. Accepts 30m, 12h, 2d and 2w. A duration under a minute needs AshWorkflow.Scheduler.Precise. Without it, no :overdue step is generated.
--transition-logtrueAlso runs mix ash_workflow.gen.transition_log for the approval resource, recording the approver as the actor. Pass --no-transition-log to skip it.

When the subject does not exist, the task creates it with mix ash.gen.resource, using the approver's data layer, or else the data layer of the first ETS or Postgres resource in --domain. When neither the approver nor any resource there uses ETS or Postgres, the task stops with an issue and writes nothing. Create the subject resource first, or pass a --domain that has one. Running the task again on the same subject changes nothing.

What it generates

For the command above, the task writes six modules, edits the subject and adds the three new resources to the subject's domain. With --no-transition-log it writes five modules and adds two resources.

  • MyApp.Expenses.ExpenseApproval runs the workflow. It belongs to the expense and to the user who requested it. Each foreign key takes the type of the primary key it points at. The task reports an issue for a subject or approver with a composite primary key.
  • MyApp.Expenses.ExpenseApprovalDecision holds one row for each approval or rejection. An identity stops an approver deciding the same request twice.
  • MyApp.Expenses.ExpenseApproval.Changes.RecordDecision writes the decision row when :approve or :reject runs.
  • MyApp.Expenses.ExpenseApproval.Checks.CanRequest decides who may open a request on a subject. It denies everyone as generated.
  • MyApp.Expenses.ExpenseApproval.Checks.CanApprove decides who may approve. It denies everyone as generated.
  • MyApp.Expenses.ExpenseApprovalTransition logs each transition of the approval with the user who made it. mix ash_workflow.gen.transition_log writes it.
  • MyApp.Expenses.Expense gains has_many :approvals, has_one :latest_approval and an approved? calculation. The task adds no change, argument or policy to the subject's actions.

The approval is a separate resource rather than a workflow block on the subject. A subject that already runs a workflow keeps it, and a rejected expense that is submitted again gets a new approval row. The old row keeps the rejection and who made it.

The workflow

stateDiagram-v2
  [*] --> pending
  pending --> pending: approve (quorum not met)
  pending --> approved: approve (quorum met)
  pending --> rejected: reject
  pending --> cancelled: cancel
  pending --> overdue: overdue_after passes
  overdue --> overdue: approve (quorum not met)
  overdue --> approved: approve (quorum met)
  overdue --> rejected: reject
  overdue --> cancelled: cancel
workflow do
  step :pending do
    transition :approve do
      route :approved, when: expr(approvals_remaining <= 1)
      route :pending, when: expr(approvals_remaining > 1)
    end

    transition :reject, to: :rejected
    transition :cancel, to: :cancelled

    timeout :overdue, fire_after: {2, :days}, field: :requested_at, transition_to: :overdue
  end

  step :overdue do
    transition :approve do
      route :approved, when: expr(approvals_remaining <= 1)
      route :overdue, when: expr(approvals_remaining > 1)
    end

    transition :reject, to: :rejected
    transition :cancel, to: :cancelled
  end

  step :approved, terminal: true
  step :rejected, terminal: true
  step :cancelled, terminal: true
end

approvals_remaining is required_approvals minus the number of approving decisions. Routes read it before the current call's decision is written, so <= 1 means this call is the last approval needed. One rejection rejects the request.

The overdue deadline is measured from requested_at, which the :request action sets once. A partial approval loops the request back into its step and moves state_entered_at, so a deadline measured from state_entered_at would restart with every approval.

:overdue is a step, not a flag. An overdue request can still be approved, rejected or cancelled, and a query can filter on state == :overdue. Add a timeout or every to the :overdue step for reminders or escalation.

The policies

policies do
  policy action(:request) do
    authorize_if MyApp.Expenses.ExpenseApproval.Checks.CanRequest
  end

  policy action([:approve, :reject]) do
    forbid_if expr(requested_by_id == ^actor(:id))
    forbid_if expr(exists(decisions, approver_id == ^actor(:id)))
    authorize_if MyApp.Expenses.ExpenseApproval.Checks.CanApprove
  end

  policy action(:cancel) do
    authorize_if relates_to_actor_via(:requested_by)
  end
end

Only an actor that CanRequest permits can open a request. The requester cannot decide their own request, and an approver cannot decide twice. Only the requester can cancel. The generated :available_actions calculation applies these policies, so loading it with an actor tells a UI whether that user can approve.

Reads stay open by default. AshWorkflow authorizes :read on the approval resource for every actor, and the decision resource's only policy allows every read. Add a read policy to each if requests or decisions are private.

What your application does next

Decide who may open a request

CanRequest denies everyone, so no request can be opened until you change it. Replace its match?/3, or replace the authorize_if line in the :request policy with a built-in check. The :request action is a create, so a check that reads the subject finds its id in context.changeset:

# Any employee may request approval
authorize_if actor_attribute_equals(:role, :employee)

Decide who may approve

CanApprove denies everyone, so nothing can be approved until you change it. Replace its match?/3, or replace the authorize_if line in the approval's policy with a built-in check:

# The expense owner's manager approves
authorize_if relates_to_actor_via([:subject, :owner, :manager])

# Any finance manager approves
authorize_if actor_attribute_equals(:role, :finance_manager)

Open a request

Call request/2 wherever a request should start, such as a submit action or a LiveView event. The actor becomes the requester:

MyApp.Expenses.ExpenseApproval.request(expense.id, actor: current_user)

The :request action accepts only subject_id. A quorum that varies by request belongs in a change on :request that sets required_approvals from the subject, such as the expense amount, rather than from caller input.

Approve, reject or cancel

MyApp.Expenses.ExpenseApproval.approve(approval, %{comment: "Within budget"}, actor: approver)
MyApp.Expenses.ExpenseApproval.reject(approval, %{comment: "Missing receipt"}, actor: approver)
MyApp.Expenses.ExpenseApproval.cancel(approval, actor: current_user)

Use the outcome

approved? on the subject is true when its latest approval is approved, and false otherwise, including for a subject with no approval. Gating a subject action on it is up to you, for example with a policy on the subject:

policy action(:reimburse) do
  authorize_if expr(approved?)
end

Generate the migrations

On AshPostgres, run mix ash.codegen add_expense_approval to create the approval, decision and transition log tables.

Limits

On AshPostgres, :approve and :reject start with change get_and_lock_for_update(). The lock re-reads the approval row with SELECT ... FOR UPDATE before the route reads approvals_remaining, so a second approval of the same request waits until the first commits and then counts its decision.

Other data layers take no lock. On them, two approvals that arrive at the same moment can both read the count before either decision row is written, and both loop back to the current step. The request then holds enough approvals but is still waiting, and the decide-once policy stops either approver trying again. Serialise approvals of one request if your approvers are likely to decide together.