Table of Contents
DSL: Ash.Flow.Dsl
flow
Details about the flow itself, like description and the successful return type.
Nested DSLs
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. |
flow.argument
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 |
[] |
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
Examples
steps do
# invokes a create action
create :create_post, MyApp.Post, :create
end
steps.map
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
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
transaction name, resource
Runs a set of steps in a transaction.
Examples
transaction :create_user_with_org do
touches_resources [User, Org]
create :create_user, User, :create do
input %{
first_name: {Faker.Person, :first_name, []},
last_name: {Faker.Person, :last_name, []}
}
end
create :create_org, Org, :create do
input %{
user_id: path(result(:create_user), :id),
name: {Faker.Color, :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
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 | 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. |
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
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
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 | 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. |
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
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 | 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. |
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
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 | 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. |
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
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 | 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. |
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
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
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