# DSL: Ash.Flow.Dsl The built in flow DSL. ## Halting Steps can be halted, which will stop the flow from continuing and return a halted flow. 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(...)}` ## flow Details about the flow itself, like description and the successful return type. ### Nested DSLs * [argument](#flow-argument) ### Options

Name	Type	Docs
api	`module`	An api to use by default when calling actions
description	`String.t`	A description of the flow
trace_name	`String.t`	The name to use when creating traces. Defaults to the short name.
short_name	`atom`	A short name to use for the flow. Defaults to the last to parts of the module name, underscored.
returns	`any`	The step or step that should constitute the return value.

## flow.argument ```elixir argument name, type ``` An argument to be passed into the flow ### Examples ``` argument :params, :map do default %{} end ``` ``` argument :retries, :integer do allow_nil? false end ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name to use for the argument
type ^*	`module`		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
default	`(-> any) \| mfa \| any()`		A default value to use for the argument if not provided
allow_nil?	`boolean`	`true`	Whether or not the argument value may be nil
constraints	`Keyword.t`	`[]`	Constraints to provide to the type when casting the value. See the type's documentation for more information.

### Introspection Target: `Ash.Flow.Argument` ## steps The steps to run. ### Nested DSLs * [map](#steps-map) * [branch](#steps-branch) * [transaction](#steps-transaction) * [create](#steps-create) * [debug](#steps-debug) * [update](#steps-update) * [destroy](#steps-destroy) * [validate](#steps-validate) * [read](#steps-read) * [run_flow](#steps-run_flow) * [custom](#steps-custom) ### Examples ``` steps do # invokes a create action create :create_post, MyApp.Post, :create end ``` ## steps.map ```elixir map name, over ``` 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 ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.
over	`any`		The value to be iterated over. Will be available inside the `map` step as `element(:map_step_name)`

### Options

Name	Type	Default	Docs
output	`atom`		Which step to use when constructing the output list. Defaults to the last step.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.Map` ## steps.branch ```elixir branch name, condition ``` 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 ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.
condition	`any`		A template that must evaluate to `true` for the branch to be executed.

### Options

Name	Type	Default	Docs
output	`atom`		Which step to use as the output. Defaults to the last step.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.Branch` ## steps.transaction ```elixir transaction name, resource ``` 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 ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.
resource	`module \| list(module)`		The Ash resource to use for the transaction.

### Options

Name	Type	Default	Docs
output	`any`		Which step or steps to use when constructing the output. Defaults to the last step.
timeout	`timeout`		A timeout to apply to the transaction.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.Transaction` ## steps.create ```elixir create name, resource, action ``` Declares a step that will call a create action on a resource. ### Examples ``` create :create_post, MyApp.Post, :create ``` ### Arguments

Name	Type	Docs
name ^*	`atom`	The name of the step. Will be used when expressing dependencies, and step inputs.
resource ^*	`any`	The resource to call the action on.
action ^*	`any`	The action to call on the resource.

### Options

Name	Type	Default	Docs
upsert?	`boolean`	`false`	Whether or not this action is always an upsert.
upsert_identity	`atom`		The identity to use for the upsert.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.
api	`any`		The api to use when calling the action. Defaults to the api set in the `flow` section.
tenant	`any`		A tenant to use for the operation. May be a template or a literal value.
input	`any`		A template for the input.

### Introspection Target: `Ash.Flow.Step.Create` ## steps.debug ```elixir debug name ``` 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 ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.

### Options

Name	Type	Default	Docs
input	`any`		A template for the input.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
halt_if	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.Debug` ## steps.update ```elixir update name, resource, action ``` 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 ``` ### Arguments

Name	Type	Docs
name ^*	`atom`	The name of the step. Will be used when expressing dependencies, and step inputs.
resource ^*	`any`	The resource to call the action on.
action ^*	`any`	The action to call on the resource.

### Options

