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


---

 * [argument](#flow-argument)

### Examples


### Reference
| Name | Type | 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

Introspection Target: `Ash.Flow.Argument`

An argument to be passed into the flow


---



### Examples
```
argument :params, :map do
  default %{}
end

```


```
argument :retries, :integer do
  allow_nil? false
end

```


### Reference
| 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. |






## steps

---

 * [map](#steps-map)

 * [branch](#steps-branch)

 * [transaction](#steps-transaction)

 * [create](#steps-create)
 * [debug](#steps-debug)
 * [update](#steps-update)
 * [destroy](#steps-destroy)
 * [validate](#steps-validate)
 * [read](#steps-read)
 * [run_flow](#steps-run_flow)
 * [custom](#steps-custom)

### Examples
```
steps do
  # invokes a create action
  create :create_post, MyApp.Post, :create
end

```



## steps.map

Introspection Target: `Ash.Flow.Step.Map`

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

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| 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. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |



## steps.branch

Introspection Target: `Ash.Flow.Step.Branch`

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

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| 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. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |



## steps.transaction

Introspection Target: `Ash.Flow.Step.Transaction`

Runs a set of steps in a transaction.


---



### Examples
```
transaction :create_users do
  create :create_user, User, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end

  create :create_user, Org, :create do
    input %{
      first_name: {Faker.Person, :first_name, []},
      last_name: {Faker.Person, :last_name, []}
    }
  end
end

```


### Reference
| 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. |
| resource | `module \| list(module)` |  | The Ash resource to use for the transaction. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |



## steps.create

Introspection Target: `Ash.Flow.Step.Create`

Declares a step that will call a create action on a resource.


---



### Examples
```
create :create_post, MyApp.Post, :create

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| upsert? | `boolean` | false | Wether or not this action is always an upsert. |
| upsert_identity | `atom` |  | The identity to use for the upsert. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |
| resource | ``any`` |  | The resource to call the action on. |
| action | ``any`` |  | The action to call on the resource. |
| 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. |



## steps.debug

Introspection Target: `Ash.Flow.Step.Debug`

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

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| input | ``any`` |  | A template for the input. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |



## steps.update

Introspection Target: `Ash.Flow.Step.Update`

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

```


### Reference
| 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. |
| 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. |
| resource | ``any`` |  | The resource to call the action on. |
| action | ``any`` |  | The action to call on the resource. |
| 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. |



## steps.destroy

Introspection Target: `Ash.Flow.Step.Destroy`

Declares a step that will call a destroy action on a resource.


---



### Examples
```
destroy :destroy_post, MyApp.Post, :destroy

```


### Reference
| 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. |
| 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. |
| resource | ``any`` |  | The resource to call the action on. |
| action | ``any`` |  | The action to call on the resource. |
| 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. |



## steps.validate

Introspection Target: `Ash.Flow.Step.Update`

Validates some input against an action.


---



### Examples
```
validate :update_post, MyApp.Post, :update do
  record result(:get_post)
  only_keys [:name]
end

```


### Reference
| 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. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |
| resource | ``any`` |  | The resource to call the action on. |
| action | ``any`` |  | The action to call on the resource. |
| 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. |



## steps.read

Introspection Target: `Ash.Flow.Step.Read`

Declares a step that will call a read action on a resource.


---



### Examples
```
read :destroy_post, MyApp.Post, :destroy

```


### Reference
| 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 |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |
| resource | ``any`` |  | The resource to call the action on. |
| action | ``any`` |  | The action to call on the resource. |
| 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. |



## steps.run_flow

Introspection Target: `Ash.Flow.Step.RunFlow`

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)
  }

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| flow | `atom` |  | The flow to run. |
| input | ``any`` |  | A template for the input. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |



## steps.custom

Introspection Target: `Ash.Flow.Step.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

```


### Reference
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| input | ``any`` |  | A template for the input. |
| 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. |
| async? | `boolean` | false | Whether or not this step can be run outside of the current process. |
| name | `atom` |  | The name of the step. Will be used when expressing dependencies, and step inputs. |
| 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. |