AshOban

https://hexdocs.pm/ash_oban/
Admin
AshOban is an extension for integrating Ash resources with Oban, allowing users to easily execute...
Tokens:9,940
Snippets:47
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install ash_oban with Igniter

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

Command to install ash_oban and Oban using the Igniter tool. This is a convenient way to set up both dependencies.

```bash
mix igniter.install ash_oban
```

--------------------------------

### Configure AshOban for Oban

Source: https://hexdocs.pm/ash_oban/AshOban

Alters the Oban configuration to include necessary AshOban setup. The `config/3` function can optionally enforce the definition of queues and plugins in the Oban configuration, aiding in distributed queue management. This is a key step for integrating AshOban into an existing Oban setup.

```elixir
config(domains, base, opts \\ [])
```

--------------------------------

### Define Scheduled Actions with Cron

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

This example demonstrates how to define a scheduled action using the `scheduled_actions` block. It specifies a cron schedule for running an import action every 6 hours.

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

--------------------------------

### Define ash_oban Trigger in Resource

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

Example of defining an Oban trigger within an Ash resource. This allows you to schedule actions based on resource state and cron expressions.

```elixir
defmodule MyApp.Resource do
  use Ash.Resource, domain: MyDomain, extensions: [AshOban]

  ... 

  oban do
    triggers do
      # add a trigger called :process
      trigger :process do
        # this trigger calls the `process` action
        action :process
        # for any record that has `processed != true`
        where expr(processed != true)
        # checking for matches every minute
        scheduler_cron "* * * * *"
        on_error :errored
      end
    end
  end
end
```

--------------------------------

### Define Elixir Function for Subscription Notifications

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

An example Elixir function to send subscription expiration notifications. This approach has limitations regarding failure handling, retries, and state tracking, which AshOban aims to address.

```elixir
def send_subscription_expiration_notification(user) do
  Subscription
  |> Ash.Query.for_read(:subscriptions_about_to_expire)
  |> Ash.stream!()
  |> Enum.each(&send_expiring_subscription_email/1)
end
```

--------------------------------

### Ash Oban: Configure Actor Persister on Individual Trigger

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This example demonstrates how to configure an `actor_persister` on an individual Ash Oban trigger. By specifying `actor_persister MyApp.AshObanActorPersister` within the trigger definition, you can override the global configuration for that specific trigger. This allows for fine-grained control over actor persistence when needed.

```elixir
trigger :name do
  ...
  actor_persister MyApp.AshObanActorPersister
end
```

--------------------------------

### Bypass Ash Oban Authorization Checks

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This code snippet demonstrates how to bypass the default authorization checks in Ash Oban by installing a bypass within your policies. This is useful for reverting to older behavior or for specific authorization strategies. It requires defining a policy bypass for `AshOban.Checks.AshObanInteraction` and setting `authorize_if` to `always()` to ensure the bypass is active.

```elixir
policies do
  bypass AshOban.Checks.AshObanInteraction do
    authorize_if always()
  end

  ...the rest of your policies
end
```

--------------------------------

### Configure Oban Pro for ash_oban

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

Configuration for using ash_oban with Oban Pro. Set the :pro? option to true if you are using Oban Pro.

```elixir
config :ash_oban, :pro?, true
```

--------------------------------

### AshOban Configuration

Source: https://hexdocs.pm/ash_oban/AshOban

Configures Oban to include AshOban's requirements, optionally controlling queue and plugin definitions.

```APIDOC
## POST /config

### Description
Alters your Oban configuration to include the required AshOban configuration. This function is crucial for setting up AshOban within your Oban workers.

### Method
POST

### Endpoint
`/config`

### Parameters
#### Query Parameters
- **domains** (list) - Required - A list of domains to configure.
- **base** (atom) - Required - The base configuration atom for Oban.
- **opts** (map) - Optional - Additional options for configuration.
  - **require?** (boolean) - Optional - Whether to require queues and plugins to be defined in your Oban config. Defaults to `true`.

### Request Example
```json
{
  "domains": ["MyApp.UserDomain"],
  "base": :my_oban_base,
  "opts": {
    "require?": false
  }
}
```

### Response
#### Success Response (200)
This function modifies the Oban configuration in place and does not return a specific value.

#### Response Example
(No direct response body, configuration is updated)
```

