docs: update cheat shets fix: honor tenant option on aggregates closes #805
29 KiB
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
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
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