mix ash_workflow.gen.invitation adds an invitation workflow to a resource. An email address is invited to a record, the invitee accepts or declines, the inviter can revoke or resend the invitation, and an invitation nobody answers expires.

The command

mix ash_workflow.gen.invitation MyApp.Teams.Team \
  --invitee MyApp.Accounts.User \
  --expires-after 7d
OptionDefaultEffect
--inviteerequiredThe actor resource. The inviter and the invitee who accepts belong to it.
--expires-after7dHow long an invitation stays open after invite or resend. Accepts 10s, 30m, 12h, 2d and 2w.
--module<Subject>InvitationName of the generated invitation resource.
--domainthe subject's domainDomain for a subject the task creates. Required only when the subject does not exist.
--transition-logtrueAlso runs mix ash_workflow.gen.transition_log for the invitation resource, recording the invitee resource 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 invitee resource's data layer, or else the data layer of the first ETS or Postgres resource in --domain. When neither the invitee resource 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 five modules and edits the subject:

  • MyApp.Teams.TeamInvitation runs the workflow. It belongs to the team and to the user who sent it, and holds the invited email and expires_at.
  • MyApp.Teams.TeamInvitation.Checks.CanInvite decides who may send an invitation. It denies everyone as generated.
  • MyApp.Teams.TeamInvitation.Checks.CanAccept decides who may accept or decline. It denies everyone as generated.
  • MyApp.Teams.TeamInvitation.Changes.SetExpiresAt sets expires_at to now plus --expires-after on invite and resend.
  • MyApp.Teams.TeamInvitation.Validations.NoOpenInvitation refuses a second open invitation to the same email for the same team.
  • MyApp.Teams.Team gains has_many :invitations and has_one :latest_invitation. The task adds no change, argument or policy to the subject's actions.

The subject gains no boolean calculation such as accepted?. A team has many invitations to different people, so whether the latest one was accepted says nothing about the team. Filter invitations by email instead.

The workflow

stateDiagram-v2
  [*] --> sent: invite
  sent --> sent: resend
  sent --> accepted: accept
  sent --> declined: decline
  sent --> revoked: revoke
  sent --> expired: expires_at passes
workflow do
  step :sent do
    transition :accept, to: :accepted
    transition :decline, to: :declined
    transition :revoke, to: :revoked
    transition :resend, to: :sent

    timeout :expired do
      fire_at :expires_at
      transition_to :expired
    end
  end

  step :accepted, terminal: true
  step :declined, terminal: true
  step :revoked, terminal: true
  step :expired, terminal: true
end

The deadline reads expires_at, not state_entered_at. resend writes a new expires_at a full --expires-after from now, and both schedulers pick up the new deadline. The default Oban scheduler sweeps for due deadlines once a minute, so a short --expires-after such as 10s moves the invitation to :expired up to a minute late. AshWorkflow.Scheduler.Precise fires it on time.

Every outcome is terminal. To invite someone again after their invitation expired, was declined or was revoked, send a new invitation. The old row keeps its outcome.

:accept refuses an invitation whose expires_at has passed, even before the scheduler has moved it to :expired.

What your application does next

Send invitations

Call invite/3 wherever someone invites a person, with the inviter as the actor:

MyApp.Teams.TeamInvitation.invite(team.id, "ada@example.com", actor: current_user)

email is case-insensitive. A second invitation to the same address for the same team fails while the first is in :sent. On AshPostgres, email is a citext column, so the repo needs "citext" in its installed_extensions.

CanInvite gates :invite and denies everyone as generated, so nobody can send an invitation until you change it. Replace its match?/3 with who may invite, for example team admins:

def match?(actor, %{changeset: changeset}, _opts) do
  team_id = Ash.Changeset.get_attribute(changeset, :subject_id)
  MyApp.Teams.admin?(team_id, actor)
end

def match?(_actor, _context, _opts), do: false

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

Deliver the invitation

The task generates no token and sends no email. Send the invitation from an Ash notifier on the invitation resource, or from the code that calls invite/3 and resend/2. If the email carries a link with a token, store the token yourself, for example in an attribute you add to the invitation.

Decide who is the invitee

CanAccept denies everyone, so nobody can accept or decline until you change it. Replace its match?/3 with however an actor proves they are the invitee, such as a matching email:

def match?(%{email: email}, %{subject: %{data: invitation}}, _opts),
  do: Ash.CiString.compare(email, invitation.email) == :eq

def match?(_actor, _context, _opts), do: false

:accept sets invitee to the actor. :decline leaves it unset.

Revoke and resend

Only the user who sent an invitation can revoke or resend it, through relates_to_actor_via(:invited_by). To let others do so, such as team admins, add an authorize_if line to that policy:

policy action([:revoke, :resend]) do
  authorize_if relates_to_actor_via(:invited_by)
  authorize_if relates_to_actor_via([:subject, :admins])
end

Grant what the invitation is for

Accepting an invitation creates nothing else. Add a change to :accept, or a notifier, that creates the membership, RSVP or grant your application needs.

Restrict reads

Reads stay open by default. AshWorkflow authorizes :read on the invitation resource for every actor, and each invitation row holds the invitee's email. Until you add a read policy, any actor can list every invitation's email across all teams. Add a policy that limits reads to the people an invitation concerns, for example the inviter and the invited address:

policy action_type(:read) do
  authorize_if relates_to_actor_via(:invited_by)
  authorize_if expr(email == ^actor(:email))
end

Generate the migrations

On AshPostgres, run mix ash.codegen add_team_invitation to create the invitation and transition log tables.

Limits

On AshPostgres, a partial unique index on subject_id and email where state = 'sent' backs NoOpenInvitation. On other data layers, two invitations to the same address sent at the same moment can both pass the validation.

NoOpenInvitation only looks at invitations in :sent. A team can invite an address that already accepted an invitation.