Name	Type	Default	Docs
record ^*	`any`		The record to be updated, can use template helpers, e.g `result(:step_name)`.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.
api	`any`		The api to use when calling the action. Defaults to the api set in the `flow` section.
tenant	`any`		A tenant to use for the operation. May be a template or a literal value.
input	`any`		A template for the input.

### Introspection Target: `Ash.Flow.Step.Update` ## steps.destroy ```elixir destroy name, resource, action ``` Declares a step that will call a destroy action on a resource. ### Examples ``` destroy :destroy_post, MyApp.Post, :destroy ``` ### Arguments

Name	Type	Docs
name ^*	`atom`	The name of the step. Will be used when expressing dependencies, and step inputs.
resource ^*	`any`	The resource to call the action on.
action ^*	`any`	The action to call on the resource.

### Options

Name	Type	Default	Docs
record ^*	`any`		The record to be updated, can use template helpers, e.g `result(:step_name)`.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.
api	`any`		The api to use when calling the action. Defaults to the api set in the `flow` section.
tenant	`any`		A tenant to use for the operation. May be a template or a literal value.
input	`any`		A template for the input.

### Introspection Target: `Ash.Flow.Step.Destroy` ## steps.validate ```elixir validate name, resource, action ``` Validates some input against an action. ### Examples ``` validate :update_post, MyApp.Post, :update do record result(:get_post) only_keys [:name] end ``` ### Arguments

Name	Type	Docs
name ^*	`atom`	The name of the step. Will be used when expressing dependencies, and step inputs.
resource ^*	`any`	The resource to call the action on.
action ^*	`any`	The action to call on the resource.

### Options

Name	Type	Default	Docs
record	`any`		The record to be created/updated/destroyed. 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.
only_keys	`list(atom \| list(atom))`		A list of keys or paths to keys that should be validated. Others will be ignored, and errors generated for other fields will be ignored.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.
api	`any`		The api to use when calling the action. Defaults to the api set in the `flow` section.
tenant	`any`		A tenant to use for the operation. May be a template or a literal value.
input	`any`		A template for the input.

### Introspection Target: `Ash.Flow.Step.Update` ## steps.read ```elixir read name, resource, action ``` Declares a step that will call a read action on a resource. ### Examples ``` read :destroy_post, MyApp.Post, :destroy ``` ### Arguments

Name	Type	Docs
name ^*	`atom`	The name of the step. Will be used when expressing dependencies, and step inputs.
resource ^*	`any`	The resource to call the action on.
action ^*	`any`	The action to call on the resource.

### Options

Name	Type	Default	Docs
get?	`boolean`	`false`	Whether or not read action is expected to return a single result or `nil`. Set to `true` automatically if `get? true`.
not_found_error?	`boolean`	`true`	Whether or not finding no record should result in a not found error
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.
api	`any`		The api to use when calling the action. Defaults to the api set in the `flow` section.
tenant	`any`		A tenant to use for the operation. May be a template or a literal value.
input	`any`		A template for the input.

### Introspection Target: `Ash.Flow.Step.Read` ## steps.run_flow ```elixir run_flow name, 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) } ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.
flow ^*	`atom`		The flow to run.

### Options

Name	Type	Default	Docs
input	`any`		A template for the input.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.RunFlow` ## steps.custom ```elixir custom name, 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 ``` ### Arguments

Name	Type	Default	Docs
name ^*	`atom`		The name of the step. Will be used when expressing dependencies, and step inputs.
custom	`(any, any -> any) \| module`		The module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context.

### Options

Name	Type	Default	Docs
input	`any`		A template for the input.
async?	`boolean`	`false`	Whether or not this step can be run outside of the current process.
short_name	`String.t`		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for	`any`		Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resources	`list(atom)`		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	`any`		Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more.
halt_reason	`any`	`:halted`	Configures the reason for the `halt_if` clause.
description	`String.t`		A description for the step.

### Introspection Target: `Ash.Flow.Step.Custom`