Choices And Conditions
View SourceOverview
A Choice evaluates conditions in author order. It runs the first matching Action. A required fallback handles the no-match case.
Run the cells from top to bottom.
Install The Package
Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])Define A Routing Action
defmodule FlowChoices.Route do
use Jido.Action, name: "flow_choices_route"
@impl true
def run(params, _context), do: {:ok, params}
endDeclare Ordered Options
defmodule FlowChoices.Example do
use Jido.Flow, name: "flow_choices_example"
flow do
choice "route" do
option "urgent",
condition: input(:priority) >= 90,
action: FlowChoices.Route,
params: %{queue: :urgent, id: input(:id)}
option "priority",
condition: input(:priority) >= 50,
action: FlowChoices.Route,
params: %{queue: :priority, id: input(:id)}
otherwise action: FlowChoices.Route, params: %{queue: :standard, id: input(:id)}
end
output(%{route: result("route")})
end
end{:ok, urgent} =
Jido.Exec.run(FlowChoices.Example, %{id: 1, priority: 100})
{:ok, standard} =
Jido.Exec.run(FlowChoices.Example, %{id: 2, priority: 10})
{urgent, standard}When two conditions match, only the first option runs. Jido does not evaluate later options after a match.
Result references in every option and in the fallback become static graph dependencies. The referenced components run before Choice selection, even when Jido does not select the option that contains a reference. Put work that must stay lazy inside the selected Action.
Condition Grammar
The DSL accepts:
== != < <= > >= in
and or not
eq neq lt lte gt gte
all anyConditions compare Flow expressions. They do not call application functions. Put complex or effectful decisions in an Action before the Choice, then test that Action result.
With the expression API, not also accepts a Boolean reference. Direct
Boolean references and literals are valid conditions:
condition: not input(:enabled)
# In an Iterate component:
while not state(:done)Declare the field as a required Zoi.boolean() in the Flow input schema,
the producing Action's output schema, or the Iterate State schema. For example,
Zoi.object(%{enabled: Zoi.boolean()}) rejects missing and non-Boolean input.
The direct condition rejects a non-Boolean value. An explicit comparison
such as input(:enabled) == false keeps its existing equality behavior and
does not validate the type. A missing reference still fails. The expression
API requires 3.0.0-beta.6 or later; see
Expressions.
Fallback Is Routing
otherwise is mandatory. It is the normal route when no option matches. It is
not an error handler. If a selected Action fails, the Choice fails and does
not run the fallback.
Choice option and fallback targets must be Actions. A Choice does not derive a Subflow target.
Choice options and fallback use Action modules. Put their Flow inputs in
params. Only the selected Action runs. A fallback remains a normal route,
not an error handler.
Route An Expected Failure As Data
Keep expected provider outcomes in the application's result contract. A small Action wrapper can convert a specific error to data that Choice can inspect. Return other errors unchanged. Do not catch all exceptions or use Choice fallback as recovery from a failed target.
This local provider has no external effects:
defmodule FlowChoices.Provider do
def fetch(:missing),
do: {:error, Jido.Action.Error.validation_error("not found", code: :not_found)}
def fetch(:offline),
do: {:error, Jido.Action.Error.execution_error("offline", retry: true)}
def fetch(id), do: {:ok, %{id: id}}
end
defmodule FlowChoices.Fetch do
use Jido.Action, name: "flow_choices_fetch"
@impl true
def run(%{id: id}, _context) do
case FlowChoices.Provider.fetch(id) do
{:ok, value} ->
{:ok, %{status: :ok, value: value, error: nil}}
{:error, %Jido.Action.Error.InvalidInputError{details: %{code: :not_found}} = error} ->
{:ok, %{status: :error, value: nil, error: Jido.Flow.Error.to_map(error)}}
{:error, error} ->
{:error, error}
end
end
end
defmodule FlowChoices.ExpectedFailure do
use Jido.Flow, name: "flow_choices_expected_failure"
flow do
step "fetch", action: FlowChoices.Fetch, params: %{id: input(:id)}
choice "route" do
option "missing",
condition: result("fetch", :status) == :error,
action: FlowChoices.Route,
params: %{route: :missing, error: result("fetch", :error)}
otherwise action: FlowChoices.Route, params: %{route: :found, value: result("fetch", :value)}
end
output(result("route"))
end
end{:ok, %{route: :found, value: %{id: 1}}} =
Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: 1})
{:ok, %{route: :missing, error: %{type: :validation_error, details: %{code: :not_found}}}} =
Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: :missing})
{:error, %Jido.Action.Error.ExecutionFailureError{}} =
Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: :offline})The wrapper preserves the expected error's mapped type, message, details, and
retry flag. This result is successful application data, not a failed Flow
node. It does not receive automatic error telemetry or added node/execution
identity. Add application correlation data explicitly when needed. A selected
route that fails still fails the Flow; it does not run otherwise.
The provider above is an ordinary function. If the provider is another Jido
Action, do not call its run/2 callback and assume validation occurred. Use
its validation boundary, or move the shared provider operation to an ordinary
function. There is no on_error: :capture option on Step or Choice.
Canonical Form
A Jido.Flow.Choice contains ordered Jido.Flow.Choice.Option values and one
Jido.Flow.Choice.Fallback. Use their constructors for direct authoring or use
option and fallback maps for data authoring.
Expression Result Types
Conditions must produce a Boolean. Native and and or can return their
right operand unchanged: true and 123 evaluates to 123 and is rejected at
the condition boundary. The same expression is valid inside a data map.
See Expressions for the V3 beta behavior corrections.