View Source Ash.Flow.Dsl (ash v2.9.20)

The built in flow DSL.

dsl-documentation
DSL Documentation

index
Index

flow
- argument
steps
- map
- branch
- transaction
- create
- debug
- update
- destroy
- validate
- read
- run_flow
- custom

docs
Docs

flow
flow

Details about the flow itself, like description and the successful return type.

argument

:api (atom/0) - An api to use by default when calling actions
:description (String.t/0) - A description of the flow
:trace_name (String.t/0) - The name to use when creating traces. Defaults to the short name.
:short_name (atom/0) - A short name to use for the flow. Defaults to the last to parts of the module name, underscored.
:returns (term/0) - The step or step that should constitute the return value.

argument
argument

An argument to be passed into the flow

Examples:

argument :params, :map do
  default %{}
end

argument :retries, :integer do
  allow_nil? false
end

:name (atom/0) - Required. The name to use for the argument
:type (term/0) - Required. The type of the argument. See Ash.Type for more.
:default - A default value to use for the argument if not provided
:allow_nil? (boolean/0) - Whether or not the argument value may be nil The default value is true.
:constraints (keyword/0) - Constraints to provide to the type when casting the value. See the type's documentation for more information. The default value is [].

steps
steps

The steps to run.

map
branch
transaction
create
debug
update
destroy
validate
read
run_flow
custom

Examples:

steps do
  # invokes a create action
  create :create_post, MyApp.Post, :create
end

Imports:

Ash.Flow.StepHelpers

map
map

Runs a set of steps for each item in a provided list.

Examples:

map :create_users, range(1, arg(:count)) do
  output :create_user

  create :create_user, Org, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end
end

:over (term/0) - The value to be iterated over. Will be available inside the map step as element(:map_step_name)
:output (atom/0) - Which step to use when constructing the output list. Defaults to the last step.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

branch
branch

Runs a set of steps based on a given value.

Examples:

branch :create_users, result(:create_users?) do
  output :create_user

  create :create_user, Org, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end
end

:condition (term/0) - A template that must evaluate to true for the branch to be executed.
:output (atom/0) - Which step to use as the output. Defaults to the last step.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

transaction
transaction

Runs a set of steps in a transaction.

Examples:

transaction :create_users do
  create :create_user, User, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end

  create :create_user, Org, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end
end

:output (term/0) - Which step or steps to use when constructing the output. Defaults to the last step.
:timeout (timeout/0) - A timeout to apply to the transaction.
:resource - The Ash resource to use for the transaction.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

create
create

Declares a step that will call a create action on a resource.

Examples:

create :create_post, MyApp.Post, :create

:upsert? (boolean/0) - Wether or not this action is always an upsert. The default value is false.
:upsert_identity (atom/0) - The identity to use for the upsert.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.
:resource (term/0) - Required. The resource to call the action on.
:action (term/0) - Required. The action to call on the resource.
:api (term/0) - The api to use when calling the action. Defaults to the api set in the flow section.
:tenant (term/0) - A tenant to use for the operation. May be a template or a literal value.
:input (term/0) - A template for the input.

debug
debug

Declares a step that will inspect its input and provide additional debug information.

Examples:

debug :show_some_information do
  input %{post: result(:create_post)}
end

:input (term/0) - A template for the input.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

update
update

Declares a step that will call a update action on a resource.

Examples:

update :update_post, MyApp.Post, :update do
  record result(:get_post)
end

:record (term/0) - Required. The record to be updated, can use template helpers, e.g result(:step_name).
If the value is nil, the step is skipped and nil is the result of the step. Any other value is used as an input record.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.
:resource (term/0) - Required. The resource to call the action on.
:action (term/0) - Required. The action to call on the resource.
:api (term/0) - The api to use when calling the action. Defaults to the api set in the flow section.
:tenant (term/0) - A tenant to use for the operation. May be a template or a literal value.
:input (term/0) - A template for the input.

destroy
destroy

Declares a step that will call a destroy action on a resource.

Examples:

destroy :destroy_post, MyApp.Post, :destroy

