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
| Option | Default | Effect |
|---|---|---|
--approver | required | The actor resource. Decisions and the requester belong to it. |
--module | <Subject>Approval | Name of the generated approval resource. |
--domain | none | Domain 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-approvals | 1 | Number 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-after | none | Moves 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-log | true | Also 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.ExpenseApprovalruns 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.ExpenseApprovalDecisionholds one row for each approval or rejection. An identity stops an approver deciding the same request twice.MyApp.Expenses.ExpenseApproval.Changes.RecordDecisionwrites the decision row when:approveor:rejectruns.MyApp.Expenses.ExpenseApproval.Checks.CanRequestdecides who may open a request on a subject. It denies everyone as generated.MyApp.Expenses.ExpenseApproval.Checks.CanApprovedecides who may approve. It denies everyone as generated.MyApp.Expenses.ExpenseApprovalTransitionlogs each transition of the approval with the user who made it.mix ash_workflow.gen.transition_logwrites it.MyApp.Expenses.Expensegainshas_many :approvals,has_one :latest_approvaland anapproved?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: cancelworkflow 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
endapprovals_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
endOnly 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?)
endGenerate 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.