mix ash_workflow.gen.publication adds a publication workflow to a resource. Each record starts as a draft, can be scheduled for a publish_at, goes live once that passes or when someone publishes it straight away, and can be unpublished and republished. With --with-unpublish-at, a publication can also come down on its own at an unpublish_at.
The command
mix ash_workflow.gen.publication MyApp.Blog.Post --with-unpublish-at
| Option | Default | Effect |
|---|---|---|
--module | <Subject>Publication | Name of the generated publication resource. |
--domain | the subject's domain | Domain for a subject the task creates. Required only when the subject does not exist. |
--with-unpublish-at | false | Generates an unpublish_at attribute and the timeout that moves a publication to :unpublished once it passes. Without it, a publication stays published until someone unpublishes it. |
--transition-log | true | Also runs mix ash_workflow.gen.transition_log for the publication 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.Blog.PostPublicationruns the workflow. It belongs to the post and holdspublish_atandunpublish_at. An identity onsubject_idallows one publication per post.MyApp.Blog.PostPublication.Checks.CanCreatedecides who may create a publication. It denies everyone as generated.MyApp.Blog.PostPublication.Checks.CanPublishdecides who may schedule, publish and unpublish. It denies everyone as generated.MyApp.Blog.Postgainshas_one :publicationand apublished?calculation. The task adds no change, argument or policy to the subject's actions.
The publication 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
[*] --> draft
draft --> scheduled: schedule
draft --> published: publish_now
scheduled --> scheduled: reschedule
scheduled --> draft: unschedule
scheduled --> published: publish_now
scheduled --> published: publish_at passes
published --> unpublished: unpublish
published --> unpublished: unpublish_at passes
unpublished --> published: republishworkflow do
step :draft do
transition :schedule, to: :scheduled
transition :publish_now, to: :published
end
step :scheduled do
transition :reschedule, to: :scheduled
transition :unschedule, to: :draft
transition :publish_now, to: :published
timeout :published do
fire_at :publish_at
transition_to :published
end
end
step :published do
transition :unpublish, to: :unpublished
timeout :unpublished do
fire_at :unpublish_at
transition_to :unpublished
end
end
step :unpublished do
transition :republish, to: :published
end
endWithout --with-unpublish-at, there is no unpublish_at attribute and no :unpublished timeout.
Each deadline reads its own attribute. reschedule writes a new publish_at, and neither timeout reads state_entered_at.
A publication with no unpublish_at stays published until someone calls unpublish. The scheduler never treats an empty fire_at field as due.
No step is terminal. An unpublished record can be republished.
The actions
| Action | From | Writes |
|---|---|---|
schedule | :draft | publish_at, required, and unpublish_at, optional. |
reschedule | :scheduled | publish_at. Keeps unpublish_at. |
unschedule | :scheduled | Clears publish_at and unpublish_at. |
publish_now | :draft, :scheduled | Nothing. A scheduled unpublish_at is kept. |
unpublish | :published | Nothing. |
republish | :unpublished | unpublish_at, optional. Cleared when not given. |
schedule and reschedule reject an unpublish_at that is not after publish_at. No action checks that a date is in the future. A publish_at in the past publishes on the first scheduler pass.
republish clears unpublish_at when none is given. A date that has already passed would otherwise unpublish the record again on the next pass.
What your application does next
Create the publication
Call create/2 wherever a draft starts, such as the subject's create action:
MyApp.Blog.PostPublication.create(post.id, actor: editor)A second publication for the same post fails on the :unique_subject identity.
CanCreate denies everyone, so no publication 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, :editor)
end
endCode that creates a publication on the application's behalf, such as the subject's create action, can pass authorize?: false instead.
Reads stay open by default. AshWorkflow authorizes :read on the publication resource for every actor. Add a read policy if publications are private.
Decide who may publish
CanPublish denies everyone, so no transition a person makes succeeds until you change it. One policy covers schedule, reschedule, unschedule, publish_now, unpublish and republish. Replace match?/3 in CanPublish, or replace the authorize_if line with a built-in check:
policies do
policy action([:schedule, :reschedule, :unschedule, :publish_now, :unpublish, :republish]) do
authorize_if actor_attribute_equals(:role, :editor)
end
endSplit the policy if different people schedule and take down publications. The scheduler's timeouts do not go through it, so a scheduled publication still goes live.
Schedule and publish
MyApp.Blog.PostPublication.schedule(publication, ~U[2027-01-05 09:00:00Z], ~U[2027-02-05 09:00:00Z], actor: editor)
MyApp.Blog.PostPublication.publish_now(publication, actor: editor)React to publishing and unpublishing
The task generates no notification. Add a timeout with an action to the :published or :unpublished step, or use an Ash notifier on the publication resource, to purge a cache or announce the post.
Use the outcome
published? on the subject is true when its publication is in :published. Filtering public reads on it is up to you, for example with a policy on the subject:
policy action(:read) do
authorize_if expr(published?)
authorize_if actor_attribute_equals(:role, :editor)
endGenerate the migrations
On AshPostgres, run mix ash.codegen add_post_publication to create the publication and transition log tables.
Limits
reschedule runs only from :scheduled. Moving unpublish_at on a live publication needs an update action you add yourself.