mix ash_workflow.gen.verification adds a verification workflow to a resource. Each verification runs a :verify action you fill in, such as a call to an identity provider, and moves to :verified or :rejected on the outcome that action writes. A verification whose :verify fails on every attempt moves to :needs_review, where a person approves or rejects it.

The command

mix ash_workflow.gen.verification MyApp.Accounts.IdentityDocument --max-attempts 5
OptionDefaultEffect
--module<Subject>VerificationName of the generated verification resource.
--domainthe subject's domainDomain for a subject the task creates. Required only when the subject does not exist.
--max-attempts3Attempts :verify gets before the verification moves to :needs_review. With 1, no retry block is generated.
--transition-logtrueAlso runs mix ash_workflow.gen.transition_log for the verification resource. Pass --no-transition-log to skip it.

When the subject does not exist, the task creates it with mix ash.gen.resource, using the data layer of the first ETS or Postgres resource in --domain. When no 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 three modules and edits the subject:

  • MyApp.Accounts.IdentityDocumentVerification runs the workflow. It belongs to the document and holds the provider's outcome, either :passed or :failed.
  • MyApp.Accounts.IdentityDocumentVerification.Checks.CanSubmit decides who may submit a verification. It denies everyone as generated.
  • MyApp.Accounts.IdentityDocumentVerification.Checks.CanReview decides who may approve or reject a verification in review. It denies everyone as generated.
  • MyApp.Accounts.IdentityDocument gains has_many :verifications, has_one :latest_verification and a verified? calculation. The task adds no change, argument or policy to the subject's actions.

A document can be verified many times. A rejected document that is uploaded again gets a new verification, and the old one keeps its rejection.

The workflow

stateDiagram-v2
  [*] --> submitted
  submitted --> verifying: begin
  verifying --> verified: verify, outcome passed
  verifying --> rejected: verify, outcome failed
  verifying --> needs_review: verify fails max_attempts times
  needs_review --> verified: approve
  needs_review --> rejected: reject
workflow do
  step :submitted do
    transition :begin, to: :verifying
  end

  step :verifying do
    action :verify
    on_success :verified, when: expr(outcome == :passed)
    on_success :rejected, when: expr(outcome == :failed)
    on_error :needs_review

    retry do
      max_attempts 5
    end
  end

  step :needs_review do
    transition :approve, to: :verified
    transition :reject, to: :rejected
  end

  step :verified, terminal: true
  step :rejected, terminal: true
end

:verifying is an automatic step. The scheduler runs :verify as soon as a verification enters it, then routes on outcome. A provider that answers :failed rejects the verification directly. That is an outcome, not an error, so it is not retried.

A :verify that returns an error, raises, or writes no outcome is a failure. The scheduler retries it up to --max-attempts times with an exponential backoff, and moves the verification to :needs_review once the last attempt fails.

The workflow has no timeouts. :verifying is bounded by its attempts, and :needs_review waits for a person.

What your application does next

Decide who may submit

CanSubmit denies everyone, so no verification can be submitted until you change it. Replace its match?/3, or replace the authorize_if line in the :submit policy with a built-in check:

policies do
  policy action(:submit) do
    authorize_if actor_attribute_equals(:role, :applicant)
  end
end

Code that submits a verification on the application's behalf, such as an import, can pass authorize?: false instead.

Reads stay open by default. AshWorkflow authorizes :read on the verification resource for every actor. Add a read policy if verifications are private.

Submit and begin a verification

Call submit/1 with the subject, then begin/1 once the provider has what it needs, such as an uploaded file:

verification = MyApp.Accounts.IdentityDocumentVerification.submit!(document.id, actor: current_user)
MyApp.Accounts.IdentityDocumentVerification.begin!(verification)

begin is allowed by the default policy AshWorkflow adds for every transition, and a policy of your own replaces it.

Call your provider

The generated :verify action is empty, so every verification lands in :needs_review until you fill it in. Add a change that calls your provider and writes outcome:

update :verify do
  require_atomic? false
  accept []
  change MyApp.Accounts.Changes.CheckWithProvider
end
defmodule MyApp.Accounts.Changes.CheckWithProvider do
  use Ash.Resource.Change

  @impl true
  def change(changeset, _opts, _context) do
    Ash.Changeset.before_action(changeset, fn changeset ->
      %{subject: document} = Ash.load!(changeset.data, :subject, authorize?: false)

      case MyApp.IdentityProvider.check(document) do
        {:ok, :genuine} -> Ash.Changeset.force_change_attribute(changeset, :outcome, :passed)
        {:ok, :forged} -> Ash.Changeset.force_change_attribute(changeset, :outcome, :failed)
        {:error, reason} -> Ash.Changeset.add_error(changeset, inspect(reason))
      end
    end)
  end
end

Return an error for a provider that is down or times out, so the scheduler retries it.

Decide who may review

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

policies do
  policy action([:approve, :reject]) do
    authorize_if actor_attribute_equals(:role, :compliance_officer)
  end
end

Use the outcome

verified? on the subject is true when its latest verification is in :verified, and false otherwise, including when the subject has no verification. It reads latest_verification only. Submitting a new verification for a verified subject turns verified? false until the new verification reaches :verified. Gating a subject action on it is up to you, for example with a policy on the subject:

policy action(:withdraw) do
  forbid_unless expr(verified?)
  authorize_if always()
end

state is the verdict and outcome is what the provider said. A verification approved by a reviewer is :verified with an outcome of nil.

Generate the migrations

On AshPostgres, run mix ash.codegen add_identity_document_verification to create the verification and transition log tables.

Limits

A no-match is retried like any other failure. A :verify that succeeds without writing outcome calls your provider --max-attempts times before the verification moves to :needs_review.

AshWorkflow.Transformers.AddPolicies allows :verify for any caller, as it does every automatic step's action. Add a policy to the verification resource if callers outside the scheduler must not run it.

There is no transition from :needs_review back to :verifying. Add transition :retry, to: :verifying to the :needs_review step to let a reviewer send a verification back to the provider.