# `AshOban`
[🔗](https://github.com/ash-project/ash_oban/blob/v0.8.7/lib/ash_oban.ex#L5)

Tools for working with AshOban triggers.

## Module Names

Each trigger and scheduled action must have a defined module
name, otherwise changing the name of the trigger will lead to
"dangling" jobs. Because Oban uses the module name to determine
which code should execute when a job runs, changing the module name
associated with a trigger will cause those jobs to fail and be lost
if their worker's module name was configured. By configuring the module
name explicitly, renaming the resource or the trigger will not cause
an issue.

This was an oversight in the initial design of AshOban triggers and
scheduled actions, and in the future the module names will be required
to ensure that this does not happen.

Use `mix ash_oban.set_default_module_names` to set the module names to
their appropriate default values.

# `result`

```elixir
@type result() :: %{
  discard: non_neg_integer(),
  cancelled: non_neg_integer(),
  success: non_neg_integer(),
  failure: non_neg_integer(),
  snoozed: non_neg_integer(),
  queues_not_drained: [atom()]
}
```

# `triggerable`

```elixir
@type triggerable() ::
  Ash.Resource.t() | {Ash.Resource.t(), atom()} | Ash.Domain.t() | atom()
```

# `authorize?`

```elixir
@spec authorize?() :: boolean()
```

# `build_context`

```elixir
@spec build_context(:all | [atom()] | nil | false, Oban.Job.t() | nil) :: map()
```

Builds the context map for an AshOban operation based on the `shared_context` configuration.

`shared_context` can be `:all`, a list of keys (`:ash_oban?`, `:job`), or `nil`/`false`.
When a key is in the shared context list, it is placed under the `:shared` key in the context map,
which propagates to related actions called via `manage_relationship`.

# `build_trigger`

Builds a specific trigger for the record provided, but does not insert it into the database.

## Options

- `:scope` - a scope to extract actor, tenant, and context from. See `Ash.Scope.to_opts/2`.
- `:actor` - the actor to set on the job. Requires configuring an actor persister.
- `:tenant` - the tenant to set on the job.
- `:action_arguments` - additional arguments to merge into the action invocation's arguments map.
   affects the uniqueness checks for the job.
- `:args` - additional arguments to merge into the job's arguments map.
   the action will not use these arguments, it can only be used to affect the job uniqueness checks.
   you likely are looking for the `:action_arguments` job.

All other options are passed through to `c:Oban.Worker.new/2`

# `check_for_oban_return`

Checks if an error represents a snooze or cancel instruction for the Oban job.

Returns `{:snooze, seconds}`, `{:cancel, reason}`, or `nil`.

# `config`

Alters your oban configuration to include the required AshOban configuration.

# Options

* `:require?` (`t:boolean/0`) - Whether to require queues and plugins to be defined in your oban config. This can be helpful to
  allow the ability to split queues between nodes. See https://hexdocs.pm/oban/splitting-queues.html The default value is `true`.

# `do_schedule_and_run_triggers`

# `lookup_actor`

```elixir
@spec lookup_actor(actor_json :: any(), actor_persister :: module() | :none | nil) ::
  any()
```

# `oban`
*macro* 

# `run_trigger`

Runs a specific trigger for the record provided.

## Options

Options are passed through to `build_trigger/3` check its documentation
for the possible values

# `run_triggers`

Runs a specific trigger for the records provided.

## Options

Options are passed through to `build_trigger/3` check its documentation
for the possible values

# `schedule`

Schedules all relevant jobs for the provided trigger or scheduled action

## Options

- `:actor` - the actor to set on the job. Requires configuring an actor persister.
- `:action_arguments` - additional arguments to merge into the action invocation's arguments map.
   affects the uniqueness checks for the job. This only affects scheduled actions.

# `schedule_and_run_triggers`

```elixir
@spec schedule_and_run_triggers(
  triggerable() | [triggerable()],
  keyword()
) :: result()
```

Runs the schedulers for the given resource, domain, or otp_app, or list of resources, domains, or otp_apps.

Options:

- `drain_queues?` - Defaults to false, drains the queues after scheduling. This is primarily for testing
- `queue`, `with_limit`, `with_recursion`, `with_safety`, `with_scheduled` - passed through to `Oban.drain_queue/2`, if it is called
- `scheduled_actions?` - Defaults to false, unless a scheduled action name was explicitly provided. Schedules all applicable scheduled actions.
- `triggers?` - Defaults to true, schedules all applicable scheduled actions.
- `actor` - The actor to schedule and run the triggers with
- `oban` - The oban module to use. Defaults to `Oban`

If the input is:
* a list - each item is passed into `schedule_and_run_triggers/1`, and the results are merged together.
* an otp_app - each domain configured in the `ash_domains` of that otp_app is passed into `schedule_and_run_triggers/1`, and the results are merged together.
* a domain - each reosurce configured in that domain is passed into `schedule_and_run_triggers/1`, and the results are merged together.
* a tuple of {resource, :trigger_name} - that trigger is scheduled, and the results are merged together.
* a resource - each trigger configured in that resource is scheduled, and the results are merged together.

# `stacktrace`

# `store_actor`

```elixir
@spec store_actor(
  args :: map(),
  actor :: any(),
  actor_persister :: module() | :none | nil
) :: any()
```

---

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