Repository navigation
Releases
v0.13.0
Added
- Several initial steps. More than one step can set
initial true.AshWorkflow.Transformers.AddStateMachinepasses every initial step to the state machine'sinitial_states, and a create action starts a record in one withchange transition_state(:step). A create that sets no state starts in the first initial step by declaration order. The reachability check inAshWorkflow.Verifiers.ValidateWorkflowstarts from every initial step. A step reached only from a second initial step is no longer reported as unreachable.AshWorkflow.Info.initial_steps/1andAshWorkflow.Entities.Step.find_initials/1list the initial steps, andAshWorkflow.Info.workflow_graph/1, the charts and the Clarity overview mark each of them. everycan fire at a wall-clock time in the record's own time zone, instead of measuring anintervalfrom its last fire.at ~T[09:00:00]names the local time,on [:mon, :tue, :wed, :thu, :fri]names the days, andtime_zone :candidate_time_zonenames the attribute holding the zone, or takes a literal such as"Australia/Sydney". A per-record zone is the case a global cron cannot express: two records in the same step fire at 09:00 in their own zones, at two different instants.AshWorkflow.Verifiers.ValidateEveryrejects aneverydeclaring neither. Firing writes the samelast_fired_fieldcolumn, anduntilstill bounds it againststate_entered_at.intervalalongsideatis a stride: how many local days must separate two fires.onsays which days carry an occurrence and the stride says how many of them to skip, sointerval {14, :days}withon [:mon]is 09:00 every second Monday. A stride must be given in:days, and counts local dates rather than elapsed duration — firing at 09:00 writes the last-fired column microseconds after 09:00, so a duration comparison would find the occurrence exactly one stride later ineligible by that margin and slip the fire a week.AshWorkflow.WallClockcomputes the occurrences behindat. A local time daylight saving skipped still fires that day, at the instant the clock jumped to; a local time that happens twice fires on the first of the two. A missed occurrence fires late rather than being skipped.AshWorkflow.Scheduler.Precisearms its timers from it andAshWorkflow.Calculations.PendingDeadlinesreports the next occurrence from it, so both run on any data layer.AshWorkflow.Scheduler.Obanasks the same question in SQL, with anAT TIME ZONEfragment reading the zone out of each row, soatunder that scheduler needs a SQL data layer.time_zoneaccepts an expression calculation as well as an attribute or a literal, which is how a record reads its zone off a related one:calculate :candidate_time_zone, :string, expr(candidate.time_zone). The calculation must be expression-based, since the zone is read from the trigger's filter —AshWorkflow.Verifiers.ValidateEveryrejects a module calculation, the same checkAshWorkflow.Verifiers.ValidateTimeoutFieldsalready applies to a timeout'sfield.AshWorkflow.Scheduler.Precise.TimelineandAshWorkflow.Calculations.PendingDeadlinesload a calculated zone before reading it.atneeds a time zone database in the host application, such asconfig :elixir, :time_zone_database, Tz.TimeZoneDatabase.AshWorkflow.Verifiers.ValidateEverychecks a literaltime_zoneagainst it at compile time. A record holding a zone the database does not know arms nothing and reports no pending deadline, rather than raising.
Changed
- The unreachable-step error names the initial step it searched from ("not reachable from the initial step :review") rather than "the first step".
AshWorkflow.Verifiers.ValidateWorkflowno longer raises "Only one step can have initial: true".AshWorkflow.Verifiers.ValidateWorkflowrejects a create action whosetransition_statenames a step that is not initial. Before, the create failed at runtime.AshWorkflow.Verifiers.ValidateWorkflowrejects an upserting create action that callstransition_state. ash_state_machine only lets an upsert move to a state that a transition declares for that action, and a workflow declares none for creates.- The unreachable-step error suggests
initial truefor an unreachable step that no other step leads into.
v0.12.0
Added
max_firesandbackoffonevery.max_firesstops aneveryafter a number of fires in the current step visit.backoffgrows the gap after each fire, taking a duration tuple or:exponentiallikeretry'sbackoff, and both schedulers compute it fromAshWorkflow.Entities.Retry.delay_ms/2. Either option adds a<step>_<every>_firesinteger column, so runmix ash.codegenon AshPostgres. Aneverywithout them is unchanged.mix ash_workflow.gen.approvaladds an approval workflow to a resource: a sibling approval resource withpending,approved,rejected,cancelledand an optionaloverduestep, a decision resource, quorum routing, and policies that stop a requester approving their own request. Who may open a request and who may approve live in generatedChecks.CanRequestandChecks.CanApprovemodules, which deny everyone until the application fills them in. See the approval recipe.mix ash_workflow.gen.expiryadds an expiry workflow to a resource: a sibling expiry resource withactive,expiredand an optionalexpiringstep, whose deadlines readexpires_atand move when the expiry is renewed. The subject gainshas_one :expiry, anexpired?calculation and a:set_expiryupdate action, which creates the subject's expiry or renews the one it has. A subject with no expiry never expires. The generatedChanges.SetExpirychange does the same work on any other subject action, taking anexpires_in:option such as{365, :day}where the action has no:expires_atargument.--default-expiry 365dadds that change to the subject'schangesblock for every create, which then fails untilChecks.CanCreatelets the creating actor through. Who may create an expiry and who may renew one live in generatedChecks.CanCreateandChecks.CanRenewmodules, which deny everyone until the application fills them in. See the expiry recipe.mix ash_workflow.gen.dormancyadds a dormancy workflow to a resource: a sibling dormancy resource withactive,dormantand an optionalarchivedstep, driven by alast_activity_atthat arecord_activityaction moves and areactivateaction resets. The subject gainshas_one :dormancy, adormant?calculation, and achangeon its create actions that runs the generatedChanges.StartDormancy, so each new subject starts its own dormancy. The generatedChanges.RecordActivityrecords activity from whichever subject actions the application adds it to. Who may create a dormancy directly and who may reactivate one live in generatedChecks.CanCreateandChecks.CanReactivatemodules, which deny everyone until the application fills them in. See the dormancy recipe.mix ash_workflow.gen.syncadds a sync workflow to a resource: a sibling sync resource withsyncing,syncedandfailedsteps, whose:pushaction is retried with--max-attemptsand--backoffand moves back tosyncingon a resync. The subject gainshas_one :sync, asynced?calculation, and two changes in itschangesblock.Changes.StartSyncstarts a sync on every subject create.Changes.RequestSyncstampsresync_requested_aton every subject update, or only when a--fieldsfield changes, and afire_attimeout onsyncedandfailedresyncs on that stamp, so a request made during a push runs once the push settles. Who may create a sync directly and who may resync one by hand live in generatedChecks.CanCreateandChecks.CanResyncmodules, which deny everyone until the application fills them in. See the sync recipe.mix ash_workflow.gen.transition_logaccepts a workflow resource generated earlier in the same Igniter run, before it has compiled, by reading its source. A resource on disk that fails to compile is still reported as an issue.mix ash_workflow.gen.publicationadds a publication workflow to a resource: a sibling publication resource withdraft,scheduled,publishedandunpublishedsteps, which goes live atpublish_atand, with--with-unpublish-at, comes down atunpublish_at. The subject gainshas_one :publicationand apublished?calculation. Who may create a publication and who may schedule, publish and unpublish one live in generatedChecks.CanCreateandChecks.CanPublishmodules, which deny everyone until the application fills them in. See the publication recipe.mix ash_workflow.gen.reviewadds a review workflow to a resource: a sibling review resource within_review,changes_requested,approved,rejectedand an optionaloverduestep, a decision resource that records each round, and policies that stop a requester reviewing their own work. A subject has at most one open review. Who may open a review and who may review live in generatedChecks.CanRequestandChecks.CanReviewmodules, which deny everyone until the application fills them in. See the review recipe.mix ash_workflow.gen.invitationadds an invitation workflow to a resource: a sibling invitation resource withsent,accepted,declined,revokedandexpiredsteps, whose deadline readsexpires_atand moves when the invitation is resent. Who may invite and who may accept live in generatedChecks.CanInviteandChecks.CanAcceptmodules, which deny everyone until the application fills them in. See the invitation recipe.mix ash_workflow.gen.verificationadds a verification workflow to a resource: a sibling verification resource withsubmitted,verifying,needs_review,verifiedandrejectedsteps, whose automatic:verifyaction retries up to--max-attemptstimes before the verification moves to review. The subject gainshas_many :verifications,has_one :latest_verificationand averified?calculation. Who may submit a verification and who may decide one in review live in generatedChecks.CanSubmitandChecks.CanReviewmodules, which deny everyone until the application fills them in. See the verification recipe.mix ash_workflow.gen.deletionadds a deletion workflow to a resource: a sibling deletion resource withrequested,purging,purge_failed,restoredanddeletedsteps. A grace period afterrequested_atmoves a request topurging, which runs a:purgeaction with retries and moves topurge_failedwhen they run out. The subject gainshas_one :deletionand apending_deletion?calculation. What a purge erases lives in a generatedChanges.Purgechange, which fails every purge until the application fills it in. Who may request and who may restore live in generatedChecks.CanRequestandChecks.CanRestoremodules, which deny everyone until the application fills them in. See the deletion recipe.mix ash_workflow.gen.acknowledgementadds an acknowledgement workflow to a resource: a sibling acknowledgement resource withpending,acknowledgedand an optionaloverduestep, holding one request per person per subject, which only that person may acknowledge. Who may open a request lives in a generatedChecks.CanRequestmodule, which denies everyone until the application fills it in. See the acknowledgement recipe.
Fixed
- A create action that upserts onto an existing row no longer appends an
:initialrow to the transition log, emits the workflow's signals or callsAshWorkflow.Scheduler.notify_state_change/2. The row stays in the step it was in.AshWorkflow.Changes.RecordEventskips all three when the returned record carriesupsert_action: :updatemetadata, orupsert_skipped: truemetadata from anupsert_conditionthat did not match. This coversAsh.create/2andAsh.bulk_create/4. The[:ash_workflow, :transition]span still emits:stop, because its:startevent fires before the data layer reports whether the row was inserted. Ash setsupsert_actionon ETS and Mnesia from 3.29, which ash_workflow already requires. AshPostgres sets it from 2.10.0 on PostgreSQL 17 and later, and from 2.13.1 on every PostgreSQL version. With an older AshPostgres, an upsert onto an existing row is still logged. - Transition and timeout actions that
AshWorkflow.Transformers.AddActionsgenerates on a workflow resource with apre_check_withidentity now setrequire_atomic? false. Ash adds abefore_actionfor such an identity, so the generated actions failed withMustBeAtomic. Those actions now run non-atomically on that resource.
v0.11.0
Upgrading from 0.10.2
ash_workflownow depends onash ~> 3.35, forAsh.Signals.
Added
- Workflow signals. The new
signalsoption on theworkflowsection names anAsh.Signalsmodule, andemitdeclares a signal at four levels: the workflow (every state change), a step (on: :enteroron: :exit), atransition, and atimeoutorevery.AshWorkflow.Changes.RecordEventemits each matching signal in itsafter_actionhook, after the log row, with a payload of the workflow fieldsfrom_state,to_state,transition_name,triggered_byandoccurred_at, the attributes that share a signal field's name, theemit'sfieldsand its literalvalues. A failing listener fails the action and rolls it back.AshWorkflow.Transformers.AddActionsdeclares each planned signal as a dynamic emit on the action, andAshWorkflow.Verifiers.ValidateSignalschecks the names and phases.AshWorkflow.Info.signals/1,emits/1andaction_signals/2read the configuration. Atransition,timeoutoreverythat contains anemittakes its options inside thedoblock. See the Signals guide. - Receiving signals with
on_signal. A step can declareon_signal, which moves a record totransition_to, or runs an updateaction, when a signal from the workflow'ssignalsmodule (orfrom) selects that record while it is in the step.filterselects records with^signal(:field)templates, orread_actionnames a read action of the resource.AshWorkflow.Transformers.AddActionsgenerates the:__signal_<step>_<signal>_readread action, the:__signal_<step>_<signal>transition action and asignals_inlistener named:<step>_<signal>, and the log row recordstriggered_by: :signal.AshWorkflow.Transformers.AddPoliciesauthorizes the generated actions withsignal_in/2.AshWorkflow.Verifiers.ValidateOnSignalchecks the signal, its fields and the outcome, and a step whose only exits areon_signalhandlers withtransition_tois a wait state. Charts draw anon_signaledge with📨. See the Signals guide.
v0.10.2
Upgrading from 0.10.1
- Under
AshWorkflow.Scheduler.Oban, an action that moves a record into an automatic step now inserts an Oban job. A test that runs such an action needs a repo connection checked out, even when the workflow resource uses the ETS data layer. With Oban'stesting: :inline, the step's action now runs inside the action that moved the record. - A
run_oban_trigger/1change that queued an automatic step after a create or a transition is no longer needed. Leaving it in place queues no second job, because ash_oban's trigger worker is unique while a job is incomplete.
Added
- A Workflows lens for Clarity. With Clarity installed,
AshWorkflow.Clarity.Lensmakeradds a Workflows lens that lists each workflow resource with its steps.AshWorkflow.Clarity.Introspectoradds anAshWorkflow.Clarity.Vertex.Stepfor each step. A workflow resource gets Workflow Overview, Workflow Diagram and Workflow Timing tabs, and a step gets Step Overview, Step Diagram and Step Timeline tabs. The timing tabs place each automatic action, retry attempt, timeout,everyfiring and undo window at its offset from entering the step, and say how long a record can stay in each step. Clarity is an optional dependency, so a project without it compiles none of these modules. - An
:actoroption forAshWorkflow.Scheduler.Oban. The value becomes each generated trigger'sdefault_actor. A cron-fired scheduler has no caller and read with anilactor, so on a resource whose read policy needs an actor it matched no rows and the workflow never advanced. Withscheduler {AshWorkflow.Scheduler.Oban, actor: ...}the scheduler reads as that actor, and the worker runs the step's or timeout's action as it when the job stored no actor. See issue #150.
Fixed
AshWorkflow.Scheduler.Obanruns an automatic step as soon as a record enters it, asAshWorkflow.Scheduler.Precisealready did. Before, the record waited for the trigger's nextcheck_interval, becauseAshWorkflow.Scheduler.notify_state_change/1called onlydeadline_changed/2andcancel/2, and the Oban scheduler implements neither.notify_state_change/2now also calls the new optionalAshWorkflow.Scheduler.step_entered/2callback whenAshWorkflow.Changes.RecordEventreports that the record entered its step.AshWorkflow.Scheduler.Oban.step_entered/2queues the step's trigger withAshOban.run_trigger/3. A step whose action routes the record back into the same step does not count as entering it, so that record still waits for the poll. An action timeout and aneverydo not count either. The queued job carries no actor, the same as a job the poll queues. A transition declared directly in thestate_machineblock does not runRecordEvent, so a record it moves into an automatic step still waits for the poll.AshWorkflow.Scheduler.Precisearms a timeout whosefire_atorfieldnames an expression calculation as soon as a record enters the step.AshWorkflow.Scheduler.notify_state_change/1handeddeadline_changed/2the record without that calculation loaded, soAshWorkflow.Scheduler.due_at/2returnednil, no timer was armed, and only the recovery sweep caught the deadline, up tolook_ahead_mslate.notify_state_change/1now loads the calculations returned by the newAshWorkflow.Scheduler.Work.deadline_loads/1before callingdeadline_changed/2.AshWorkflow.Scheduler.Obanwas not affected, because its trigger evaluates the calculation in thewhereclause.
Security
- The development lock now resolves
ash3.37.2,ash_postgres2.15.2 andplug_crypto2.2.1, which fix the advisoriesmix hex.auditreported againstash3.34.6 (EEF-CVE-2026-96581, EEF-CVE-2026-114214),ash_postgres2.13.1 (EEF-CVE-2026-115627, EEF-CVE-2026-115635) andplug_crypto2.2.0 (EEF-CVE-2026-105963). Theash ~> 3.0requirement inmix.exsis unchanged, so applications pick their own versions. Upgrade them in your own lock to get the fixes.
v0.10.1
Upgrading from 0.10.0
- A conditional route that reads a related field, a calculation or an aggregate now loads it when the transition runs. A route that relied on an unloaded relationship reading as
nil, such asis_nil(sponsor.name), now sees the real value. A route on a relationship the caller had already loaded now reads the current value, not the loaded copy.AshWorkflow.Info.transition_target/3still loads nothing.
Fixed
- A transition whose action the resource declares without
acceptno longer crashesAshWorkflow.Transformers.AddActionswithnil ++ []. The action keeps Ash'sdefault_acceptunless the transition accepts attributes of its own. - A conditional route that references a calculation, an aggregate or a related field now reads its current value.
AshWorkflow.Changes.ConditionalTransitionloads those fields before evaluating routes, as the:transition_targetscalculation already did. The action used to read them off the record it was called on, so an unloaded field read asniland no route matched. A route over a relationship the caller had already loaded now reads the current value rather than the loaded copy.
v0.10.0
Upgrading from 0.9.x
- Generate a migration. Each action timeout (a
timeoutwithactionand notransition_to) adds a nilable<step>_<timeout>_fired_atcolumn. On AshPostgres, runmix ash.codegenafter upgrading. - A record whose action timeout already fired before the upgrade has a
nilcolumn, so that timeout fires once more for it after the upgrade.
Added
- A generated
:workflow_terminated_atcalculation returnsstate_entered_atwhile a record is in a terminal step, andnilwhile the workflow is still running. A terminal step has no outgoing transitions, so the time the record entered it is the time the workflow ended, and no new attribute or migration is needed. The calculation is an expression, so it filters and sorts in the data layer:Ash.Query.filter(workflow_terminated_at > ago(7, :day)). The newterminated_at_calculationoption on theworkflowsection renames it, for a resource that already has a field by that name.AshWorkflow.Transformers.AddCalculationsadds it withadd_new_calculation, so a user-defined calculation with the configured name takes precedence. (#120)
Fixed
- An action timeout fires once for each deadline under both schedulers.
AshWorkflow.Scheduler.Precisefired a due action timeout in a loop: firing left the record matching,AshWorkflow.Changes.RecordEventrearmed it, andrun_due/2never returned 0.AshWorkflow.Scheduler.Obanrelied ontrigger_once?, so the completed job row was the only record of a firing. Pruning the row fired the timeout again, keeping it stopped a second visit to the step from firing, and afire_attimeout whose action moved its own field later never fired a second time. Each action timeout now writes its own<step>_<timeout>_fired_atcolumn (AshWorkflow.Entities.Timeout.fired_field/2) when it fires, andAshWorkflow.Scheduler.Work.not_fired/1addsis_nil(fired_at) or fired_at < deadlineto the timeout'smatch. The timeout fires again once its deadline moves past the column. A new visit to the step and a laterfire_atvalue both do that.AshWorkflow.Scheduler.Workreplacesonce?withfired_field, the generated Oban trigger no longer setstrigger_once?, andpending_deadlinesomits an action timeout that has fired for its current deadline.AshWorkflow.Verifiers.ValidateTimeoutFiredFieldsrejects a fired column that names an existing non-datetime attribute, and two timeouts, or a timeout and anevery, that resolve to the same column. (#106) - The exported
locals_without_parensnow includeslast_fired_field. A project withimport_deps: [:ash_workflow]in its.formatter.exshadmix formatrewritelast_fired_field :reminder_fired_ataslast_fired_field(:reminder_fired_at). (#120)
v0.9.0
Upgrading from 0.8.x
ash_workflownow depends onjason ~> 1.4, for the:jsonchart backend.
Added
- Workflow diagrams.
AshWorkflow.Chartsdraws a workflow from its DSL.AshWorkflow.Charts.mermaid_state_diagram/2returns a MermaidstateDiagram-v2that marks each step as automatic, manual, wait state or terminal. It labels a timeout with its name and its deadline (⏱ auto_escalate after 4 hours,⏱ go_live at publish_at) and gives each conditional route itswhenexpression. It notes a step's policy through the check's owndescribe/1, itsretry, the timeouts that run an action and itseveryentries. It draws each undo move thatAshWorkflow.Info.undoable_edges/1allows, with the undo window whenwithinis set (↶ undo within 1 hour).AshWorkflow.Charts.render/3takes:mermaid,:jsonor any module that implementsAshWorkflow.Charts.Backend. Every format draws from oneAshWorkflow.Charts.Graph, so all formats show the same workflow.:jsongives that graph as plain data, for a client that draws the workflow itself.mix ash_workflow.diagramprints a diagram, or with--outputwrites one file for each workflow resource in the project's domains. The Diagrams guide shows four small workflows fromexamples/basicwith their charts, and both the definitions and the charts are generated from the code:bin/update-chart-examplesrewrites them, andtest/documentation_charts_test.exsfails when one is stale. (#16) - Graphviz DOT diagrams.
AshWorkflow.Charts.render(resource, :dot)andmix ash_workflow.diagram --format dotgive a Graphviz DOT chart of a workflow. It shows the same steps, edges and labels as the Mermaid chart, with colour and line styles. It takes its colours fromAshWorkflow.Charts.Palette.svg: true, or--svg, runsdotfrom thePATHand returns the SVG. You install Graphviz.:pathunderconfig :ash_workflow, :dotselects anotherdot, for example in a release. Without adot,svg: trueraises anArgumentErrorthat says to install Graphviz.- Colour follows the graph: blue automatic steps, amber manual steps and lavender wait states. A terminal step is green, red, amber or grey by the kinds of edges that reach it.
on_successis a thick line, a timeout is dashed, and undo is dotted with a hollow arrowhead. theme: :dark, or--theme dark, gives a dark chart. With--output, a dark chart goes to a file such asMyApp.Candidate-dark.svg, beside the light file.classes:changes the colours and line styles of the step kinds, the terminal steps, and theon_success,on_error, timeout and undo edges. Transitions, the start circle and the background have no class. A key is a Graphviz attribute name, such asfillcolororpenwidth: a node attribute for a step class, and an edge attribute for an edge class.classes: [light: [...], dark: [...]]gives each theme its own colours.classes:andtheme:can also go underconfig :ash_workflow, :dot.- The chart puts a step's notes inside the step.
direction: :rightturns the chart on its side.
v0.8.0
Upgrading from 0.7.x
- A stale transition now fails. Code that transitions a struct it loaded before the record changed — a second transition on the struct the first was called on, or a record held in a LiveView assign since mount — gets
Ash.Error.Changes.StaleRecordinstead of a silent, wrong write. Reload the record first, or use the struct the previous transition returned, and handleStaleRecordwherever a user can act on a page that has gone stale (show "this changed, refresh"). There is no option to turn it off. On a data layer that cannot filter an update, such asAsh.DataLayer.Simple, nothing changes. entered_current_state_atis gone. Readstate_entered_atinstead, or filterhistory/1for rows wherefrom_state != to_state.- New:
skip_other_actors?onbelongs_to_actor, for anyone who hand-rolled actor capture around a non-Ash-resource actor. - New:
AshWorkflow.Info.transition_target/3and the generated:transition_targetscalculation, for anyone who copied route matching to preview where a transition goes.
Breaking
- A transition built from a stale record now fails with
Ash.Error.Changes.StaleRecordinstead of writing. A transition decides from the record it is called on whether it is legal and where it goes, then writes by primary key. Before this, a transition from a stale copy ran from a step the record had left, routed on values that had since changed, or overwrote a concurrent transition, all silently. Now every manual transition andundofilter their update on the state attribute and on each attribute of the resource that a route of the loaded step reads, withis_nil/1for anilvalue. The row is left as it was, on the atomic and non-atomic update paths. There is no option to turn this off. Code that transitions a struct it loaded before the record changed, such as a second transition on the struct the first was called on, must reload it first. An attribute the call supplies throughacceptis not pinned, and neither are references through a relationship, calculations or aggregates. A change to an attribute no route reads does not make a copy stale. Automatic step actions, timeouts and error paths are not covered, since the scheduler reads the record just before it runs them. On a data layer that cannot filter an update, such asAsh.DataLayer.Simple, nothing is pinned and transitions behave as before.AshWorkflow.Changes.RefuseStaleTransitiondoes the filtering. It shares the route reference collection of:transition_targetsthroughAshWorkflow.Routing.references/2. - Removed the
entered_current_state_atcalculation andAshWorkflow.Calculations.EnteredCurrentStateAt. The calculation existed because a repeating timeout resetstate_entered_aton each firing. Since 0.7.0 eacheverywrites its own<step>_<every>_last_fired_atcolumn, sostate_entered_atis written only on a genuine step entry and the two agree. Where they still differed, the calculation was wrong: a transition into the step the record is already in updatesstate_entered_atbut logs afrom_state == to_staterow, which the calculation skipped. It also readhistory/1once per record and could not be used as a timeoutfield. Readstate_entered_atinstead. To get the entry time the log attests to, filterhistory/1for rows wherefrom_state != to_state.
Added
skip_other_actors?onbelongs_to_actor.belongs_to_actor :user, MyApp.Accounts.User, skip_other_actors?: truerecordsnilfor an actor that is not aMyApp.Accounts.Userstruct, as it does for anilactor. Without it, an action run as a plain-struct actor that is not an Ash resource, such as a system actor for an AshOban run or an internal side effect, raisesAsh.Error.UnknownwhenAshWorkflow.Changes.RecordEventwrites its log row, and an actor of another resource has its primary key written to the actor foreign key. Both stay the default. Withundo same_actor? true,AshWorkflow.Undorefuses a skipped caller with:no_actor.AshWorkflow.Entities.TransitionLog.recorded_actor/2returns the actor a log row records.- A workflow resource with a
transition_lognow gets a publichas_many :transitionsrelationship to the log resource, added byAshWorkflow.Transformers.AddRelationships. Itsdestination_attributeis the log'sbelongs_toforeign key back to the workflow. A user-defined:transitionsrelationship takes precedence. AshWorkflow.Info.transition_target/3returns the step a transition would move a record to, without running it. It returns{:ok, step},{:ok, nil}when the record's current step does not declare the transition or no route matches, and{:error, error}when a route'swhenfails to evaluate. It raisesArgumentErrorfor a name no step declares. A route that reads accepted input sees it only when the transition runs, so the function takes an optional input map and applies the keys the transition accepts. It resolves routes through the same code asAshWorkflow.Changes.ConditionalTransition, which now shares its route matching and input merge with it, so a preview and the transition cannot disagree.- A generated
:transition_targetscalculation maps each transition of a record's current step to the step it would land in, such as%{advance: :compliance, reject: :rejected}. A transition maps tonilwhen no route matches or a route fails to evaluate, and a record at an automatic or terminal step gets an empty map. The map is not filtered by authorization. The calculation loads every field its routes reference, including fields on related resources.AshWorkflow.Transformers.AddCalculationsadds it withadd_new_calculation, so a user-defined:transition_targetstakes precedence.
Security
- Updated the locked
ashfrom 3.33.5 to 3.33.11, which fixes EEF-CVE-2026-93477 (MEDIUM): private action arguments can be set by user input on the bulk update and bulk destroy paths. Introduced in 2.17.15 and fixed in 3.33.11. The~> 3.0constraint already allowed the fix; only the lockfile held the affected version. The demo lockfiles moved from 3.32.3 to the same version, with the packages ash requires. Ash 3.33.11 also refuses to compile a resource until the application setsconfig :ash, default_string_length_count:, so each demo now sets:codepoints, as this library's own config does.
v0.7.1
Fixed
AshWorkflow.Scheduler.Precise.Timeline's sweep now reads the attribute a workflow named withstate_attribute. It built its step predicate asstate == ^step, so a workflow keeping its state anywhere other thanstatematched no records: a deadline nothing had armed was never recovered, and one inside the horizon was never armed.Timeline.deadline_changed/2was unaffected, since it arms fromAshWorkflow.Scheduler.Work.match, whichAshWorkflow.Transformers.AddSchedulerhas always built through the named attribute. The sweep rebuilds that predicate rather than reusingmatchso the horizon's bound reaches the data layer as a bind parameter, and it now builds it fromAshWorkflow.Info.state_attribute/1.
v0.7.0
Upgrading from 0.6.x
- Rewrite every repeating timeout as an
every.timeout :nudge, fire_after: {1, :day}, action: :send_nudge, repeat: truebecomesevery :nudge, {1, :day}, action: :send_nudge. Therepeatoption no longer compiles. - Run
mix ash.codegen add_every_last_fired_columnsand migrate.AshWorkflow.Transformers.AddAttributesnow adds one column perevery, andAshWorkflow.Transformers.AddIndexesa(state, column)index for each, so a resource that declares aneveryfails on insert until the migration runs. - Drop
state_entered_atfrom any action'sacceptlist. It iswritable?: false, and a caller that genuinely needs to set it usesAsh.Changeset.force_change_attribute/3.
Added
-
every, a sibling entity totimeout. Declares a recurring action that runs on an interval for as long as a record sits in its step:every :nudge, {1, :day}, action: :send_reminderor the block form withinterval,action,check_interval,self_scheduled?,last_fired_fieldand a nestedretry. Unliketimeout,everyalways requiresaction, has notransition_toand nofield. It measuresintervalagainst its own nilable:utc_datetime_usecattribute, one perevery, named<step>_<every>_last_fired_atby default or explicitly withlast_fired_field— notstate_entered_at, and notfield, which names an anchor AshWorkflow reads and never writes.AshWorkflow.Changes.RecordEventwrites that column on every fire via its:every_fieldoption, so twoeveryentities on the same step, or aneveryand atimeout, no longer share (and reset) one anchor. A record whose column is stillnil(never fired) measures its interval fromstate_entered_atinstead, so the first firing lands one whole interval after the record entered the step and an existing table needs no backfill. Both the generated Oban trigger andAshWorkflow.Scheduler.Precise.Timelineapply that fallback, as doesAshWorkflow.Calculations.PendingDeadlines.AshWorkflow.Info.everys/2reads the entities off a step.AshWorkflow.Info.recommended_indexes/1covers eachevery's column with the same(state, field)composite index it gives atimeout. -
fire_aton a timeout. Names a datetime attribute or expression calculation that already holds the deadline instant, rather than an anchor to measure an offset from:timeout :dormant do fire_at :next_check_at; transition_to :dormant_review endfires oncenext_check_athas passed, at whatever resolution the selected scheduler polls with.fire_atandfire_afterare mutually exclusive and exactly one of them is required, andfire_atcannot be combined withfield, which is the anchorfire_aftermeasures from.AshWorkflow.Verifiers.ValidateTimeoutPrecisionskips afire_attimeout: it promises no duration, so there is no precision for the scheduler to miss. That replaces thefire_after: {1, :seconds}sentinel the verifier used to coach people towards, which handed it a number that meant nothing.AshWorkflow.Scheduler.Work'sdeadlinemap expresses both shapes, with anilfire_aftermeaning the field holds the instant, andAshWorkflow.Scheduler.due_at/2resolves either to aDateTime.AshWorkflow.Info.workflow_graph/1carriesfire_at, andAshWorkflow.Info.recommended_indexes/1covers afire_atfield with the same(state, field)composite index it gives afield. -
A bound on
everywithuntil.everyfires forever by default;untilstops it after a fixed amount of wall-clock time:every :reminder do interval {2, :days} action :send_review_reminder until {8, :days} enduntilis measured againststate_entered_atdirectly, which anevery's own firing no longer touches (see above).AshWorkflow.Verifiers.ValidateEveryrejects anuntilthat is not strictly longer thaninterval, since anything shorter or equal leaves no room to fire even once. BothAshWorkflow.Scheduler.ObanandAshWorkflow.Scheduler.Precisehonour the bound through the sameWork.matchexpression every other check already goes through, andAshWorkflow.Scheduler.Precise.Timeline's recovery sweep filters on it too. Reaching the bound only stops the firing; compose a second, ordinary timeout with afire_afterequal to the bound for "give up and move on".
Changed
-
Breaking:
state_entered_atis no longer writable through an action.AshWorkflow.Transformers.AddAttributesdeclares itwritable?: false, so it cannot appear in an action'sacceptlist and is rejected as action input. Every deadline on a step measures from this attribute, so a write from outside moved all of them at once, and afire_aftertimeout could be pushed out of reach by an unrelated update.AshWorkflow.Changes.RecordEventis unaffected: it writes the attribute withAsh.Changeset.force_change_attribute/3and, on the atomic path, through the mapatomic/3returns, and neither goes throughwritable?. A caller that genuinely needs to set it, such as one backfilling imported records, usesforce_change_attribute/3or the data layer directly. A resource that defines its ownstate_entered_atkeeps whatever it declared, since the transformer is a no-op there. -
Breaking:
timeout'srepeatoption is gone. Useeveryinstead.repeat: truelet a timeout re-fire on its own interval, but it also compiled two combinations that were meaningless:repeat: truewithtransition_to(firing leaves the step, so the repeat never comes round) andrepeat: truewith a customfield(rejected at compile time, since the repeat mechanism resetsstate_entered_at, not the custom field).everyrequiringactionand offering neithertransition_tonorfieldstops both from being representable at all. Changetimeout :name, fire_after: ..., action: ..., repeat: truetoevery :name, interval: ..., action: ....AshWorkflow.Verifiers.ValidateTimeoutFields.validate_no_repeat_with_custom_field/2and its tests are gone along with the option. -
Breaking:
AshWorkflow.Info.workflow_graph/1's:timeoutsentries drop:repeat, and each step's map gains an:everyslist of%{name:, interval:, action:, until:, retry:}maps, mirroring:timeouts.
Fixed
AshWorkflow.Scheduler.due_at/2returnsnilfor a deadline field that is an unloaded calculation, rather than raising on the%Ash.NotLoaded{}struct it read.AshWorkflow.Scheduler.Precise.Timelineloads a calculation deadline field with the records it sweeps and re-reads before firing, so it arms the timer from a value rather than from nothing. That is the #70 failure mode under the Precise scheduler; a caller computingdue_at/2from a record of its own still has to load the calculation first.