--------------------------------

### Update Application Configuration for AshOban

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

Modify your Application module to integrate AshOban's configuration with Oban. This ensures Oban uses AshOban's scheduling logic.

```elixir
# Replace this
{Oban, your_oban_config}

# With this
{Oban, AshOban.config(Application.fetch_env!(:my_app, :ash_domains), your_oban_config)}
# OR this, to selectively enable AshOban only for specific domains
{Oban, AshOban.config([YourDomain, YourOtherDomain], your_oban_config)}
```

--------------------------------

### AshOban Trigger Options

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Detailed explanations of the configuration options for AshOban triggers.

```APIDOC
## AshOban Trigger Configuration Options

This document outlines the various options available for configuring triggers in AshOban, allowing for fine-grained control over job scheduling and execution.

### Trigger Options

#### `action`
- **Type**: `atom`
- **Default**: The identifier of the resource plus the name of the trigger.
- **Description**: The action to be triggered.

#### `action_input`
- **Type**: `map`
- **Default**: None
- **Description**: 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`
- **Type**: `map | (any -> any)`
- **Default**: None
- **Description**: 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`
- **Type**: `:none | module`
- **Default**: Configured `config :ash_oban, :actor_persister`.
- **Description**: 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`
- **Type**: `list(any) | (-> any) | module`
- **Default**: None
- **Description**: A list of tenants or a function behavior that returns a list of tenants a trigger should be run for.

#### `scheduler_queue`
- **Type**: `atom`
- **Default**: The same queue as the job (but with a priority of 1 so schedulers run first).
- **Description**: The queue to place the scheduler job in.

#### `debug?`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: 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?`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: 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`
- **Type**: `module`
- **Default**: None
- **Description**: The module name to be used for the generated worker.

#### `scheduler_module_name`
- **Type**: `module`
- **Default**: None
- **Description**: The module name to be used for the generated scheduler.

#### `scheduler_cron`
- **Type**: `String.t | false`
- **Default**: `"* * * * *"`
- **Description**: A crontab configuration for when the job should run. Defaults to once per minute ("* * * *"). Use `false` to disable the scheduler entirely.

#### `stream_batch_size`
- **Type**: `pos_integer`
- **Default**: None
- **Description**: 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`
- **Type**: `atom`
- **Default**: The resource's short name plus the name of the trigger.
- **Description**: The queue to place the job in.

#### `record_limit`
- **Type**: `pos_integer`
- **Default**: None
- **Description**: If set, any given run of the scheduler will only ever schedule this many items maximum.

#### `log_errors?`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: Whether or not to log errors that occur when performing an action.

#### `log_final_error?`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: 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`
- **Type**: `non_neg_integer`
- **Default**: `2`
- **Description**: A number from 0 to 3, where 0 is the highest priority and 3 is the lowest.

#### `scheduler_priority`
- **Type**: `non_neg_integer`
- **Default**: `3`
- **Description**: A number from 0 to 3, where 0 is the highest priority and 3 is the lowest.

#### `max_scheduler_attempts`
- **Type**: `pos_integer`
- **Default**: `1`
- **Description**: How many times to attempt scheduling of the triggered action.

#### `max_attempts`
- **Type**: `pos_integer`
- **Default**: `1`
- **Description**: 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?`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: If set to `true`, `completed` is added to the 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 processed. 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`
- **Type**: `(any -> any)`
- **Default**: None
- **Description**: Takes a record, and returns metadata to be given to the update action as an argument called `metadata`.

#### `state`
- **Type**: `:active | :paused | :deleted`
- **Default**: `:active`
- **Description**: 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`
- **Type**: `atom`
- **Default**: The primary read.
- **Description**: The read action to use when querying records. Defaults to the primary read. This action _must_ support keyset pagination.

#### `worker_read_action`
- **Type**: `atom`
- **Default**: `read_action`
- **Description**: 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`
- **Type**: `any`
- **Default**: None
- **Description**: The filter expression to determine if something should be triggered.

#### `sort`
- **Type**: `any`
- **Default**: None
- **Description**: The sort applied to the query that determines if something should be triggered.

```

--------------------------------

### Schedule and Run Triggers

Source: https://hexdocs.pm/ash_oban/AshOban

This endpoint allows scheduling and running triggers for specified resources, domains, or OTP applications. It supports various options for controlling the execution flow and queueing behavior.

```APIDOC
## Schedule and Run Triggers

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

