documentation/dsls/DSL-AshOban.md

Select File:
documentation/dsls/DSL-AshOban.md

<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshOban

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.


## oban


### Nested DSLs
 * [triggers](#oban-triggers)
   * trigger
 * [scheduled_actions](#oban-scheduled_actions)
   * schedule


### Examples
```
oban do
  triggers do
    trigger :process do
      action :process
      where expr(processed != true)
      worker_read_action(:read)
    end
  end
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`domain`](#oban-domain){: #oban-domain } | `module` |  | The Domain to use when calling actions on this resource. Defaults to the resource's domain. |
| [`list_tenants`](#oban-list_tenants){: #oban-list_tenants } | `list(any) \| (-> any) \| module` | `[nil]` | A list of tenants or a function behaviour that returns a list of tenants a trigger should be run for. Can be overwritten on the trigger level. |
| [`shared_context?`](#oban-shared_context?){: #oban-shared_context? } | `boolean` | `false` | If set to `true`, the `ash_oban?: true` flag will be placed in shared context instead of regular context. Shared context propagates to related actions called via `manage_relationship` and can be passed to other action invocations using the context as scope, making it easier to detect AshOban execution in nested actions. Can be overridden per trigger or scheduled action. |
| [`use_tenant_from_record?`](#oban-use_tenant_from_record?){: #oban-use_tenant_from_record? } | `boolean` | `false` | Default value for `use_tenant_from_record?` for all triggers in this resource. When set to `true`, tenants will be extracted from each record's tenant attribute and used when workers process those records. This allows schedulers to use multitenancy `:allow_global` read actions to find records across all tenants, while worker actions still run with the correct tenant context for each record. Can be overridden per trigger. |


### oban.triggers


### Nested DSLs
 * [trigger](#oban-triggers-trigger)


### Examples
```
triggers do
  trigger :process do
    action :process
    where expr(processed != true)
    worker_read_action(:read)
  end
end

```




### oban.triggers.trigger
```elixir
trigger name
```






### Examples
```
trigger :process do
  action :process
  where expr(processed != true)
  worker_read_action(:read)
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#oban-triggers-trigger-name){: #oban-triggers-trigger-name } | `atom` |  | A unique identifier for this trigger. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action`](#oban-triggers-trigger-action){: #oban-triggers-trigger-action .spark-required} | `atom` |  | The action to be triggered. Defaults to the identifier of the resource plus the name of the trigger |
| [`action_input`](#oban-triggers-trigger-action_input){: #oban-triggers-trigger-action_input } | `map` |  | Static inputs to supply to the update/destroy action when it is called. Any metadata produced by `read_metadata` will overwrite these values. |
| [`extra_args`](#oban-triggers-trigger-extra_args){: #oban-triggers-trigger-extra_args } | `map \| (any -> any)` |  | Additional arguments to merge into the job's arguments map. Can either be a map or a function that takes the record and returns a map. |
| [`actor_persister`](#oban-triggers-trigger-actor_persister){: #oban-triggers-trigger-actor_persister } | `:none \| module` |  | An `AshOban.PersistActor` to use to store the actor. Defaults to to the configured `config :ash_oban, :actor_persister`. Set to `:none` to override the configured default. |
| [`list_tenants`](#oban-triggers-trigger-list_tenants){: #oban-triggers-trigger-list_tenants } | `list(any) \| (-> any) \| module` |  | A list of tenants or a function behaviour that returns a list of tenants a trigger should be run for. |
| [`scheduler_queue`](#oban-triggers-trigger-scheduler_queue){: #oban-triggers-trigger-scheduler_queue } | `atom` |  | The queue to place the scheduler job in. The same queue as job is used by default (but with a priority of 1 so schedulers run first). |
| [`debug?`](#oban-triggers-trigger-debug?){: #oban-triggers-trigger-debug? } | `boolean` | `false` | If set to `true`, detailed debug logging will be enabled for this trigger. You can also set `config :ash_oban, debug_all_triggers?: true` to enable debug logging for all triggers. If the action has `transaction?: false` this is automatically false. |
| [`lock_for_update?`](#oban-triggers-trigger-lock_for_update?){: #oban-triggers-trigger-lock_for_update? } | `boolean` | `true` | If `true`, a transaction will be started before looking up the record, and it will be locked for update. Typically you should leave this on unless you have before/after/around transaction hooks. |
| [`worker_module_name`](#oban-triggers-trigger-worker_module_name){: #oban-triggers-trigger-worker_module_name } | `module` |  | The module name to be used for the generated worker. |
| [`scheduler_module_name`](#oban-triggers-trigger-scheduler_module_name){: #oban-triggers-trigger-scheduler_module_name } | `module` |  | The module name to be used for the generated scheduler. |
| [`scheduler_cron`](#oban-triggers-trigger-scheduler_cron){: #oban-triggers-trigger-scheduler_cron } | `String.t \| false` | `"* * * * *"` | A crontab configuration for when the job should run. Defaults to once per minute ("* * * * *"). Use `false` to disable the scheduler entirely. |
| [`stream_batch_size`](#oban-triggers-trigger-stream_batch_size){: #oban-triggers-trigger-stream_batch_size } | `pos_integer` |  | The batch size to pass when streaming records from using `Ash.stream!/2`. No batch size is passed if none is provided here, so the default is used. |
| [`stream_with`](#oban-triggers-trigger-stream_with){: #oban-triggers-trigger-stream_with } | `:keyset \| :offset \| :full_read` | `:keyset` | How to stream records when processing the trigger. Defaults to `:keyset`, which is the most efficient and reliable option. Use `:offset` if you need to support databases that don't support keyset pagination (e.g. MySQL). Use `:full_read` if you need to support scenarios where the `where` clause may change between batches (e.g. if it depends on time). |
| [`queue`](#oban-triggers-trigger-queue){: #oban-triggers-trigger-queue } | `atom` |  | The queue to place the job in. Defaults to the resources short name plus the name of the trigger. |
| [`record_limit`](#oban-triggers-trigger-record_limit){: #oban-triggers-trigger-record_limit } | `pos_integer` |  | If set, any given run of the scheduler will only ever schedule this many items maximum. |
| [`log_errors?`](#oban-triggers-trigger-log_errors?){: #oban-triggers-trigger-log_errors? } | `boolean` | `true` | Whether or not to log errors that occur when performing an action. |
| [`log_final_error?`](#oban-triggers-trigger-log_final_error?){: #oban-triggers-trigger-log_final_error? } | `boolean` | `true` | If true, logs that an error occurred on the final attempt to perform an action even if `log_errors?` is set to false. |
| [`worker_priority`](#oban-triggers-trigger-worker_priority){: #oban-triggers-trigger-worker_priority } | `non_neg_integer` | `2` | A number from 0 to 3, where 0 is the highest priority and 3 is the lowest. |
| [`scheduler_priority`](#oban-triggers-trigger-scheduler_priority){: #oban-triggers-trigger-scheduler_priority } | `non_neg_integer` | `3` | A number from 0 to 3, where 0 is the highest priority and 3 is the lowest. |
| [`max_scheduler_attempts`](#oban-triggers-trigger-max_scheduler_attempts){: #oban-triggers-trigger-max_scheduler_attempts } | `pos_integer` | `1` | How many times to attempt scheduling of the triggered action. |
| [`max_attempts`](#oban-triggers-trigger-max_attempts){: #oban-triggers-trigger-max_attempts } | `pos_integer` | `1` | How many times to attempt the job. After all attempts have been exhausted, the scheduler may just reschedule it. Use the `on_error` action to update the record to make the scheduler no longer apply. |
| [`trigger_once?`](#oban-triggers-trigger-trigger_once?){: #oban-triggers-trigger-trigger_once? } | `boolean` | `false` | If set to `true` `completed` is added to list of states to check for uniqueness. If the execution time of the job is very low, it's possible that jobs are executed and completed while the scheduler is running. This can lead to jobs being scheduled for resources that are already processed by the time the job gets inserted. Adding `completed` to the list of states will lead to oban ignoring the job when inserted. Only use this if nothing else is writing to the resource attribute that marks it as processsed. Because it will not be processed again as long the completed job is still in the db. You also don't need this if the job executing puts the record into a state that makes it no longer eligible for scheduling. |
| [`read_metadata`](#oban-triggers-trigger-read_metadata){: #oban-triggers-trigger-read_metadata } | `(any -> any)` |  | Takes a record, and returns metadata to be given to the update action as an argument called `metadata`. |
| [`state`](#oban-triggers-trigger-state){: #oban-triggers-trigger-state } | `:active \| :paused \| :deleted` | `:active` | Describes the state of the cron job. See the getting started guide for more information. The most important thing is that you *do not remove a trigger from a resource if you are using oban pro*. |
| [`read_action`](#oban-triggers-trigger-read_action){: #oban-triggers-trigger-read_action } | `atom` |  | The read action to use when querying records. Defaults to the primary read. This action *must* support keyset pagination. |
| [`worker_read_action`](#oban-triggers-trigger-worker_read_action){: #oban-triggers-trigger-worker_read_action } | `atom` |  | The read action to use when fetching the individual records for the trigger. Defaults to `read_action`. If you customize this, ensure your action handles scenarios where the trigger is no longer relevant. |
| [`where`](#oban-triggers-trigger-where){: #oban-triggers-trigger-where } | `any` |  | The filter expression to determine if something should be triggered |
| [`sort`](#oban-triggers-trigger-sort){: #oban-triggers-trigger-sort } | `any` |  | The sort applied to the query that determines if something should be triggered |
| [`on_error`](#oban-triggers-trigger-on_error){: #oban-triggers-trigger-on_error } | `atom` |  | An update action to call after the last attempt has failed. See the getting started guide for more. |
| [`on_error_fails_job?`](#oban-triggers-trigger-on_error_fails_job?){: #oban-triggers-trigger-on_error_fails_job? } | `boolean` | `false` | Determines if the oban job will be failed on the last attempt when there is an on_error handler that is called. If there is no on_error, then the action is always marked as failed on the last attempt. |
| [`shared_context?`](#oban-triggers-trigger-shared_context?){: #oban-triggers-trigger-shared_context? } | `boolean` |  | If set to `true`, the `ash_oban?: true` flag will be placed in shared context instead of regular context. Shared context propagates to related actions called via `manage_relationship` and can be passed to other action invocations using the context as scope, making it easier to detect AshOban execution in nested actions. If not specified, inherits the global `shared_context?` setting from the `oban` section. |
| [`use_tenant_from_record?`](#oban-triggers-trigger-use_tenant_from_record?){: #oban-triggers-trigger-use_tenant_from_record? } | `boolean` | `false` | If set to `true`, the tenant will be extracted from each record's tenant attribute and used when the worker processes that record. This allows the scheduler to use a multitenancy `:allow_global` read action to find records across all tenants, while the worker action still runs with the correct tenant context for each individual record. If not specified, inherits the global `use_tenant_from_record?` setting from the `oban` section. |
| [`worker_opts`](#oban-triggers-trigger-worker_opts){: #oban-triggers-trigger-worker_opts } | `keyword` | `[]` | Options to set on the worker. ATTENTION: this may overwrite options set by ash_oban, make sure you know what you are doing. See [Oban.Worker](https://hexdocs.pm/oban/Oban.Worker.html#module-defining-workers) for options and [Oban.Pro.Worker](https://oban.pro/docs/pro/Oban.Pro.Worker.html) for oban pro |
| [`backoff`](#oban-triggers-trigger-backoff){: #oban-triggers-trigger-backoff } | `pos_integer \| (any -> any) \| :exponential` | `:exponential` | Configure after how much time job should (in seconds) be retried in case of error if more retries available. Can be a number of seconds or a function that takes the job and returns a number of seconds. Will not be executed if default max_attempts value of 1 will be used. See [Oban.Worker](https://hexdocs.pm/oban/Oban.Worker.html#module-customizing-backoff) for more about backoff.   backoff 10   backoff fn _job -> 10 end   backoff fn %Oban.Job{attempt: attempt} -> 10 * attempt end   backoff fn %Oban.Job{attempt: attempt, unsaved_error: unsaved_error} ->     %{kind: _, reason: reason, stacktrace: _} = unsaved_error     case reason do       %MyApp.ApiError{status: 429} -> 300       _ -> trunc(:math.pow(attempt, 4))     end   end |
| [`timeout`](#oban-triggers-trigger-timeout){: #oban-triggers-trigger-timeout } | `pos_integer \| (any -> any) \| :infinity` | `:infinity` | Configure timeout for the job in milliseconds. See [Oban.Worker timeout](https://hexdocs.pm/oban/Oban.Worker.html#module-customizing-timeout) for more about timeout.   timeout 30_000   timeout fn _job -> :timer.seconds(30) end |





### Introspection

Target: `AshOban.Trigger`


### oban.scheduled_actions
A section for configured scheduled actions. Supports generic and create actions.


### Nested DSLs
 * [schedule](#oban-scheduled_actions-schedule)


### Examples
```
scheduled_actions do
  schedule :import, "0 */6 * * *", action: :import
end

```




### oban.scheduled_actions.schedule
```elixir
schedule name, cron
```








### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#oban-scheduled_actions-schedule-name){: #oban-scheduled_actions-schedule-name } | `atom` |  | A unique identifier for this scheduled action. |
| [`cron`](#oban-scheduled_actions-schedule-cron){: #oban-scheduled_actions-schedule-cron } | `String.t` |  | The schedule in crontab notation |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action_input`](#oban-scheduled_actions-schedule-action_input){: #oban-scheduled_actions-schedule-action_input } | `map` |  | Inputs to supply to the action when it is called. |
| [`action`](#oban-scheduled_actions-schedule-action){: #oban-scheduled_actions-schedule-action } | `atom` |  | The generic or create action to call when the schedule is triggered. |
| [`actor_persister`](#oban-scheduled_actions-schedule-actor_persister){: #oban-scheduled_actions-schedule-actor_persister } | `:none \| module` |  | An `AshOban.PersistActor` to use to store the actor. Defaults to to the configured `config :ash_oban, :actor_persister`. Set to `:none` to override the configured default. |
| [`worker_module_name`](#oban-scheduled_actions-schedule-worker_module_name){: #oban-scheduled_actions-schedule-worker_module_name } | `module` |  | The module name to be used for the generated worker. |
| [`queue`](#oban-scheduled_actions-schedule-queue){: #oban-scheduled_actions-schedule-queue } | `atom` |  | The queue to place the job in. Defaults to the resources short name plus the name of the scheduled action (not the action name). |
| [`state`](#oban-scheduled_actions-schedule-state){: #oban-scheduled_actions-schedule-state } | `:active \| :paused \| :deleted` | `:active` | Describes the state of the cron job. See the getting started guide for more information. The most important thing is that you *do not remove a scheduled action from a resource if you are using oban pro*. |
| [`max_attempts`](#oban-scheduled_actions-schedule-max_attempts){: #oban-scheduled_actions-schedule-max_attempts } | `pos_integer` | `1` | How many times to attempt the job. The action will receive a `last_oban_attempt?` argument on the last attempt, and you should handle errors accordingly. |
| [`priority`](#oban-scheduled_actions-schedule-priority){: #oban-scheduled_actions-schedule-priority } | `non_neg_integer` | `3` | A number from 0 to 3, where 0 is the highest priority and 3 is the lowest. |
| [`debug?`](#oban-scheduled_actions-schedule-debug?){: #oban-scheduled_actions-schedule-debug? } | `boolean` | `false` | If set to `true`, detailed debug logging will be enabled for this trigger. You can also set `config :ash_oban, debug_all_triggers?: true` to enable debug logging for all triggers. |
| [`shared_context?`](#oban-scheduled_actions-schedule-shared_context?){: #oban-scheduled_actions-schedule-shared_context? } | `boolean` |  | If set to `true`, the `ash_oban?: true` flag will be placed in shared context instead of regular context. Shared context propagates to related actions called via `manage_relationship` and can be passed to other action invocations using the context as scope, making it easier to detect AshOban execution in nested actions. If not specified, inherits the global `shared_context?` setting from the `oban` section. |





### Introspection

Target: `AshOban.Schedule`







<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>