# `AshWorkflow.Scheduler.Oban`
[🔗](https://github.com/team-alembic/ash_workflow/blob/v0.12.0/lib/ash_workflow/scheduler/oban.ex#L1)

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. `c: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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
