mirror of
https://github.com/ash-project/ash.git
synced 2024-09-20 13:33:20 +12:00
549 lines
20 KiB
Text
549 lines
20 KiB
Text
# 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. |
|
|
|
|
|
|
|
|
|
|
|
|
|