AshWorkflow.Scheduler.Oban (AshWorkflow v0.12.0)

Copy Markdown View Source

Runs a workflow's scheduled work through ash_oban. The default scheduler.

Each AshWorkflow.Scheduler.Work becomes an AshOban trigger whose where is the work's match expression, so ash_oban discovers eligible records by polling rather than being told about deadlines. That makes the polling interval the floor on accuracy: cron cannot ask for less than a minute, which is why AshWorkflow.Verifiers.ValidateTimeoutPrecision rejects a shorter deadline.

The resource must add the AshOban extension

AshWorkflow does not add it. A workflow using a scheduler that has nothing to do with Oban should not carry the ash_oban DSL, so the extension goes where the choice is made:

use Ash.Resource,
  domain: MyApp.Domain,
  data_layer: AshPostgres.DataLayer,
  extensions: [AshWorkflow, AshOban]

Omitting it while this scheduler is selected is a compile error naming the fix.

Options

  • :queue — the Oban queue for every generated trigger. Defaults to the workflow block's queue.

  • :check_interval — the cron for every generated trigger. Defaults to the workflow block's check_interval. A timeout's own check_interval still overrides it.

  • :actor — the actor for every generated trigger, handed to ash_oban as the trigger's default_actor. The cron-fired scheduler reads eligible records as this actor, and the worker runs the step's or timeout's action as it when the job carries no actor of its own. Without it both run with a nil actor, so a resource whose read policy needs an actor never finds a record to run.

    scheduler {AshWorkflow.Scheduler.Oban,
               actor: %MyApp.SystemActor{reason: "workflow"}}

Entering an automatic step

An automatic step has no deadline, so a record is due the moment it enters the step. AshWorkflow.Scheduler.step_entered/2 queues that step's trigger with AshOban.run_trigger/3 when the record enters it, so the action runs without waiting for the next check_interval. The worker re-checks the trigger's where before it runs, so a record that has already moved on is left alone.

A step whose on_success or on_error routes the record back into the same step is not queued again. That route means "nothing to do yet", and the record waits for the next check_interval. A transition declared directly in the state_machine block, not in the workflow, does not run AshWorkflow.Changes.RecordEvent, so a record it moves into an automatic step also waits for the poll.

The queued job carries no actor, the same as a job the cron poll queues.

Retry

A step's or timeout's retry block becomes the generated trigger's max_attempts and backoff. ash_oban runs the step's on_error action only after the final attempt has failed, which is the same rule AshWorkflow.Scheduler.execute/3 documents.

Module names

Worker and scheduler module names are derived from the resource, the step and the timeout, and are set explicitly rather than left to ash_oban's defaults so that renaming a step does not leave jobs pointing at a module that no longer exists.