### Method
POST (assumed, typically for actions that modify state or trigger processes)

### Endpoint
/websites/hexdocs_pm_ash_oban/schedule_and_run_triggers

### Parameters
#### Query Parameters
- **resources_or_domains_or_otp_apps** (triggerable() | [triggerable()]) - Required - The resource, domain, OTP app, or a list thereof to schedule triggers for.
- **opts** (keyword()) - Optional - A keyword list of options to configure the scheduling and execution.

#### Request Body
(Not explicitly defined in the provided text, typically inferred from function arguments or handled implicitly)

### Request Example
(No specific request body example provided. A potential representation might be:
```json
{
  "resources_or_domains_or_otp_apps": "MyApp.Resources.User",
  "opts": {
    "drain_queues?": true,
    "scheduled_actions?": true
  }
}
```
)

### Response
#### Success Response (200)
- **result** (result()) - The result of the trigger scheduling and execution process.

#### Response Example
(No specific response example provided. The `result()` type would dictate the structure.)

### Options Details
- `drain_queues?` (boolean) - Defaults to `false`. Drains the queues after scheduling. Primarily for testing.
- `queue` (any) - Passed through to `Oban.drain_queue/2`.
- `with_limit` (integer) - Passed through to `Oban.drain_queue/2`.
- `with_recursion` (integer) - Passed through to `Oban.drain_queue/2`.
- `with_safety` (integer) - Passed through to `Oban.drain_queue/2`.
- `with_scheduled` (boolean) - Passed through to `Oban.drain_queue/2`.
- `scheduled_actions?` (boolean) - Defaults to `false`. Schedules all applicable scheduled actions unless a scheduled action name was explicitly provided.
- `triggers?` (boolean) - Defaults to `true`. Schedules all applicable scheduled actions.
- `actor` (any) - The actor to schedule and run the triggers with.
- `oban` (module) - The Oban module to use. Defaults to `Oban`.

### Input Handling
- **List**: Each item is passed into `schedule_and_run_triggers/1`, and results are merged.
- **OTP App**: Each domain configured in the `ash_domains` of the OTP app is passed into `schedule_and_run_triggers/1`, and results are merged.
- **Domain**: Each resource configured in that domain is passed into `schedule_and_run_triggers/1`, and results are merged.
- **Tuple {resource, :trigger_name}**: That specific trigger is scheduled, and results are merged.
- **Resource**: Each trigger configured in that resource is scheduled, and results are merged.
```

--------------------------------

### Add ash_oban Dependency

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This snippet shows how to add the ash_oban dependency to your Elixir project's mix.exs file.

```elixir
{:ash_oban, "~> 0.4.12"}
```

--------------------------------

### AshOban Transaction Reasons

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

Illustrates the transaction reasons added by AshOban for tracking triggered records and errors during processing.

```elixir
%{
  type: :ash_oban_trigger,
  metadata: %{
    resource: Resource,
    trigger: :trigger_name,
    primary_key: %{primary_key_fields: value}
  }
}

and

%{
  type: :ash_oban_trigger_error,
  metadata: %{
    resource: Resource
    trigger: :trigger_name,
    primary_key: %{primary_key_fields: value},
    error: <the error (this will be an ash error class)>
  }
}
```

--------------------------------

### Trigger Management

Source: https://hexdocs.pm/ash_oban/AshOban

Functions for building, running, and scheduling triggers associated with Ash resources.

```APIDOC
## POST /triggers/build

### Description
Builds a specific trigger for the record provided, but does not insert it into the database. This is useful for inspecting or manipulating trigger data before persistence.

### Method
POST

### Endpoint
`/triggers/build`

### Parameters
#### Request Body
- **record** (Ash.Resource.t | triggerable()) - Required - The Ash resource or triggerable from which to build the trigger.
- **trigger** (atom) - Required - The name of the trigger to build.
- **opts** (map) - Optional - Options to customize the trigger building process.
  - **actor** (any) - Optional - The actor to set on the job. Requires configuring an actor persister.
  - **tenant** (any) - Optional - The tenant to set on the job.
  - **action_arguments** (map) - Optional - Additional arguments to merge into the action invocation's arguments map. Affects uniqueness checks for the job.
  - **args** (map) - Optional - Additional arguments to merge into the job's arguments map. Does not affect the action, only job uniqueness checks.

