ash/documentation/dsls/DSL:-Ash.Flow.md

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

Options

Name	Type	Default	Docs
api{: #flow-api }	module		An api to use by default when calling actions
description{: #flow-description }	String.t		A description of the flow
trace_name{: #flow-trace_name }	String.t		The name to use when creating traces. Defaults to the short name.
short_name{: #flow-short_name }	atom		A short name to use for the flow. Defaults to the last to parts of the module name, underscored.
returns{: #flow-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{: #flow-argument-name .spark-required}	atom		The name to use for the argument
type{: #flow-argument-type .spark-required}	module		The type of the argument. See Ash.Type for more.

Options

Name	Type	Default	Docs
default{: #flow-argument-default }	(-> any) | mfa | any()		A default value to use for the argument if not provided
allow_nil?{: #flow-argument-allow_nil? }	boolean	true	Whether or not the argument value may be nil
constraints{: #flow-argument-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

• 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

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{: #steps-map-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
over{: #steps-map-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{: #steps-map-output }	atom		Which step to use when constructing the output list. Defaults to the last step.
short_name{: #steps-map-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-map-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{: #steps-map-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{: #steps-map-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{: #steps-map-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-map-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{: #steps-branch-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
condition{: #steps-branch-condition }	any		A template that must evaluate to true for the branch to be executed.

Options

Name	Type	Default	Docs
output{: #steps-branch-output }	atom		Which step to use as the output. Defaults to the last step.
short_name{: #steps-branch-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-branch-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{: #steps-branch-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{: #steps-branch-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{: #steps-branch-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-branch-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{: #steps-transaction-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-transaction-resource }	module | list(module)		The Ash resource to use for the transaction.

Options

Name	Type	Default	Docs
output{: #steps-transaction-output }	any		Which step or steps to use when constructing the output. Defaults to the last step.
timeout{: #steps-transaction-timeout }	timeout		A timeout to apply to the transaction.
short_name{: #steps-transaction-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-transaction-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{: #steps-transaction-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{: #steps-transaction-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{: #steps-transaction-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-transaction-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{: #steps-create-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-create-resource .spark-required}	any		The resource to call the action on.
action{: #steps-create-action .spark-required}	any		The action to call on the resource.

Options

Name	Type	Default	Docs
upsert?{: #steps-create-upsert? }	boolean	false	Whether or not this action is always an upsert.
upsert_identity{: #steps-create-upsert_identity }	atom		The identity to use for the upsert.
short_name{: #steps-create-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-create-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{: #steps-create-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{: #steps-create-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{: #steps-create-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-create-description }	String.t		A description for the step.
api{: #steps-create-api }	any		The api to use when calling the action. Defaults to the api set in the flow section.
tenant{: #steps-create-tenant }	any		A tenant to use for the operation. May be a template or a literal value.
input{: #steps-create-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{: #steps-debug-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.

Options

Name	Type	Default	Docs
input{: #steps-debug-input }	any		A template for the input.
short_name{: #steps-debug-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-debug-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{: #steps-debug-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{: #steps-debug-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-debug-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{: #steps-update-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-update-resource .spark-required}	any		The resource to call the action on.
action{: #steps-update-action .spark-required}	any		The action to call on the resource.

Options

Name	Type	Default	Docs
record{: #steps-update-record .spark-required}	any		The record to be updated, can use template helpers, e.g result(:step_name).
short_name{: #steps-update-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-update-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{: #steps-update-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{: #steps-update-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{: #steps-update-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-update-description }	String.t		A description for the step.
api{: #steps-update-api }	any		The api to use when calling the action. Defaults to the api set in the flow section.
tenant{: #steps-update-tenant }	any		A tenant to use for the operation. May be a template or a literal value.
input{: #steps-update-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{: #steps-destroy-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-destroy-resource .spark-required}	any		The resource to call the action on.
action{: #steps-destroy-action .spark-required}	any		The action to call on the resource.

Options

Name	Type	Default	Docs
record{: #steps-destroy-record .spark-required}	any		The record to be updated, can use template helpers, e.g result(:step_name).
short_name{: #steps-destroy-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-destroy-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{: #steps-destroy-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{: #steps-destroy-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{: #steps-destroy-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-destroy-description }	String.t		A description for the step.
api{: #steps-destroy-api }	any		The api to use when calling the action. Defaults to the api set in the flow section.
tenant{: #steps-destroy-tenant }	any		A tenant to use for the operation. May be a template or a literal value.
input{: #steps-destroy-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{: #steps-validate-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-validate-resource .spark-required}	any		The resource to call the action on.
action{: #steps-validate-action .spark-required}	any		The action to call on the resource.

Options

Name	Type	Default	Docs
record{: #steps-validate-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{: #steps-validate-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{: #steps-validate-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-validate-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{: #steps-validate-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{: #steps-validate-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{: #steps-validate-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-validate-description }	String.t		A description for the step.
api{: #steps-validate-api }	any		The api to use when calling the action. Defaults to the api set in the flow section.
tenant{: #steps-validate-tenant }	any		A tenant to use for the operation. May be a template or a literal value.
input{: #steps-validate-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{: #steps-read-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
resource{: #steps-read-resource .spark-required}	any		The resource to call the action on.
action{: #steps-read-action .spark-required}	any		The action to call on the resource.

Options

Name	Type	Default	Docs
get?{: #steps-read-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?{: #steps-read-not_found_error? }	boolean	true	Whether or not finding no record should result in a not found error
short_name{: #steps-read-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-read-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{: #steps-read-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{: #steps-read-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{: #steps-read-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-read-description }	String.t		A description for the step.
api{: #steps-read-api }	any		The api to use when calling the action. Defaults to the api set in the flow section.
tenant{: #steps-read-tenant }	any		A tenant to use for the operation. May be a template or a literal value.
input{: #steps-read-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{: #steps-run_flow-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
flow{: #steps-run_flow-flow .spark-required}	atom		The flow to run.

Options

Name	Type	Default	Docs
input{: #steps-run_flow-input }	any		A template for the input.
short_name{: #steps-run_flow-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-run_flow-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{: #steps-run_flow-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{: #steps-run_flow-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{: #steps-run_flow-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-run_flow-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{: #steps-custom-name .spark-required}	atom		The name of the step. Will be used when expressing dependencies, and step inputs.
custom{: #steps-custom-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{: #steps-custom-input }	any		A template for the input.
async?{: #steps-custom-async? }	boolean	false	Whether or not this step can be run outside of the current process.
short_name{: #steps-custom-short_name }	String.t		Set a short name for the step. Will be used when building things like mermaid charts.
wait_for{: #steps-custom-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{: #steps-custom-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{: #steps-custom-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{: #steps-custom-halt_reason }	any	:halted	Configures the reason for the halt_if clause.
description{: #steps-custom-description }	String.t		A description for the step.

Introspection

Target: Ash.Flow.Step.Custom