View Source DSL: Ash.Flow.Dsl

flow

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

Nested DSLs

Options

NameTypeDefaultDocs
apimoduleAn api to use by default when calling actions
descriptionString.tA description of the flow
trace_nameString.tThe name to use when creating traces. Defaults to the short name.
short_nameatomA short name to use for the flow. Defaults to the last to parts of the module name, underscored.
returnsanyThe 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

NameTypeDefaultDocs
nameatomThe name to use for the argument
typemoduleThe type of the argument. See Ash.Type for more.

Options

NameTypeDefaultDocs
default(-> any) | mfa | any()A default value to use for the argument if not provided
allow_nil?booleantrueWhether or not the argument value may be nil
constraintsKeyword.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

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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
overanyThe value to be iterated over. Will be available inside the map step as element(:map_step_name)

Options

NameTypeDefaultDocs
outputatomWhich step to use when constructing the output list. Defaults to the last step.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
conditionanyA template that must evaluate to true for the branch to be executed.

Options

NameTypeDefaultDocs
outputatomWhich step to use as the output. Defaults to the last step.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourcemodule | list(module)The Ash resource to use for the transaction.

Options

NameTypeDefaultDocs
outputanyWhich step or steps to use when constructing the output. Defaults to the last step.
timeouttimeoutA timeout to apply to the transaction.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourceanyThe resource to call the action on.
actionanyThe action to call on the resource.

Options

NameTypeDefaultDocs
upsert?booleanfalseWhether or not this action is always an upsert.
upsert_identityatomThe identity to use for the upsert.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.
apianyThe api to use when calling the action. Defaults to the api set in the flow section.
tenantanyA tenant to use for the operation. May be a template or a literal value.
inputanyA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.

Options

NameTypeDefaultDocs
inputanyA template for the input.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
halt_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourceanyThe resource to call the action on.
actionanyThe action to call on the resource.

Options

NameTypeDefaultDocs
recordanyThe record to be updated, can use template helpers, e.g result(:step_name).
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.
apianyThe api to use when calling the action. Defaults to the api set in the flow section.
tenantanyA tenant to use for the operation. May be a template or a literal value.
inputanyA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourceanyThe resource to call the action on.
actionanyThe action to call on the resource.

Options

NameTypeDefaultDocs
recordanyThe record to be updated, can use template helpers, e.g result(:step_name).
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.
apianyThe api to use when calling the action. Defaults to the api set in the flow section.
tenantanyA tenant to use for the operation. May be a template or a literal value.
inputanyA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourceanyThe resource to call the action on.
actionanyThe action to call on the resource.

Options

NameTypeDefaultDocs
recordanyThe 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_keyslist(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_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.
apianyThe api to use when calling the action. Defaults to the api set in the flow section.
tenantanyA tenant to use for the operation. May be a template or a literal value.
inputanyA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
resourceanyThe resource to call the action on.
actionanyThe action to call on the resource.

Options

NameTypeDefaultDocs
get?booleanfalseWhether or not read action is expected to return a single result or nil. Set to true automatically if get? true.
not_found_error?booleantrueWhether or not finding no record should result in a not found error
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.
apianyThe api to use when calling the action. Defaults to the api set in the flow section.
tenantanyA tenant to use for the operation. May be a template or a literal value.
inputanyA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
flowatomThe flow to run.

Options

NameTypeDefaultDocs
inputanyA template for the input.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA 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

NameTypeDefaultDocs
nameatomThe name of the step. Will be used when expressing dependencies, and step inputs.
custom(any, any -> any) | moduleThe module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context.

Options

NameTypeDefaultDocs
inputanyA template for the input.
async?booleanfalseWhether or not this step can be run outside of the current process.
short_nameString.tSet a short name for the step. Will be used when building things like mermaid charts.
wait_foranyEnsures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited.
touches_resourceslist(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_ifanyHalts the step by emitting an error (with an Ash.Error.Flow.Halted). Can use template variables. See the section on Halting for more.
halt_reasonany:haltedConfigures the reason for the halt_if clause.
descriptionString.tA description for the step.

Introspection

Target: Ash.Flow.Step.Custom