mix ash_workflow.gen.expiry adds an expiry workflow to a resource. Each record gets an expires_at, moves to :expiring a notice period before it, moves to :expired once it passes, and returns to :active when it is renewed with a new date.
The command
mix ash_workflow.gen.expiry MyApp.Contracts.Contract --notice-period 30d
| Option | Default | Effect |
|---|---|---|
--module | <Subject>Expiry | Name of the generated expiry resource. |
--domain | none | Domain for a subject the task creates. Required when the subject does not exist, and ignored when it does: the expiry resource then joins the subject's domain. |
--notice-period | none | Moves an expiry to :expiring this long before expires_at. Accepts 10s, 30m, 12h, 2d and 2w. Without it, no :expiring step is generated. |
--default-expiry | none | Starts an expiry on every create of the subject, this long after the create. Accepts 10s, 30m, 12h, 2d and 2w. Without it, the subject's create is left alone. See Default expiry on create. |
--transition-log | true | Also runs mix ash_workflow.gen.transition_log for the expiry 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 four modules and edits the subject:
MyApp.Contracts.ContractExpiryruns the workflow. It belongs to the contract and holdsexpires_at. Itssubject_idtakes the type of the contract's primary key, and the task reports an issue for a subject with a composite primary key. An identity onsubject_idallows one expiry per contract.MyApp.Contracts.ContractExpiry.Checks.CanCreatedecides who may create an expiry. It denies everyone as generated.MyApp.Contracts.ContractExpiry.Checks.CanRenewdecides who may renew. It denies everyone as generated.MyApp.Contracts.ContractExpiry.Changes.SetExpiryis a change for the contract's actions. After the contract action succeeds, it creates the contract's expiry, or renews the one it has.MyApp.Contracts.Contractgainshas_one :expiry, anexpired?calculation, and an update action:set_expirywith aset_expirycode interface.:set_expirytakes anexpires_atargument and runsSetExpiry. The task changes none of the subject's other actions.
A contract with no expiry never expires. Its expired? is false, and no timeout runs for it. Nothing creates an expiry until your application calls :set_expiry or adds SetExpiry to one of its own actions, as described in Start the clock. The --default-expiry flag adds SetExpiry to every create of the subject.
The expiry is a separate resource rather than a workflow block on the subject, so a subject that already runs a workflow keeps it.
The workflow
stateDiagram-v2
[*] --> active
active --> expiring: expiring_at passes
expiring --> expired: expires_at passes
active --> active: renew
expiring --> active: renew
expired --> active: renewworkflow do
step :active do
transition :renew, to: :active
timeout :expiring do
fire_at :expiring_at
transition_to :expiring
end
end
step :expiring do
transition :renew, to: :active
timeout :expired do
fire_at :expires_at
transition_to :expired
end
end
step :expired do
transition :renew, to: :active
end
end
calculations do
calculate :expiring_at, :utc_datetime_usec, expr(datetime_add(expires_at, -30, :day))
endWithout --notice-period, there is no :expiring step and no expiring_at calculation. The :expired timeout sits on :active instead.
Both deadlines read expires_at, and expiring_at is calculated from it. Renewing writes a new expires_at, which moves both deadlines. Neither timeout reads state_entered_at.
:expired is not terminal. An expired record stays expired until it is renewed.
An expiry created with expires_at already in the past moves to :expiring on the first scheduler pass and to :expired on the next.
What your application does next
Decide who may create an expiry
CanCreate denies everyone, so no expiry can be created until you change it. Replace its match?/3, or replace the authorize_if line in the :create policy with a built-in check:
policies do
policy action(:create) do
authorize_if actor_attribute_equals(:role, :account_manager)
end
endCode that creates an expiry on the application's behalf, such as an import, can pass authorize?: false instead.
Reads stay open by default. AshWorkflow authorizes :read on the expiry resource for every actor. Add a read policy if expiries are private.
Start the clock
set_expiry/3 on the contract creates its expiry, or renews the one it already has:
MyApp.Contracts.Contract.set_expiry(contract, ~U[2027-06-30 00:00:00Z], actor: current_user)To start the clock from one of the contract's own actions, add SetExpiry with an expires_in: option to it:
create :create do
accept [:title]
change {MyApp.Contracts.ContractExpiry.Changes.SetExpiry, expires_in: {365, :day}}
endexpires_in: is {count, unit}, with a unit of :second, :minute, :hour, :day or :week. expires_at is the time the action runs plus expires_in:. An action that has an :expires_at argument uses the argument instead. An action with neither fails with an error on expires_at.
SetExpiry also works in an atomic update, so the action it is added to does not need require_atomic? false. It runs after the contract action, so its error fails the contract action, and on a data layer with transactions the contract change rolls back with it.
To backfill contracts that existed before the recipe, run :set_expiry over those without an expiry with Ash.bulk_update/4:
require Ash.Query
MyApp.Contracts.Contract
|> Ash.Query.filter(not exists(expiry, true))
|> Ash.bulk_update(:set_expiry, %{expires_at: ~U[2027-06-30 00:00:00Z]},
strategy: :stream,
actor: current_user
):set_expiry declares require_atomic? false, so Ash.bulk_update/4 needs strategy: :stream.
The actor and tenant of the contract action pass through to the expiry's create and renew, so CanCreate and CanRenew decide whether set_expiry succeeds. A contract action called with authorize?: false passes authorize?: false on. On a contract that uses Ash.Policy.Authorizer, :set_expiry also needs a policy of its own, and the task prints a notice saying so.
ContractExpiry.create/3 and ContractExpiry.renew/3 remain the lower-level calls. Use them when the code has the expiry rather than the contract:
MyApp.Contracts.ContractExpiry.create(contract.id, ~U[2027-06-30 00:00:00Z], actor: current_user)A second expiry for the same contract fails on the :unique_subject identity.
Default expiry on create
--default-expiry 365d gives every new contract an expiry 365 days out. The task adds a global change to the contract:
changes do
change {MyApp.Contracts.ContractExpiry.Changes.SetExpiry, expires_in: {365, :day}},
on: [:create]
endThe change runs on every create action of the contract. SetExpiry creates the expiry with the actor of the contract create, so CanCreate must let that actor through. Until it does, every contract create fails with a forbidden error. A contract create called with authorize?: false creates its expiry with authorize?: false too. The task prints a notice saying so.
Running the task again with the same flag changes nothing. When the contract already has a SetExpiry change with other options, the task keeps it and prints a warning that shows both versions.
Decide who may renew
CanRenew denies everyone, so nothing can be renewed until you change it. Replace its match?/3, or replace the authorize_if line in the expiry's policy with a built-in check:
policies do
policy action(:renew) do
authorize_if actor_attribute_equals(:role, :account_manager)
end
endRenew
renew/3 takes the new expires_at and returns the expiry to :active from any step:
MyApp.Contracts.ContractExpiry.renew(expiry, ~U[2028-06-30 00:00:00Z], actor: current_user)renew does not check that the new date is in the future. Add a validation to the :renew action if your application needs one.
React to expiring and expired
The task generates no notification. Add a timeout with an action to the :expiring or :expired step to send a reminder or revoke access, or use an Ash notifier on the expiry resource.
Use the outcome
expired? on the subject is true when its expiry is in :expired, and false otherwise, including for a subject with no expiry. Gating a subject action on it is up to you, for example with a policy on the subject:
policy action(:sign) do
forbid_if expr(expired?)
authorize_if always()
endGenerate the migrations
On AshPostgres, run mix ash.codegen add_contract_expiry to create the expiry and transition log tables.
Limits
expiring_at is a calculation, so Postgres has no index on it. The trigger for the :active step filters on the state and then on expires_at minus the notice period. The (state, expires_at) index AshWorkflow adds for the :expired timeout covers the state part of that filter only.
expiring_at is computed in whole seconds, so the notice deadline can fall up to a second before expires_at minus the notice period.
AshWorkflow.Scheduler.due_at/2 returns nil for an expiry whose expiring_at was not loaded. Load the calculation before calling it.