### Request Example
```json
{
  "record": "%MyApp.User{id: 1}",
  "trigger": :send_welcome_email,
  "opts": {
    "actor": "%MyApp.Actor{id: 1}",
    "tenant": "tenant1"
  }
}
```

### Response
#### Success Response (200)
- **trigger_data** (map) - The constructed trigger data, ready for scheduling or inspection.

#### Response Example
```json
{
  "trigger_data": {
    "module": "MyApp.Triggers.SendWelcomeEmail",
    "args": {
      "record_id": 1,
      "actor_id": 1,
      "tenant": "tenant1"
    }
  }
}
```
```

```APIDOC
## POST /triggers/run

### Description
Runs a specific trigger for the record or records provided. This function executes the trigger immediately.

### Method
POST

### Endpoint
`/triggers/run`

### Parameters
#### Request Body
- **record** (Ash.Resource.t | triggerable() | [Ash.Resource.t | triggerable()]) - Required - The Ash resource or a list of resources for which to run the trigger.
- **trigger** (atom) - Required - The name of the trigger to run.
- **opts** (map) - Optional - Options passed through to `build_trigger/3`.

### Request Example
```json
{
  "record": "%MyApp.User{id: 1}",
  "trigger": :send_welcome_email,
  "opts": {}
}
```

### Response
#### Success Response (200)
- **result** (AshOban.result()) - A map detailing the outcome of the trigger execution (e.g., success, failure counts).

#### Response Example
```json
{
  "result": {
    "discard": 0,
    "cancelled": 0,
    "success": 1,
    "failure": 0,
    "snoozed": 0,
    "queues_not_drained": []
  }
}
```
```

```APIDOC
## POST /triggers/schedule

### Description
Schedules all relevant jobs for the provided trigger or scheduled action. This queues the jobs in Oban for later execution.

### Method
POST

### Endpoint
`/triggers/schedule`

### Parameters
#### Request Body
- **resource** (Ash.Resource.t | triggerable()) - Required - The Ash resource or triggerable for which to schedule jobs.
- **trigger** (atom) - Required - The name of the trigger or scheduled action.
- **opts** (map) - Optional - Options to customize the scheduling process.
  - **actor** (any) - Optional - The actor to set on the job. Requires configuring an actor persister.
  - **action_arguments** (map) - Optional - Additional arguments to merge into the action invocation's arguments map. Affects uniqueness checks for the job. This only affects scheduled actions.

### Request Example
```json
{
  "resource": "%MyApp.User{id: 1}",
  "trigger": :send_welcome_email,
  "opts": {
    "actor": "%MyApp.Actor{id: 1}"
  }
}
```

### Response
#### Success Response (200)
This function schedules jobs and typically returns `:ok` or a similar confirmation.

#### Response Example
```json
{
  "status": "scheduled"
}
```
```

```APIDOC
## POST /triggers/schedule_and_run

### Description
Runs the schedulers for the given resource, domain, or otp_app, or list of resources, domains, or otp_apps. This function schedules and then attempts to run the jobs.

### Method
POST

### Endpoint
`/triggers/schedule_and_run`

### Parameters
#### Request Body
- **resources_or_domains_or_otp_apps** (list) - Required - A list of resources, domains, or OTP apps to process.
- **opts** (map) - Optional - Options to customize the scheduling and running process.

### Request Example
```json
{
  "resources_or_domains_or_otp_apps": ["MyApp.Resource", :my_domain],
  "opts": {}
}
```

### Response
#### Success Response (200)
- **result** (AshOban.result()) - A map detailing the outcome of the trigger execution (e.g., success, failure counts).

#### Response Example
```json
{
  "result": {
    "discard": 0,
    "cancelled": 0,
    "success": 1,
    "failure": 0,
    "snoozed": 0,
    "queues_not_drained": []
  }
}
```
```

--------------------------------

### Define Generic AshOban Action for Imports

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Defines a generic AshOban action named `:import_from_github` using a function. This action encapsulates the logic for importing data from an external service, to be scheduled later.

```elixir
action :import_from_github do
  run fn _input, _ ->
    # import logic here
  end
