# 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 | Default | 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. |
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. | ||
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. |
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)` | ||
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. |
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. | ||
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
name * |
atom
|
The name of the step. Will be used when expressing dependencies, and step inputs. | ||
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. | ||
resource |
list(module) | module
|
The Ash resource to use for 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. |
Name | Type | Default | 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. | ||
upsert? |
boolean
|
false
|
Wether 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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
name * |
atom
|
The name of the step. Will be used when expressing dependencies, and step inputs. | ||
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
record * |
`any`
|
The record to be updated, can use template helpers, e.g `result(:step_name)`. | ||
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. | ||
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
record * |
`any`
|
The record to be updated, can use template helpers, e.g `result(:step_name)`. | ||
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. | ||
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. |
Name | Type | Default | 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. | ||
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(list(atom) | 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. |
Name | Type | Default | 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. | ||
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
flow * |
atom
|
The flow to run. | ||
name * |
atom
|
The name of the step. Will be used when expressing dependencies, and step inputs. | ||
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
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. |
Name | Type | Default | Docs | |
---|---|---|---|---|
name * |
atom
|
The name of the step. Will be used when expressing dependencies, and step inputs. | ||
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. |