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
OptionDefaultEffect
--module<Subject>PublicationName of the generated publication resource.
--domainthe subject's domainDomain for a subject the task creates. Required only when the subject does not exist.
--with-unpublish-atfalseGenerates 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-logtrueAlso 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.PostPublication runs the workflow. It belongs to the post and holds publish_at and unpublish_at. An identity on subject_id allows one publication per post.
  • MyApp.Blog.PostPublication.Checks.CanCreate decides who may create a publication. It denies everyone as generated.
  • MyApp.Blog.PostPublication.Checks.CanPublish decides who may schedule, publish and unpublish. It denies everyone as generated.
  • MyApp.Blog.Post gains has_one :publication and a published? 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: republish
workflow 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
end

Without --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

ActionFromWrites
schedule:draftpublish_at, required, and unpublish_at, optional.
reschedule:scheduledpublish_at. Keeps unpublish_at.
unschedule:scheduledClears publish_at and unpublish_at.
publish_now:draft, :scheduledNothing. A scheduled unpublish_at is kept.
unpublish:publishedNothing.
republish:unpublishedunpublish_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
end

Code 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
end

Split 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)
end

Generate 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.