end
```

--------------------------------

### Run AshOban triggers

Source: https://hexdocs.pm/ash_oban/AshOban

Provides functions to directly run AshOban triggers, either for a single record or multiple records. These functions delegate to `build_trigger/3` for the core logic and accept similar options for customization. This allows for immediate execution of triggers outside the standard scheduling mechanism.

```elixir
run_trigger(record, trigger, opts \\ [])
run_triggers(records, trigger, opts \\ [])
```

--------------------------------

### Configure Oban Triggers and Scheduled Actions

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Defines Oban triggers and scheduled actions within a configuration block. It specifies the action to perform, conditions for execution, and how to read worker data. This configuration ensures that jobs are processed correctly by Oban.

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

--------------------------------

### __oban.scheduled_actions

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Configures scheduled actions for Oban jobs within Ash.

```APIDOC
## __oban.scheduled_actions

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

### Nested DSLs
* schedule

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

### Introspection
Target: `AshOban.Trigger`
```

--------------------------------

### Configure Job Timeout

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Shows how to set the timeout for an Oban job. The timeout can be specified in milliseconds or as a function that returns the timeout duration in milliseconds, allowing for dynamic timeout configurations.

```elixir
timeout 30_000
timeout fn _job -> :timer.seconds(30) end
```

--------------------------------

### Configure Job Backoff Strategy

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Illustrates different ways to configure the backoff strategy for Oban jobs. This includes using a fixed number of seconds, a function that takes the job, or a more complex function that inspects the job's unsaved error to determine the retry delay.

```elixir
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
```

--------------------------------

### Create AshOban.Errors.TriggerNoLongerApplies Exception (Elixir)

Source: https://hexdocs.pm/ash_oban/AshOban.Errors

Demonstrates how to create an instance of the `AshOban.Errors.TriggerNoLongerApplies` exception without raising it. This function takes keyword options as input and returns a `%AshOban.Errors.TriggerNoLongerApplies` struct. This is useful for capturing error states programmatically.

```elixir
@spec exception(opts :: Keyword.t()) :: %AshOban.Errors.TriggerNoLongerApplies{
  __exception__: true,
  bread_crumbs: term(),
  class: term(),
  path: term(),
  splode: term(),
  stacktrace: term(),
  vars: term()
}
```

Create an `Elixir.AshOban.Errors.TriggerNoLongerApplies` without raising it.
```

--------------------------------

### Define Oban Triggers

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Configures Oban triggers using a dedicated DSL. This snippet shows how to define a trigger named `:process`, specifying the associated action, a condition using an expression, and a worker read action.

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

--------------------------------

### Oban Worker Options

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Options that can be passed to an Oban Worker when configuring scheduled actions.

```APIDOC
## Oban Worker Options

### Description
These options can be configured for Oban jobs triggered by scheduled actions.

### Options
- **on_error** (atom) - Optional - An update action to call after the last attempt has failed.
- **on_error_fails_job?** (boolean) - Optional - Defaults to `false`. Determines if the Oban job will be failed on the last attempt when there is an `on_error` handler.
- **worker_opts** (keyword) - Optional - Defaults to `[]`. Options to set on the worker. Be cautious as this may overwrite options set by `ash_oban`.
- **backoff** (pos_integer | (any -> any) | :exponential) - Optional - Defaults to `:exponential`. Configures the retry interval in seconds after an error. Can be a number, a function that takes the job and returns seconds, or a function that handles specific errors.
- **timeout** (pos_integer | (any -> any) | :infinity) - Optional - Defaults to `:infinity`. Configures the job timeout in milliseconds.
```

--------------------------------

### Schedule Generic AshOban Action for Imports

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Schedules the `:import_from_github` action to run every 6 hours using cron syntax. It specifies the worker module responsible for executing the action.

```elixir
schedule :import_from_github, "0 */6 * * *" do
  worker_module_name AshOban.Test.Triggered.AshOban.ActionWorker.SayHello
end
```

--------------------------------

### Ash Oban: Configure Global Actor Persister

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This configuration snippet shows how to set a global actor persister for Ash Oban using `config/runtime.exs`. By setting `:actor_persister` under `:ash_oban`, all Oban triggers will use the specified module (e.g., `MyApp.AshObanActorPersister`) for actor persistence. This is the simplest way to ensure consistent actor handling across all triggers.

