View Source DSL: Ash.Flow.Dsl

flow

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

Nested DSLs

• 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.

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

• 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	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