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. |


### 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. |
| [`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. |
| [`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. |





### Introspection

Target: `AshOban.Schedule`







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