```elixir
config :ash_oban, :actor_persister, MyApp.AshObanActorPersister
```

--------------------------------

### Schedule and run AshOban triggers

Source: https://hexdocs.pm/ash_oban/AshOban

Executes the schedulers for the provided resources, domains, or OTP applications. This function can accept a single item or a list of items. It orchestrates the scheduling and potential immediate running of Oban jobs based on AshOban configurations.

```elixir
schedule_and_run_triggers(resources_or_domains_or_otp_apps, opts \\ [])
do_schedule_and_run_triggers(resources_or_domains_or_otp_apps, opts)
```

--------------------------------

### Schedule and Run Triggers with Ash Oban

Source: https://hexdocs.pm/ash_oban/AshOban

The `schedule_and_run_triggers/2` function allows for scheduling and running Oban jobs based on provided resources, domains, or OTP applications. It supports various options for draining queues, limiting concurrency, and specifying the actor or Oban module to use. The function can handle single or multiple inputs, including OTP applications, domains, resources, and specific 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.
"""

```

--------------------------------

### Module Name Management

Source: https://hexdocs.pm/ash_oban/AshOban

Utilities for managing module names associated with Oban jobs to prevent data loss during renames.

```APIDOC
## POST /module_names/set_defaults

### Description
Sets the default module names for AshOban triggers and scheduled actions. This is recommended to prevent "dangling" jobs when resource or trigger names change.

### Method
POST

### Endpoint
`/module_names/set_defaults`

### Parameters
(No parameters required for this action)

### Request Example
```json
{}
```

### Response
#### Success Response (200)
This operation configures module names and typically returns a success confirmation.

#### Response Example
```json
{
  "status": "module_names_set"
}
```
```

--------------------------------

### Ash Oban: Implement Custom Actor Persister

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This Elixir module implements a custom actor persister for Ash Oban, enabling the persistence of actors (like users) along with jobs. It defines `store/1` to convert an actor (e.g., a `MyApp.User` struct) into a JSON-encodable format and `lookup/1` to reconstruct the actor from the encoded format. The `lookup/1` function also handles `nil` input for cases where no actor was initially present.

```elixir
defmodule MyApp.AshObanActorPersister do
  use AshOban.ActorPersister

  def store(%MyApp.User{id: id}), do: %{"type" => "user", "id" => id}

  def lookup(%{"type" => "user", "id" => id}), do: MyApp.Accounts.get_user_by_id(id)

  # This allows you to set a default actor
  # in cases where no actor was present
  # when scheduling.
  def lookup(nil), do: {:ok, nil}
end
```

--------------------------------

### Define a Specific Oban Trigger

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Demonstrates the definition of a single Oban trigger with a specific name. It includes the action to be performed, a filtering condition, and the method for reading data from the worker.

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

--------------------------------

### Job Execution Control

Source: https://hexdocs.pm/ash_oban/AshOban

Functions to directly run or schedule Oban jobs, bypassing some trigger-specific logic.

```APIDOC
## POST /jobs/run

### Description
Runs a specific Oban job directly. This is a lower-level function for executing jobs.

### Method
POST

### Endpoint
`/jobs/run`

### Parameters
#### Request Body
- **body** (map) - Required - The job body to be executed by Oban.

### Request Example
```json
{
  "body": {
    "module": "MyApp.Workers.ProcessData",
    "args": {"data_id": 123},
    "queue": "default"
  }
}
```

### Response
#### Success Response (200)
- **result** (AshOban.result()) - A map detailing the outcome of the job execution.

#### Response Example
```json
{
  "result": {
    "discard": 0,
    "cancelled": 0,
    "success": 1,
    "failure": 0,
    "snoozed": 0,
    "queues_not_drained": []
  }
}
```
```

--------------------------------

### Configure AshOban Trigger for Subscription Notifications

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Configures an AshOban trigger named `:send_subscription_expiration_notification`. It uses cron syntax for scheduling, specifies the action to perform, applies a `where` condition based on calculations, and defines worker and scheduler modules.

```elixir
oban do
  triggers do
    trigger :send_subscription_expiration_notification do
      # Defaults to an aggressive every one minute currently
      # This default will change in the future major version release
      scheduler_cron "@daily"
      action :send_subscription_expiration_notification
      where expr(should_send_expiring_subscription_email)
      read_action :read
      worker_module_name __MODULE__.Process.Worker
      scheduler_module_name __MODULE__.Process.Scheduler
    end
  end
end
```

--------------------------------

### Store Actor with Ash Oban

Source: https://hexdocs.pm/ash_oban/AshOban

The `store_actor/3` function is used to persist actor data. It takes arguments, the actor itself, and an optional actor persister module. This function is essential for managing the state of actors within the Ash Oban framework.

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

```

--------------------------------

### __oban.scheduled_actions.schedule

Source: https://hexdocs.pm/ash_oban/dsl-ashoban

Defines a specific scheduled action with its name and cron schedule.

```APIDOC
## __oban.scheduled_actions.schedule

### Description
Configures a scheduled job with a given name and cron schedule.

### Method Signature
`schedule name, cron`

### Arguments
#### Path Parameters
- **name** (atom) - Required - A unique identifier for this scheduled action.
- **cron** (String.t) - Required - The schedule in crontab notation.

#### Options
- **action_input** (map) - Optional - Inputs to supply to the action when it is called.
- **action** (atom) - Optional - The generic or create action to call when the schedule is triggered.
- **actor_persister** (:none | module) - Optional - An `AshOban.PersistActor` to use to store the actor. Defaults to the configured `config :ash_oban, :actor_persister`. Set to `:none` to override the configured default.
- **worker_module_name** (module) - Optional - The module name to be used for the generated worker.
- **queue** (atom) - Optional - The queue to place the job in. Defaults to the resource's short name plus the name of the scheduled action.
- **state** (:active | :paused | :deleted) - Optional - Defaults to `:active`. Describes the state of the cron job. See the getting started guide for more information.
- **max_attempts** (pos_integer) - Optional - Defaults to `1`. How many times to attempt the job.
- **priority** (non_neg_integer) - Optional - Defaults to `3`. A number from 0 to 3, where 0 is the highest priority and 3 is the lowest.
- **debug?** (boolean) - Optional - Defaults to `false`. If set to `true`, detailed debug logging will be enabled for this trigger.

### Introspection
Target: `AshOban.Schedule`
```

--------------------------------

### Actor Management

Source: https://hexdocs.pm/ash_oban/AshOban

Functions for storing and looking up actors, which can be associated with Oban jobs.

```APIDOC
## POST /actors/store

### Description
Stores actor information, potentially for association with Oban jobs. Requires an actor persister to be configured.

### Method
POST

### Endpoint
`/actors/store`

### Parameters
#### Request Body
- **args** (map) - Required - Arguments related to the actor storage.
- **actor** (any) - Required - The actor data to store.
- **actor_persister** (module() | :none | nil) - Optional - The module responsible for persisting actors. Defaults to `nil`.

### Request Example
```json
{
  "args": {"user_id": 1},
  "actor": "%MyApp.Actor{id: 1}",
  "actor_persister": "MyApp.ActorPersister"
}
```

### Response
#### Success Response (200)
This operation stores actor data and typically returns a confirmation.

#### Response Example
```json
{
  "status": "actor_stored"
}
```
```

```APIDOC
## POST /actors/lookup

### Description
Looks up actor information based on provided JSON data. Requires an actor persister to be configured if not `:none` or `nil`.

### Method
POST

### Endpoint
`/actors/lookup`

### Parameters
#### Request Body
- **actor_json** (any) - Required - The JSON representation of the actor to look up.
- **actor_persister** (module() | :none | nil) - Optional - The module responsible for persisting actors. Defaults to `nil`.

### Request Example
```json
{
  "actor_json": "{\"id\": 1, \"name\": \"Test Actor\"}",
  "actor_persister": "MyApp.ActorPersister"
}
```

### Response
#### Success Response (200)
- **actor** (any) - The retrieved actor data.

#### Response Example
```json
{
  "actor": "%MyApp.Actor{id: 1}"
}
```
```

--------------------------------

### Schedule Oban jobs for Ash triggers

Source: https://hexdocs.pm/ash_oban/AshOban

Schedules all relevant Oban jobs for a given Ash trigger or scheduled action. It accepts options such as `:actor` for setting the job's actor and `:action_arguments` for influencing uniqueness checks. This function is crucial for integrating Ash's declarative resource definitions with Oban's background job processing.

```elixir
schedule(resource, trigger, opts \\ [])
```

--------------------------------

### Define authorize?() function signature

Source: https://hexdocs.pm/ash_oban/AshOban

Specifies the function signature for 'authorize?'. This function is expected to return a boolean value, indicating whether an authorization check passes or fails. Its exact implementation and context are not provided here, but it's a standard Elixir type specification.

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

--------------------------------

### Define triggerable() type for AshOban

Source: https://hexdocs.pm/ash_oban/AshOban

Defines the 'triggerable' type, which represents entities that can be used to trigger Oban jobs. This includes Ash Resources, tuples of Ash Resources and atoms, Ash Domains, or simply atoms. This type is used to specify which resources or domains should have their triggers scheduled or run.

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

--------------------------------

### Build AshOban trigger without insertion

Source: https://hexdocs.pm/ash_oban/AshOban

Constructs a specific Oban trigger for a given record and trigger definition without immediately inserting it into the database. This function accepts various options like `:actor`, `:tenant`, and `:action_arguments` to customize the trigger's behavior and metadata. It's useful for pre-building triggers for inspection or further manipulation.

```elixir
build_trigger(record, trigger, opts \\ [])
```

--------------------------------

### Define lookup_actor() function signature

Source: https://hexdocs.pm/ash_oban/AshOban

Defines the type specification for the 'lookup_actor' function. It takes a JSON representation of an actor and an optional actor persister module, returning any type. This is used for retrieving actor information, likely within the context of Oban jobs.

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

--------------------------------

### Define Ash Calculations for Subscription Expiration Logic

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Implements Elixir calculations within an Ash resource to determine if a subscription is expiring soon and if an email notification should be sent based on expiration date and last sent time.

```elixir
calculations do
  calculate :subscription_expires_soon, :boolean do
    calculation expr(
      expires_at < from_now(30, :day)
    )
  end

  calculate :should_send_expiring_subscription_email, :boolean do
    calculation expr(
      subscription_expires_soon and
      (is_nil(last_subscription_expiration_notification_sent_at) ||
        last_subscription_expiration_notification_sent_at < ago(30, :day))
    )
  end
end
```

--------------------------------

### Bypass AshObanInteraction Policies in Elixir

Source: https://hexdocs.pm/ash_oban/AshOban.Checks

This Elixir code snippet demonstrates how to bypass the AshObanInteraction check within Ash policies. It leverages the `policies do ... end` block to conditionally authorize actions when the internal ash_oban context is present. This is useful for creating exceptions in policy enforcement for internal `ash_oban` operations.

```elixir
policies do
  bypass AshObanInteraction do
    authorize_if always()
  end
end
```

--------------------------------

### Define Ash Action for Sending Subscription Notifications

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Defines an Ash action named `:send_subscription_expiration_notification` using a `change` to encapsulate the logic for sending emails. This action is intended to be triggered by AshOban.

```elixir
# on `Subscription`
#
# now we have a well defined action that expresses this logic
update :send_subscription_expiration_notification do
  change SendExpiringSubscriptionEmail
end
```

--------------------------------

### Define result() type for Oban Jobs

Source: https://hexdocs.pm/ash_oban/AshOban

Defines the structure for the result of an Oban job, including counts for discarded, cancelled, successful, failed, and snoozed jobs, as well as a list of queues that were not drained. This type is essential for understanding job outcomes.

```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()]
}
```

--------------------------------

### Ash Oban: Disable Actor Persister on Trigger

Source: https://hexdocs.pm/ash_oban/getting-started-with-ash-oban

This code snippet shows how to disable the actor persister for a specific Ash Oban trigger by setting `actor_persister :none`. This effectively overrides any global `actor_persister` configuration for that trigger, ensuring no actor persistence is attempted for this particular trigger.

```elixir
trigger :name do
  ...
  actor_persister :none
end
```

--------------------------------

### Define Ash Attributes for Notification State

Source: https://hexdocs.pm/ash_oban/triggers-and-scheduled-actions

Adds a `:last_subscription_expiration_notification_sent_at` attribute to the `Subscription` Ash resource. This attribute tracks the last time a notification was sent, enabling logic for resending.

```elixir
attributes do
  attribute :last_subscription_expiration_notification_sent_at, :utc_datetime_usec
  ...
end
```
Tokens:
Raw