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
- trigger
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`	`module`		The Domain to use when calling actions on this resource. Defaults to the resource's domain.
`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

Examples

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

oban.triggers.trigger

trigger name

Examples

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

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique identifier for this trigger.

Options

Name	Type	Default	Docs
`action`	`atom`		The action to be triggered. Defaults to the identifier of the resource plus the name of the 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`	`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`	`: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`	`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`	`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?`	`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?`	`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`	`module`		The module name to be used for the generated worker.
`scheduler_module_name`	`module`		The module name to be used for the generated scheduler.
`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`	`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`	`atom`		The queue to place the job in. Defaults to the resources short name plus the name of the trigger.
`record_limit`	`pos_integer`		If set, any given run of the scheduler will only ever schedule this many items maximum.
`log_errors?`	`boolean`	`true`	Whether or not to log errors that occur when performing an action.
`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`	`non_neg_integer`	`2`	A number from 0 to 3, where 0 is the highest priority and 3 is the lowest.
`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`	`pos_integer`	`1`	How many times to attempt scheduling of the triggered action.
`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?`	`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`	`(any -> any)`		Takes a record, and returns metadata to be given to the update action as an argument called `metadata`.
`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`	`atom`		The read action to use when querying records. Defaults to the primary read. This action must support keyset pagination.
`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`	`any`		The filter expression to determine if something should be triggered
`sort`	`any`		The sort applied to the query that determines if something should be triggered
`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?`	`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`	`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 for options and Oban.Pro.Worker for oban pro
`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 maxattempts value of 1 will be used. See Oban.Worker 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`	`pos_integer \| (any -> any) \| :infinity`	`:infinity`	Configure timeout for the job in milliseconds. See Oban.Worker 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

Examples

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

oban.scheduled_actions.schedule

schedule name, cron

Arguments

Name	Type	Default	Docs
`name`	`atom`		A unique identifier for this scheduled action.
`cron`	`String.t`		The schedule in crontab notation

Options

Name	Type	Default	Docs
`action_input`	`map`		Inputs to supply to the action when it is called.
`action`	`atom`		The generic or create action to call when the schedule is triggered.
`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`	`module`		The module name to be used for the generated worker.
`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`	`: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`	`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`	`non_neg_integer`	`3`	A number from 0 to 3, where 0 is the highest priority and 3 is the lowest.
`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

← Previous Page Triggers and Scheduled Actions

Next Page → Change Log