:record (term/0) - Required. The record to be updated, can use template helpers, e.g result(:step_name).
If the value is nil, the step is skipped and nil is the result of the step. Any other value is used as an input record.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.
:resource (term/0) - Required. The resource to call the action on.
:action (term/0) - Required. The action to call on the resource.
:api (term/0) - The api to use when calling the action. Defaults to the api set in the flow section.
:tenant (term/0) - A tenant to use for the operation. May be a template or a literal value.
:input (term/0) - A template for the input.

validate
validate

Validates some input against an action.

Examples:

validate :update_post, MyApp.Post, :update do
  record result(:get_post)
  only_keys [:name]
end

:record (term/0) - The record to be created/updated/destroyed, if relevant. can use template helpers, e.g result(:step_name).
If the value is nil and would be required by the action type, the step is skipped and nil is the result of the step. Any other value is used as an input record.
:only_keys - If the keys are set, the step will succeed as long as there are no errors for those specific fields. Additionally, only errors for those keys will be returned. Use a list for the key if you want to check for an error at a path, and use :_ to allow anything at that path
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.
:resource (term/0) - Required. The resource to call the action on.
:action (term/0) - Required. The action to call on the resource.
:api (term/0) - The api to use when calling the action. Defaults to the api set in the flow section.
:tenant (term/0) - A tenant to use for the operation. May be a template or a literal value.
:input (term/0) - A template for the input.

read
read

Declares a step that will call a read action on a resource.

Examples:

read :destroy_post, MyApp.Post, :destroy

:get? (boolean/0) - Whether or not read action is expected to return a single result or nil. If the action is configured with get? true then this is automatically set to true. The default value is false.
:not_found_error? (boolean/0) - Whether or not finding no record should result in a not found error The default value is true.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.
:resource (term/0) - Required. The resource to call the action on.
:action (term/0) - Required. The action to call on the resource.
:api (term/0) - The api to use when calling the action. Defaults to the api set in the flow section.
:tenant (term/0) - A tenant to use for the operation. May be a template or a literal value.
:input (term/0) - A template for the input.

run_flow
run_flow

Runs another flow as part of the current flow. The return value of the step is the return value of the flow.

Examples:

run_flow :get_org, GetOrgByName do
  input %{
    name: arg(:org_name)
  }

:flow (atom/0) - Required. The flow to run.
:input (term/0) - A template for the input.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

custom
custom

Runs a custom step module.

See Ash.Flow.Step for the necessary callbacks and more information.

Examples:

custom :do_custom_thing, MyApp.DoCustomThing do
  input %{...}
end

custom :do_custom_thing, {MyApp.DoCustomThing, opt1: :foo, opt2: :bar} do
  input %{...}
end

:input (term/0) - A template for the input.
:custom - The module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context.
:async? (boolean/0) - Whether or not this step can be run outside of the current process. Defaults to true. The default value is false.
:name (atom/0) - Required. The name of the step. Will be used when expressing dependencies, and step inputs.
:short_name (String.t/0) - Set a short name for the step. Will be used when building things like mermaid charts.
:wait_for (term/0) - Ensures that the step happens after the configured step or steps.
This value is just a template that isn't used, except to determine dependencies, so you can use it like this wait_for [result(:step_one), result(:step_two)] or wait_for result(:step).
:touches_resources (list of atom/0) - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for custom steps.
:halt_if (term/0) - Halts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables.
To attach a specific reason, use a halt_reason.
If you need more complex halting logic, then you'd want to use a custom step, and return {:error, Ash.Error.Flow.Halted.exception(...)}
:halt_reason (term/0) - Configures the reason for the halt_if clause. The default value is :halted.
:description (String.t/0) - A description for the step.

Settings View Source Ash.Flow.Dsl (ash v2.9.20)

dsl-documentation DSL Documentation

index Index

docs Docs

flow flow

argument argument

steps steps

map map

branch branch

transaction transaction

create create

debug debug

update update

destroy destroy

validate validate

read read

run_flow run_flow

custom custom

View Source Ash.Flow.Dsl (ash v2.9.20)

dsl-documentation
DSL Documentation

index
Index

docs
Docs

flow
flow

argument
argument

steps
steps

map
map

branch
branch

transaction
transaction

create
create

debug
debug

update
update

destroy
destroy

validate
validate

read
read

run_flow
run_flow

custom
custom